xpcom/io/nsIBinaryOutputStream.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 "nsIOutputStream.idl"
   7
   8 /**
   9  * This interface allows writing of primitive data types (integers,
  10  * floating-point values, booleans, etc.) to a stream in a binary, untagged,
  11  * fixed-endianness format.  This might be used, for example, to implement
  12  * network protocols or to produce architecture-neutral binary disk files,
  13  * i.e. ones that can be read and written by both big-endian and little-endian
  14  * platforms.  Output is written in big-endian order (high-order byte first),
  15  * as this is traditional network order.
  16  *
  17  * @See nsIBinaryInputStream
  18  */
  19
  20 [scriptable, uuid(204ee610-8765-11d3-90cf-0040056a906e)]
  21 interface nsIBinaryOutputStream : nsIOutputStream {
  22     void setOutputStream(in nsIOutputStream aOutputStream);
  23
  24     /**
  25      * Write a boolean as an 8-bit char to the stream.
  26      */
  27     void writeBoolean(in boolean aBoolean);
  28
  29     void write8(in uint8_t aByte);
  30     void write16(in uint16_t a16);
  31     void write32(in uint32_t a32);
  32     void write64(in uint64_t a64);
  33
  34     void writeFloat(in float aFloat);
  35     void writeDouble(in double aDouble);
  36
  37     /**
  38      * Write an 8-bit pascal style string to the stream.
  39      * 32-bit length field, followed by length 8-bit chars.
  40      */
  41     void writeStringZ(in string aString);
  42
  43     /**
  44      * Write a 16-bit pascal style string to the stream.
  45      * 32-bit length field, followed by length PRUnichars.
  46      */
  47     void writeWStringZ(in wstring aString);
  48
  49     /**
  50      * Write an 8-bit pascal style string (UTF8-encoded) to the stream.
  51      * 32-bit length field, followed by length 8-bit chars.
  52      */
  53     void writeUtf8Z(in wstring aString);
  54
  55     /**
  56      * Write an opaque byte array to the stream.
  57      */
  58     void writeBytes([size_is(aLength)] in string aString, in uint32_t aLength);
  59
  60     /**
  61      * Write an opaque byte array to the stream.
  62      */
  63     void writeByteArray([array, size_is(aLength)] in uint8_t aBytes,
  64                         in uint32_t aLength);
  65
  66 };
  67
  68 %{C++
  69
  70 inline nsresult
  71 NS_WriteOptionalStringZ(nsIBinaryOutputStream* aStream, const char* aString)
  72 {
  73     bool nonnull = (aString != nullptr);
  74     nsresult rv = aStream->WriteBoolean(nonnull);
  75     if (NS_SUCCEEDED(rv) && nonnull)
  76         rv = aStream->WriteStringZ(aString);
  77     return rv;
  78 }
  79
  80 inline nsresult
  81 NS_WriteOptionalWStringZ(nsIBinaryOutputStream* aStream, const char16_t* aString)
  82 {
  83     bool nonnull = (aString != nullptr);
  84     nsresult rv = aStream->WriteBoolean(nonnull);
  85     if (NS_SUCCEEDED(rv) && nonnull)
  86         rv = aStream->WriteWStringZ(aString);
  87     return rv;
  88 }
  89
  90 %}