On this page:
InputStream
in JavaScriptThe InputStream
class provides a constructor that accepts up to three arguments. Legal argument values are:
You'll normally supply the encoded data argument. The stream does not make a copy of this data; rather, it uses the data as supplied and assumes it remains unmodified for the lifetime of the stream object.
We recommend supplying a communicator instance, otherwise you will not be able to decode proxy objects. The stream also inspects the communicator's settings to configure several of its own default settings, but you can optionally configure these settings manually using methods that we'll describe later.
If you omit an encoding version, the stream uses the default encoding version of the communicator (if provided) or the most recent encoding version.
Use the following properties to manually configure the stream:
var stream = new Ice.InputStream(...); stream.valueFactoryManager = ... stream.logger = ... stream.compactIdResolver = ... stream.sliceValues = ... stream.traceSlicing = ... |
The settings include:
Compact ID resolver
A compact ID resolver for translating numeric values into Slice type IDs. The stream invokes the resolver by passing it the numeric compact ID. The resolver is expected to return the Slice type ID associated with that numeric ID or an empty string if the numeric ID is unknown. The application must supply a function that accepts an integer and returns a string.
NoValueFactoryException
. The default behavior is to allow slicing.Ice.Trace.Slicing
property, otherwise the setting defaults to false.InputStream
in JavaScriptInputStream
provides a number of read
methods that allow you to extract Slice types from the stream.
For example, you can extract a boolean and a string from a stream as follows:
var data = ... var istr = new Ice.InputStream(communicator, data); var b = istr.readBool(); var s = istr.readString(); |
Here are the methods for extracting data from a stream:
readByte()
readBool()
readInt()
readLong()
readFloat()
readDouble()
readString()
Extracts and returns a primitive value.
readByteSeq()
readSize()
readAndCheckSeqSize(minWireSize)
readSize
, this function reads a size and returns it, but also verifies that there is enough data remaining in the unmarshaling buffer to successfully unmarshal the elements of the sequence. The minWireSize
parameter indicates the smallest possible on-the-wire representation of a single sequence element. If the unmarshaling buffer contains insufficient data to unmarshal the sequence, the function throws UnmarshalOutOfBoundsException
.readProxy(type)
ObjectPrx
, otherwise it returns an instance of the given proxy type.readValue(cb, type)
The Ice encoding for class instances requires extraction to occur in stages. The readValue
function accepts a callback function that receives the extracted instance as its argument. The caller must also supply the class type expected for the instance. When the instance is available, the callback function is called. The application must call readPendingValues
on the stream to ensure that all instances are properly extracted.
readEnum(type)
Extracts the integer value of an enumerator and returns the equivalent enumerator. The caller must pass the enumeration type as the argument.
throwException()
Extracts a user exception from the stream and throws it. If the stored exception is of an unknown type, the function attempts to extract and throw a less-derived exception. If that also fails, an exception is thrown: for the 1.0 encoding, the exception is UnmarshalOutOfBoundsException
, for the 1.1 encoding, the exception is UnknownUserException
.
startSlice()
endSlice()
skipSlice()
startSlice
method returns the type ID of the next slice, which may be an empty string depending on the format used to encode the instance or exception.startValue()
endValue(preserve)
startValue
method must be called prior to reading the slices of a class instance. The endValue
method must be called after all slices have been read. Pass true to endValue
in order to preserve the slices of any unknown more-derived types, or false to discard the slices. If preserve
is true and the stream actually preserved any slices, the return value of endValue
is a non-nil SlicedData
object that encapsulates the slice data. If the caller later wishes to forward the instance with any preserved slices intact, it must supply this SlicedData
object to the output stream.startException()
endException(preserve)
startException
method must be called prior to reading the slices of an exception. The endException
method must be called after all slices have been read. Pass true to endException
in order to preserve the slices of any unknown more-derived types, or false to discard the slices. If preserve
is true and the stream actually preserved any slices, the return value of endException
is a non-nil SlicedData
object that encapsulates the slice data. If the caller later wishes to forward the exception with any preserved slices intact, it must supply this SlicedData
object to the output stream.startEncapsulation()
endEncapsulation()
skipEncapsulation()
startEncapsulation
and skipEncapsulation
methods return the encoding version used to encode the contents of the encapsulation.skipEmptyEncapsulation(version)
EncapsulationException
if the encapsulation is not empty. If the version
argument is non-null, the stream stores the encoding version of the empty encapsulation in version
.getEncapsulationSize()
getEncoding()
readPendingValues()
readValue
). For backward compatibility with encoding version 1.0, this function must only be called when non-optional data members or parameters use class types.readBlob(sz)
Extracts an array of sz
bytes from the stream at its current position. The returned byte array contains undecoded data from the stream's internal buffer. The stream's position is advanced by sz
.
skip(sz)
skipSize()
readOptional(tag, fmt)
Returns true if an optional value with the given tag and format is present, or false otherwise. If this method returns true, the data associated with that optional value must be read next. Optional values must be read in order by tag from least to greatest. The OptionalFormat
enumeration is equivalent to the following:
module Ice { enum OptionalFormat { OptionalFormatF1, OptionalFormatF2, OptionalFormatF4, OptionalFormatF8, OptionalFormatSize, OptionalFormatVSize, OptionalFormatFSize, OptionalFormatEndMarker } } |
Refer to the encoding discussion for more information on the meaning of these values.
readOptionalHelper(tag, fmt, readFn)
If an optional value is present with the given tag and format, the stream invokes the given helper function to extract the value. For example, you can pass InputStream.prototype.readByte
as the helper function when extracting an optional byte value. This function returns undefined
if the optional value is not present.readOptionalProxy(tag, type)
If an optional value is present with the given tag and the correct format for a proxy, this function extracts the proxy information and returns a proxy instance of the given type, or ObjectPrx
if no type is provided. This function returns undefined
if the optional value is not present.readOptionalEnum(tag, type)
undefined
if the optional value is not present.readOptionalValue(tag, cb, type)
undefined
if the optional instance is not present.Finally, you can use the pos
property to get and set the stream's current position.