1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/io/nsIBinaryInputStream.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,119 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
1.5 + * This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsIInputStream.idl"
1.10 +
1.11 +/**
1.12 + * This interface allows consumption of primitive data types from a "binary
1.13 + * stream" containing untagged, big-endian binary data, i.e. as produced by an
1.14 + * implementation of nsIBinaryOutputStream. This might be used, for example,
1.15 + * to implement network protocols or to read from architecture-neutral disk
1.16 + * files, i.e. ones that can be read and written by both big-endian and
1.17 + * little-endian platforms.
1.18 + *
1.19 + * @See nsIBinaryOutputStream
1.20 + */
1.21 +
1.22 +[scriptable, uuid(42084755-fedc-4310-831c-4f43e7b42e20)]
1.23 +interface nsIBinaryInputStream : nsIInputStream {
1.24 + void setInputStream(in nsIInputStream aInputStream);
1.25 +
1.26 + /**
1.27 + * Read 8-bits from the stream.
1.28 + *
1.29 + * @return that byte to be treated as a boolean.
1.30 + */
1.31 + boolean readBoolean();
1.32 +
1.33 + uint8_t read8();
1.34 + uint16_t read16();
1.35 + uint32_t read32();
1.36 + uint64_t read64();
1.37 +
1.38 + float readFloat();
1.39 + double readDouble();
1.40 +
1.41 + /**
1.42 + * Read an 8-bit pascal style string from the stream.
1.43 + * 32-bit length field, followed by length 8-bit chars.
1.44 + */
1.45 + ACString readCString();
1.46 +
1.47 + /**
1.48 + * Read an 16-bit pascal style string from the stream.
1.49 + * 32-bit length field, followed by length PRUnichars.
1.50 + */
1.51 + AString readString();
1.52 +
1.53 + /**
1.54 + * Read an opaque byte array from the stream.
1.55 + *
1.56 + * @param aLength the number of bytes that must be read.
1.57 + *
1.58 + * @throws NS_ERROR_FAILURE if it can't read aLength bytes
1.59 + */
1.60 + void readBytes(in uint32_t aLength,
1.61 + [size_is(aLength), retval] out string aString);
1.62 +
1.63 + /**
1.64 + * Read an opaque byte array from the stream, storing the results
1.65 + * as an array of PRUint8s.
1.66 + *
1.67 + * @param aLength the number of bytes that must be read.
1.68 + *
1.69 + * @throws NS_ERROR_FAILURE if it can't read aLength bytes
1.70 + */
1.71 + void readByteArray(in uint32_t aLength,
1.72 + [array, size_is(aLength), retval] out uint8_t aBytes);
1.73 +
1.74 + /**
1.75 + * Read opaque bytes from the stream, storing the results in an ArrayBuffer.
1.76 + *
1.77 + * @param aLength the number of bytes that must be read
1.78 + * @param aArrayBuffer the arraybuffer in which to store the results
1.79 + * Note: passing view.buffer, where view is an ArrayBufferView of an
1.80 + * ArrayBuffer, is not valid unless view.byteOffset == 0.
1.81 + *
1.82 + * @throws NS_ERROR_FAILURE if it can't read aLength bytes
1.83 + */
1.84 + [implicit_jscontext]
1.85 + void readArrayBuffer(in uint32_t aLength, in jsval aArrayBuffer);
1.86 +};
1.87 +
1.88 +%{C++
1.89 +
1.90 +#ifdef MOZILLA_INTERNAL_API
1.91 +#include "nsString.h"
1.92 +
1.93 +inline nsresult
1.94 +NS_ReadOptionalCString(nsIBinaryInputStream* aStream, nsACString& aResult)
1.95 +{
1.96 + bool nonnull;
1.97 + nsresult rv = aStream->ReadBoolean(&nonnull);
1.98 + if (NS_SUCCEEDED(rv)) {
1.99 + if (nonnull)
1.100 + rv = aStream->ReadCString(aResult);
1.101 + else
1.102 + aResult.Truncate();
1.103 + }
1.104 + return rv;
1.105 +}
1.106 +
1.107 +inline nsresult
1.108 +NS_ReadOptionalString(nsIBinaryInputStream* aStream, nsAString& aResult)
1.109 +{
1.110 + bool nonnull;
1.111 + nsresult rv = aStream->ReadBoolean(&nonnull);
1.112 + if (NS_SUCCEEDED(rv)) {
1.113 + if (nonnull)
1.114 + rv = aStream->ReadString(aResult);
1.115 + else
1.116 + aResult.Truncate();
1.117 + }
1.118 + return rv;
1.119 +}
1.120 +#endif
1.121 +
1.122 +%}
