xpcom/io/nsIBinaryInputStream.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 "nsIInputStream.idl"
   7
   8 /**
   9  * This interface allows consumption of primitive data types from a "binary
  10  * stream" containing untagged, big-endian binary data, i.e. as produced by an
  11  * implementation of nsIBinaryOutputStream.  This might be used, for example,
  12  * to implement network protocols or to read from architecture-neutral disk
  13  * files, i.e. ones that can be read and written by both big-endian and
  14  * little-endian platforms.
  15  *
  16  * @See nsIBinaryOutputStream
  17  */
  18
  19 [scriptable, uuid(899b826b-2eb3-469c-8b31-4c29f5d341a6)]
  20 interface nsIBinaryInputStream : nsIInputStream {
  21     void setInputStream(in nsIInputStream aInputStream);
  22
  23     /**
  24      * Read 8-bits from the stream.
  25      *
  26      * @return that byte to be treated as a boolean.
  27      */
  28     boolean readBoolean();
  29
  30     uint8_t read8();
  31     uint16_t read16();
  32     uint32_t read32();
  33     uint64_t read64();
  34
  35     float readFloat();
  36     double readDouble();
  37
  38     /**
  39      * Read an 8-bit pascal style string from the stream.
  40      * 32-bit length field, followed by length 8-bit chars.
  41      */
  42     ACString readCString();
  43
  44     /**
  45      * Read an 16-bit pascal style string from the stream.
  46      * 32-bit length field, followed by length PRUnichars.
  47      */
  48     AString readString();
  49
  50     /**
  51      * Read an opaque byte array from the stream.
  52      *
  53      * @param aLength the number of bytes that must be read.
  54      *
  55      * @throws NS_ERROR_FAILURE if it can't read aLength bytes
  56      */
  57     void readBytes(in uint32_t aLength,
  58                    [size_is(aLength), retval] out string aString);
  59
  60     /**
  61      * Read an opaque byte array from the stream, storing the results
  62      * as an array of PRUint8s.
  63      *
  64      * @param aLength the number of bytes that must be read.
  65      *
  66      * @throws NS_ERROR_FAILURE if it can't read aLength bytes
  67      */
  68     void readByteArray(in uint32_t aLength,
  69                        [array, size_is(aLength), retval] out uint8_t aBytes);
  70
  71     /**
  72      * Read opaque bytes from the stream, storing the results in an ArrayBuffer.
  73      *
  74      * @param aLength the number of bytes that must be read
  75      * @param aArrayBuffer the arraybuffer in which to store the results
  76      * Note: passing view.buffer, where view is an ArrayBufferView of an
  77      *       ArrayBuffer, is not valid unless view.byteOffset == 0.
  78      *
  79      * @return The number of bytes actually read into aArrayBuffer.
  80      */
  81     [implicit_jscontext]
  82     unsigned long readArrayBuffer(in uint32_t aLength, in jsval aArrayBuffer);
  83 };
  84
  85 %{C++
  86
  87 #ifdef MOZILLA_INTERNAL_API
  88 #include "nsString.h"
  89
  90 inline nsresult
  91 NS_ReadOptionalCString(nsIBinaryInputStream* aStream, nsACString& aResult)
  92 {
  93     bool nonnull;
  94     nsresult rv = aStream->ReadBoolean(&nonnull);
  95     if (NS_SUCCEEDED(rv)) {
  96         if (nonnull)
  97             rv = aStream->ReadCString(aResult);
  98         else
  99             aResult.Truncate();
 100     }
 101     return rv;
 102 }
 103
 104 inline nsresult
 105 NS_ReadOptionalString(nsIBinaryInputStream* aStream, nsAString& aResult)
 106 {
 107     bool nonnull;
 108     nsresult rv = aStream->ReadBoolean(&nonnull);
 109     if (NS_SUCCEEDED(rv)) {
 110         if (nonnull)
 111             rv = aStream->ReadString(aResult);
 112         else
 113             aResult.Truncate();
 114     }
 115     return rv;
 116 }
 117 #endif
 118
 119 %}