xpcom/io/nsIBinaryOutputStream.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Mozilla Communicator client code, released
  16  * March 31, 1998.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications Corporation.
  20  * Portions created by the Initial Developer are Copyright (C) 1998-1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #include "nsIOutputStream.idl"
  40 #include "nsrootidl.idl"
  41
  42 /**
  43  * This interface allows writing of primitive data types (integers,
  44  * floating-point values, booleans, etc.) to a stream in a binary, untagged,
  45  * fixed-endianness format.  This might be used, for example, to implement
  46  * network protocols or to produce architecture-neutral binary disk files,
  47  * i.e. ones that can be read and written by both big-endian and little-endian
  48  * platforms.  Output is written in big-endian order (high-order byte first),
  49  * as this is traditional network order.
  50  *
  51  * @See nsIBinaryInputStream
  52  */
  53
  54 [scriptable, uuid(204ee610-8765-11d3-90cf-0040056a906e)]
  55 interface nsIBinaryOutputStream : nsIOutputStream {
  56     void setOutputStream(in nsIOutputStream aOutputStream);
  57
  58     /**
  59      * Write a boolean as an 8-bit char to the stream.
  60      */
  61     void writeBoolean(in PRBool aBoolean);
  62
  63     void write8(in PRUint8 aByte);
  64     void write16(in PRUint16 a16);
  65     void write32(in PRUint32 a32);
  66     void write64(in PRUint64 a64);
  67
  68     void writeFloat(in float aFloat);
  69     void writeDouble(in double aDouble);
  70
  71     /**
  72      * Write an 8-bit pascal style string to the stream.
  73      * 32-bit length field, followed by length 8-bit chars.
  74      */
  75     void writeStringZ(in string aString);
  76
  77     /**
  78      * Write a 16-bit pascal style string to the stream.
  79      * 32-bit length field, followed by length PRUnichars.
  80      */
  81     void writeWStringZ(in wstring aString);
  82
  83     /**
  84      * Write an 8-bit pascal style string (UTF8-encoded) to the stream.
  85      * 32-bit length field, followed by length 8-bit chars.
  86      */
  87     void writeUtf8Z(in wstring aString);
  88
  89     /**
  90      * Write an opaque byte array to the stream.
  91      */
  92     void writeBytes([size_is(aLength)] in string aString, in PRUint32 aLength);
  93
  94     /**
  95      * Write an opaque byte array to the stream.
  96      */
  97     void writeByteArray([array, size_is(aLength)] in PRUint8 aBytes,
  98                         in PRUint32 aLength);
  99
 100 };
 101
 102 %{C++
 103
 104 inline nsresult
 105 NS_WriteOptionalStringZ(nsIBinaryOutputStream* aStream, const char* aString)
 106 {
 107     PRBool nonnull = (aString != nsnull);
 108     nsresult rv = aStream->WriteBoolean(nonnull);
 109     if (NS_SUCCEEDED(rv) && nonnull)
 110         rv = aStream->WriteStringZ(aString);
 111     return rv;
 112 }
 113
 114 inline nsresult
 115 NS_WriteOptionalWStringZ(nsIBinaryOutputStream* aStream, const PRUnichar* aString)
 116 {
 117     PRBool nonnull = (aString != nsnull);
 118     nsresult rv = aStream->WriteBoolean(nonnull);
 119     if (NS_SUCCEEDED(rv) && nonnull)
 120         rv = aStream->WriteWStringZ(aString);
 121     return rv;
 122 }
 123
 124 %}