michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsIInputStream.idl"
michael@0: 
michael@0: /**
michael@0:  * This interface allows consumption of primitive data types from a "binary
michael@0:  * stream" containing untagged, big-endian binary data, i.e. as produced by an
michael@0:  * implementation of nsIBinaryOutputStream.  This might be used, for example,
michael@0:  * to implement network protocols or to read from architecture-neutral disk
michael@0:  * files, i.e. ones that can be read and written by both big-endian and
michael@0:  * little-endian platforms.
michael@0:  *
michael@0:  * @See nsIBinaryOutputStream
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(42084755-fedc-4310-831c-4f43e7b42e20)]
michael@0: interface nsIBinaryInputStream : nsIInputStream {
michael@0:     void setInputStream(in nsIInputStream aInputStream);
michael@0:     
michael@0:     /**
michael@0:      * Read 8-bits from the stream.
michael@0:      *
michael@0:      * @return that byte to be treated as a boolean.
michael@0:      */
michael@0:     boolean readBoolean();
michael@0: 
michael@0:     uint8_t read8();
michael@0:     uint16_t read16();
michael@0:     uint32_t read32();
michael@0:     uint64_t read64();
michael@0: 
michael@0:     float readFloat();
michael@0:     double readDouble();
michael@0: 
michael@0:     /**
michael@0:      * Read an 8-bit pascal style string from the stream.
michael@0:      * 32-bit length field, followed by length 8-bit chars.
michael@0:      */
michael@0:     ACString readCString();
michael@0: 
michael@0:     /**
michael@0:      * Read an 16-bit pascal style string from the stream.
michael@0:      * 32-bit length field, followed by length PRUnichars.
michael@0:      */
michael@0:     AString readString();
michael@0: 
michael@0:     /**
michael@0:      * Read an opaque byte array from the stream.
michael@0:      *
michael@0:      * @param aLength the number of bytes that must be read.
michael@0:      *
michael@0:      * @throws NS_ERROR_FAILURE if it can't read aLength bytes
michael@0:      */
michael@0:     void readBytes(in uint32_t aLength,
michael@0:                    [size_is(aLength), retval] out string aString);
michael@0: 
michael@0:     /**
michael@0:      * Read an opaque byte array from the stream, storing the results
michael@0:      * as an array of PRUint8s.
michael@0:      *
michael@0:      * @param aLength the number of bytes that must be read.
michael@0:      *
michael@0:      * @throws NS_ERROR_FAILURE if it can't read aLength bytes
michael@0:      */
michael@0:     void readByteArray(in uint32_t aLength,
michael@0:                        [array, size_is(aLength), retval] out uint8_t aBytes);
michael@0: 
michael@0:     /**
michael@0:      * Read opaque bytes from the stream, storing the results in an ArrayBuffer.
michael@0:      *
michael@0:      * @param aLength the number of bytes that must be read
michael@0:      * @param aArrayBuffer the arraybuffer in which to store the results
michael@0:      * Note: passing view.buffer, where view is an ArrayBufferView of an
michael@0:      *       ArrayBuffer, is not valid unless view.byteOffset == 0.
michael@0:      *
michael@0:      * @throws NS_ERROR_FAILURE if it can't read aLength bytes
michael@0:      */
michael@0:     [implicit_jscontext]
michael@0:     void readArrayBuffer(in uint32_t aLength, in jsval aArrayBuffer);
michael@0: };
michael@0: 
michael@0: %{C++
michael@0: 
michael@0: #ifdef MOZILLA_INTERNAL_API
michael@0: #include "nsString.h"
michael@0: 
michael@0: inline nsresult
michael@0: NS_ReadOptionalCString(nsIBinaryInputStream* aStream, nsACString& aResult)
michael@0: {
michael@0:     bool nonnull;
michael@0:     nsresult rv = aStream->ReadBoolean(&nonnull);
michael@0:     if (NS_SUCCEEDED(rv)) {
michael@0:         if (nonnull)
michael@0:             rv = aStream->ReadCString(aResult);
michael@0:         else
michael@0:             aResult.Truncate();
michael@0:     }
michael@0:     return rv;
michael@0: }
michael@0: 
michael@0: inline nsresult
michael@0: NS_ReadOptionalString(nsIBinaryInputStream* aStream, nsAString& aResult)
michael@0: {
michael@0:     bool nonnull;
michael@0:     nsresult rv = aStream->ReadBoolean(&nonnull);
michael@0:     if (NS_SUCCEEDED(rv)) {
michael@0:         if (nonnull)
michael@0:             rv = aStream->ReadString(aResult);
michael@0:         else
michael@0:             aResult.Truncate();
michael@0:     }
michael@0:     return rv;
michael@0: }
michael@0: #endif
michael@0: 
michael@0: %}