xpcom/io/nsIObjectOutputStream.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsIBinaryOutputStream.idl"
   7
   8 /**
   9  * @See nsIObjectInputStream
  10  * @See nsIBinaryOutputStream
  11  */
  12
  13 [scriptable, uuid(92c898ac-5fde-4b99-87b3-5d486422094b)]
  14 interface nsIObjectOutputStream : nsIBinaryOutputStream
  15 {
  16     /**
  17      * Write the object whose "root" or XPCOM-identity nsISupports is aObject.
  18      * The cause for writing this object is a strong or weak reference, so the
  19      * aIsStrongRef argument must tell which kind of pointer is being followed
  20      * here during serialization.
  21      *
  22      * If the object has only one strong reference in the serialization and no
  23      * weak refs, use writeSingleRefObject.  This is a valuable optimization:
  24      * it saves space in the stream, and cycles on both ends of the process.
  25      *
  26      * If the reference being serialized is a pointer to an interface not on
  27      * the primary inheritance chain ending in the root nsISupports, you must
  28      * call writeCompoundObject instead of this method.
  29      */
  30     void writeObject(in nsISupports aObject, in boolean aIsStrongRef);
  31
  32     /**
  33      * Write an object referenced singly and strongly via its root nsISupports
  34      * or a subclass of its root nsISupports.  There must not be other refs to
  35      * aObject in memory, or in the serialization.
  36      */
  37     void writeSingleRefObject(in nsISupports aObject);
  38
  39     /**
  40      * Write the object referenced by an interface pointer at aObject that
  41      * inherits from a non-primary nsISupports, i.e., a reference to one of
  42      * the multiply inherited interfaces derived from an nsISupports other
  43      * than the root or XPCOM-identity nsISupports; or a reference to an
  44      * inner object in the case of true XPCOM aggregation.  aIID identifies
  45      * this interface.
  46      */
  47     void writeCompoundObject(in nsISupports aObject,
  48                              in nsIIDRef aIID,
  49                              in boolean aIsStrongRef);
  50
  51     void writeID(in nsIDRef aID);
  52
  53     /**
  54      * Optimized serialization support -- see nsIStreamBufferAccess.idl.
  55      */
  56     [notxpcom] charPtr getBuffer(in uint32_t aLength, in uint32_t aAlignMask);
  57     [notxpcom] void    putBuffer(in charPtr aBuffer, in uint32_t aLength);
  58 };
  59
  60 %{C++
  61
  62 inline nsresult
  63 NS_WriteOptionalObject(nsIObjectOutputStream* aStream, nsISupports* aObject,
  64                        bool aIsStrongRef)
  65 {
  66     bool nonnull = (aObject != nullptr);
  67     nsresult rv = aStream->WriteBoolean(nonnull);
  68     if (NS_SUCCEEDED(rv) && nonnull)
  69         rv = aStream->WriteObject(aObject, aIsStrongRef);
  70     return rv;
  71 }
  72
  73 inline nsresult
  74 NS_WriteOptionalSingleRefObject(nsIObjectOutputStream* aStream,
  75                                 nsISupports* aObject)
  76 {
  77     bool nonnull = (aObject != nullptr);
  78     nsresult rv = aStream->WriteBoolean(nonnull);
  79     if (NS_SUCCEEDED(rv) && nonnull)
  80         rv = aStream->WriteSingleRefObject(aObject);
  81     return rv;
  82 }
  83
  84 inline nsresult
  85 NS_WriteOptionalCompoundObject(nsIObjectOutputStream* aStream,
  86                                nsISupports* aObject,
  87                                const nsIID& aIID,
  88                                bool aIsStrongRef)
  89 {
  90     bool nonnull = (aObject != nullptr);
  91     nsresult rv = aStream->WriteBoolean(nonnull);
  92     if (NS_SUCCEEDED(rv) && nonnull)
  93         rv = aStream->WriteCompoundObject(aObject, aIID, aIsStrongRef);
  94     return rv;
  95 }
  96
  97 %}