michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsIBinaryOutputStream.idl"
michael@0: 
michael@0: /**
michael@0:  * @See nsIObjectInputStream
michael@0:  * @See nsIBinaryOutputStream
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(92c898ac-5fde-4b99-87b3-5d486422094b)]
michael@0: interface nsIObjectOutputStream : nsIBinaryOutputStream
michael@0: {
michael@0:     /**
michael@0:      * Write the object whose "root" or XPCOM-identity nsISupports is aObject.
michael@0:      * The cause for writing this object is a strong or weak reference, so the
michael@0:      * aIsStrongRef argument must tell which kind of pointer is being followed
michael@0:      * here during serialization.
michael@0:      *
michael@0:      * If the object has only one strong reference in the serialization and no
michael@0:      * weak refs, use writeSingleRefObject.  This is a valuable optimization:
michael@0:      * it saves space in the stream, and cycles on both ends of the process.
michael@0:      *
michael@0:      * If the reference being serialized is a pointer to an interface not on
michael@0:      * the primary inheritance chain ending in the root nsISupports, you must
michael@0:      * call writeCompoundObject instead of this method.
michael@0:      */
michael@0:     void writeObject(in nsISupports aObject, in boolean aIsStrongRef);
michael@0: 
michael@0:     /**
michael@0:      * Write an object referenced singly and strongly via its root nsISupports
michael@0:      * or a subclass of its root nsISupports.  There must not be other refs to
michael@0:      * aObject in memory, or in the serialization.
michael@0:      */
michael@0:     void writeSingleRefObject(in nsISupports aObject);
michael@0: 
michael@0:     /**
michael@0:      * Write the object referenced by an interface pointer at aObject that
michael@0:      * inherits from a non-primary nsISupports, i.e., a reference to one of
michael@0:      * the multiply inherited interfaces derived from an nsISupports other
michael@0:      * than the root or XPCOM-identity nsISupports; or a reference to an
michael@0:      * inner object in the case of true XPCOM aggregation.  aIID identifies
michael@0:      * this interface.
michael@0:      */
michael@0:     void writeCompoundObject(in nsISupports aObject,
michael@0:                              in nsIIDRef aIID,
michael@0:                              in boolean aIsStrongRef);
michael@0: 
michael@0:     void writeID(in nsIDRef aID);
michael@0: 
michael@0:     /**
michael@0:      * Optimized serialization support -- see nsIStreamBufferAccess.idl.
michael@0:      */
michael@0:     [notxpcom] charPtr getBuffer(in uint32_t aLength, in uint32_t aAlignMask);
michael@0:     [notxpcom] void    putBuffer(in charPtr aBuffer, in uint32_t aLength);
michael@0: };
michael@0: 
michael@0: %{C++
michael@0: 
michael@0: inline nsresult
michael@0: NS_WriteOptionalObject(nsIObjectOutputStream* aStream, nsISupports* aObject,
michael@0:                        bool aIsStrongRef)
michael@0: {
michael@0:     bool nonnull = (aObject != nullptr);
michael@0:     nsresult rv = aStream->WriteBoolean(nonnull);
michael@0:     if (NS_SUCCEEDED(rv) && nonnull)
michael@0:         rv = aStream->WriteObject(aObject, aIsStrongRef);
michael@0:     return rv;
michael@0: }
michael@0: 
michael@0: inline nsresult
michael@0: NS_WriteOptionalSingleRefObject(nsIObjectOutputStream* aStream,
michael@0:                                 nsISupports* aObject)
michael@0: {
michael@0:     bool nonnull = (aObject != nullptr);
michael@0:     nsresult rv = aStream->WriteBoolean(nonnull);
michael@0:     if (NS_SUCCEEDED(rv) && nonnull)
michael@0:         rv = aStream->WriteSingleRefObject(aObject);
michael@0:     return rv;
michael@0: }
michael@0: 
michael@0: inline nsresult
michael@0: NS_WriteOptionalCompoundObject(nsIObjectOutputStream* aStream,
michael@0:                                nsISupports* aObject,
michael@0:                                const nsIID& aIID,
michael@0:                                bool aIsStrongRef)
michael@0: {
michael@0:     bool nonnull = (aObject != nullptr);
michael@0:     nsresult rv = aStream->WriteBoolean(nonnull);
michael@0:     if (NS_SUCCEEDED(rv) && nonnull)
michael@0:         rv = aStream->WriteCompoundObject(aObject, aIID, aIsStrongRef);
michael@0:     return rv;
michael@0: }
michael@0: 
michael@0: %}