ipc/glue/nsIIPCSerializableInputStream.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   5  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_ipc_nsIIPCSerializableInputStream_h
   8 #define mozilla_ipc_nsIIPCSerializableInputStream_h
   9
  10 #include "mozilla/Attributes.h"
  11 #include "mozilla/Maybe.h"
  12 #include "nsISupports.h"
  13 #include "nsTArrayForwardDeclare.h"
  14
  15 namespace mozilla {
  16 namespace ipc {
  17
  18 class FileDescriptor;
  19 class InputStreamParams;
  20
  21 }  // namespace ipc
  22
  23 }  // namespace mozilla
  24
  25 #define NS_IIPCSERIALIZABLEINPUTSTREAM_IID           \
  26   {                                                  \
  27     0xb0211b14, 0xea6d, 0x40d4, {                    \
  28       0x87, 0xb5, 0x7b, 0xe3, 0xdf, 0xac, 0x09, 0xd1 \
  29     }                                                \
  30   }
  31
  32 class NS_NO_VTABLE nsIIPCSerializableInputStream : public nsISupports {
  33  public:
  34   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IIPCSERIALIZABLEINPUTSTREAM_IID)
  35
  36   // Determine the serialized complexity of this input stream, initializing
  37   // `*aSizeUsed`, `*aPipes` and `*aTransferables` to the number of inline
  38   // bytes/pipes/transferable resources which would be used. This will be used
  39   // by other `Serialize` implementations to potentially simplify the resulting
  40   // stream, reducing the number of pipes or file descriptors required.
  41   //
  42   // Each outparameter corresponds to a type of resource which will be included
  43   // in the serialized message, as follows:
  44   //
  45   // *aSizeUsed:
  46   //    Raw bytes to be included inline in the message's payload, usually in the
  47   //    form of a nsCString for a StringInputStreamParams. This must be less
  48   //    than or equal to `aMaxSize`. Larger payloads should instead be
  49   //    serialized using SerializeInputStreamAsPipe.
  50   // *aPipes:
  51   //    New pipes, created using SerializeInputStreamAsPipe, which will be used
  52   //    to asynchronously transfer part of the pipe over IPC. Callers such as
  53   //    nsMultiplexInputStream may choose to serialize themselves as a DataPipe
  54   //    if they contain DataPipes themselves, so existing DataPipe instances
  55   //    which are cheaply transferred should be counted as transferrables.
  56   // *aTransferables:
  57   //    Existing objects which can be more cheaply transferred over IPC than by
  58   //    serializing them inline in a payload or transferring them through a new
  59   //    DataPipe. This includes RemoteLazyInputStreams, FileDescriptors, and
  60   //    existing DataPipeReceiver instances.
  61   //
  62   // Callers of this method must have initialized all of `*aSizeUsed`,
  63   // `*aPipes`, and `*aTransferables` to 0, so implementations are not required
  64   // to initialize all outparameters. The outparameters must not be null.
  65   virtual void SerializedComplexity(uint32_t aMaxSize, uint32_t* aSizeUsed,
  66                                     uint32_t* aPipes,
  67                                     uint32_t* aTransferables) = 0;
  68
  69   virtual void Serialize(mozilla::ipc::InputStreamParams& aParams,
  70                          uint32_t aMaxSize, uint32_t* aSizeUsed) = 0;
  71
  72   virtual bool Deserialize(const mozilla::ipc::InputStreamParams& aParams) = 0;
  73 };
  74
  75 NS_DEFINE_STATIC_IID_ACCESSOR(nsIIPCSerializableInputStream,
  76                               NS_IIPCSERIALIZABLEINPUTSTREAM_IID)
  77
  78 #define NS_DECL_NSIIPCSERIALIZABLEINPUTSTREAM                               \
  79   virtual void SerializedComplexity(uint32_t aMaxSize, uint32_t* aSizeUsed, \
  80                                     uint32_t* aPipes,                       \
  81                                     uint32_t* aTransferrables) override;    \
  82   virtual void Serialize(mozilla::ipc::InputStreamParams&, uint32_t,        \
  83                          uint32_t*) override;                               \
  84                                                                             \
  85   virtual bool Deserialize(const mozilla::ipc::InputStreamParams&) override;
  86
  87 #define NS_FORWARD_NSIIPCSERIALIZABLEINPUTSTREAM(_to)                       \
  88   virtual void SerializedComplexity(uint32_t aMaxSize, uint32_t* aSizeUsed, \
  89                                     uint32_t* aPipes,                       \
  90                                     uint32_t* aTransferables) override {    \
  91     _to SerializedComplexity(aMaxSize, aSizeUsed, aPipes, aTransferables);  \
  92   };                                                                        \
  93                                                                             \
  94   virtual void Serialize(mozilla::ipc::InputStreamParams& aParams,          \
  95                          uint32_t aMaxSize, uint32_t* aSizeUsed) override { \
  96     _to Serialize(aParams, aMaxSize, aSizeUsed);                            \
  97   }                                                                         \
  98                                                                             \
  99   virtual bool Deserialize(const mozilla::ipc::InputStreamParams& aParams)  \
 100       override {                                                            \
 101     return _to Deserialize(aParams);                                        \
 102   }
 103
 104 #endif  // mozilla_ipc_nsIIPCSerializableInputStream_h