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, builtinclass, 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     Array<uint8_t> readByteArray(in uint32_t aLength);
  69
  70     /**
  71      * Read opaque bytes from the stream, storing the results in an ArrayBuffer.
  72      *
  73      * @param aLength the number of bytes that must be read
  74      * @param aArrayBuffer the arraybuffer in which to store the results
  75      * Note: passing view.buffer, where view is an ArrayBufferView of an
  76      *       ArrayBuffer, is not valid unless view.byteOffset == 0.
  77      *
  78      * @return The number of bytes actually read into aArrayBuffer.
  79      */
  80     [implicit_jscontext]
  81     uint64_t readArrayBuffer(in uint64_t aLength, in jsval aArrayBuffer);
  82 };
  83
  84 %{C++
  85
  86 #ifdef MOZILLA_INTERNAL_API
  87 #include "nsString.h"
  88
  89 inline nsresult
  90 NS_ReadOptionalCString(nsIBinaryInputStream* aStream, nsACString& aResult)
  91 {
  92     bool nonnull;
  93     nsresult rv = aStream->ReadBoolean(&nonnull);
  94     if (NS_SUCCEEDED(rv)) {
  95         if (nonnull)
  96             rv = aStream->ReadCString(aResult);
  97         else
  98             aResult.Truncate();
  99     }
 100     return rv;
 101 }
 102
 103 inline nsresult
 104 NS_ReadOptionalString(nsIBinaryInputStream* aStream, nsAString& aResult)
 105 {
 106     bool nonnull;
 107     nsresult rv = aStream->ReadBoolean(&nonnull);
 108     if (NS_SUCCEEDED(rv)) {
 109         if (nonnull)
 110             rv = aStream->ReadString(aResult);
 111         else
 112             aResult.Truncate();
 113     }
 114     return rv;
 115 }
 116 #endif
 117
 118 %}