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/. */
6 #include
"nsIInputStream.idl"
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.
16 * @See nsIBinaryOutputStream
19 [scriptable
, builtinclass
, uuid(899b826b
-2eb3
-469c
-8b31
-4c29f5d341a6
)]
20 interface nsIBinaryInputStream
: nsIInputStream
{
21 void setInputStream
(in nsIInputStream aInputStream
);
24 * Read 8-bits from the stream.
26 * @return that byte to be treated as a boolean.
28 boolean readBoolean
();
39 * Read an 8-bit pascal style string from the stream.
40 * 32-bit length field, followed by length 8-bit chars.
42 ACString readCString
();
45 * Read an 16-bit pascal style string from the stream.
46 * 32-bit length field, followed by length PRUnichars.
51 * Read an opaque byte array from the stream.
53 * @param aLength the number of bytes that must be read.
55 * @throws NS_ERROR_FAILURE if it can't read aLength bytes
57 void readBytes
(in uint32_t aLength
,
58 [size_is(aLength
), retval] out string aString
);
61 * Read an opaque byte array from the stream, storing the results
62 * as an array of PRUint8s.
64 * @param aLength the number of bytes that must be read.
66 * @throws NS_ERROR_FAILURE if it can't read aLength bytes
68 Array
<uint8_t
> readByteArray
(in uint32_t aLength
);
71 * Read opaque bytes from the stream, storing the results in an ArrayBuffer.
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.
78 * @return The number of bytes actually read into aArrayBuffer.
81 uint64_t readArrayBuffer
(in uint64_t aLength
, in jsval aArrayBuffer
);
86 #ifdef MOZILLA_INTERNAL_API
90 NS_ReadOptionalCString
(nsIBinaryInputStream
* aStream
, nsACString
& aResult
)
93 nsresult rv
= aStream
->ReadBoolean
(&nonnull
);
94 if
(NS_SUCCEEDED
(rv
)) {
96 rv
= aStream
->ReadCString
(aResult
);
104 NS_ReadOptionalString
(nsIBinaryInputStream
* aStream
, nsAString
& aResult
)
107 nsresult rv
= aStream
->ReadBoolean
(&nonnull
);
108 if
(NS_SUCCEEDED
(rv
)) {
110 rv
= aStream
->ReadString
(aResult
);