An InputStream
is created using the following function:
{zcode:cs} namespace Ice { public sealed class Util { public static InputStream createInputStream( Communicator communicator, byte[] bytes); public static InputStream createInputStream( Communicator communicator, byte[] bytes, EncodingVersion version); public static InputStream wrapInputStream( Communicator communicator, byte[] bytes); public static InputStream wrapInputStream( Communicator communicator, byte[] bytes, EncodingVersion version); } } {zcode} |
You can optionally specify an encoding version for the stream, otherwise the stream uses the communicator's default encoding version.
Note that the createInputStream
functions make a copy of the supplied data, whereas the wrapInputStream
functions avoid copies by keeping a reference to the data. If you use wrapInputStream
, it is your responsibility to ensure that the memory buffer remains unmodified for the lifetime of the InputStream
object.
The InputStream
interface is shown below.
{zcode:cs} namespace Ice { public interface InputStream { Communicator communicator(); void sliceObjects(bool slice); bool readBool(); bool[] readBoolSeq(); byte readByte(); byte[] readByteSeq(); short readShort(); short[] readShortSeq(); int readInt(); int[] readIntSeq(); long readLong(); long[] readLongSeq(); float readFloat(); float[] readFloatSeq(); double readDouble(); double[] readDoubleSeq(); string readString(); string[] readStringSeq(); int readSize(); int readAndCheckSeqSize(int minSize); ObjectPrx readProxy(); void readObject(ReadObjectCallback cb); int readEnum(int maxValue); void throwException(); void throwException(UserExceptionReaderFactory factory); void startObject(); SlicedData endObject(bool preserve); void startException(); SlicedData endException(bool preserve); string startSlice(); void endSlice(); void skipSlice(); EncodingVersion startEncapsulation(); void endEncapsulation(); EncodingVersion skipEncapsulation(); EncodingVersion getEncoding(); void readPendingObjects(); object readSerializable(); void rewind(); void skip(int sz); void skipSize(); bool readOptional(int tag, OptionalFormat format); int pos(); void destroy(); } } {zcode} |
Member functions are provided for extracting all of the primitive types, as well as sequences of primitive types; these are self-explanatory. The remaining member functions have the following semantics:
void sliceObjects(boolean slice)
NoObjectFactoryException
is raised. The default behavior is to allow slicing.int readSize()
int readAndCheckSeqSize(int 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
.Ice.ObjectPrx readProxy()
ObjectPrx
. The Slice compiler optionally generates helper functions to extract proxies of user-defined types.void readObject(ReadObjectCallback cb)
The Ice encoding for class instances requires extraction to occur in stages. The readObject
function accepts a callback object of type ReadObjectCallback
, whose definition is shown below:
{zcode:cs} namespace Ice { public interface ReadObjectCallback { void invoke(Ice.Object obj); } } {zcode} |
When the object instance is available, the callback object's invoke
member function is called. The application must call readPendingObjects
to ensure that all instances are properly extracted. Note that applications rarely need to invoke this member function directly; the helper functions generated by the Slice compiler are easier to use.
int readEnum(int maxValue)
Unmarshals the integer value of an enumerator. The maxValue
argument represents the highest enumerator value in the enumeration. Consider the following definitions:
{zcode:slice} enum Color { red, green, blue }; enum Fruit { Apple, Pear=3, Orange }; {zcode} |
The maximum value for Color
is 2, and the maximum value for Fruit
is 4.
void throwException()
void throwException(UserExceptionReaderFactory factory)
UnmarshalOutOfBoundsException
, for the 1.1 encoding, the exception is UnknownUserException
.void startObject()
SlicedData endObject(bool preserve)
startObject
method must be called prior to reading the slices of an object. The endObject
method must be called after all slices have been read. Pass true to endObject
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 endObject
is a non-nil SlicedData
object that encapsulates the slice data. If the caller later wishes to forward the object with any preserved slices intact, it must supply this SlicedData
object to the output stream.void startException()
SlicedData endException(bool 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.string startSlice()
void endSlice()
void 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 object or exception.EncodingVersion startEncapsulation()
void endEncapsulation()
EncodingVersion skipEncapsulation()
startEncapsulation
and skipEncapsulation
methods return the encoding version used to encode the contents of the encapsulation.EncodingVersion getEncoding()
void readPendingObjects()
readObject
). Note that endEncapsulation
implicitly calls readPendingObjects
if necessary.void readPendingObjects()
readObject
). For backward compatibility with encoding version 1.0, this function must only be called when non-optional data members or parameters use class types.object readSerializable()
void rewind()
void skip(int sz)
void skipSize()
bool readOptional(int tag, OptionalFormat 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 defined as follows:
{zcode:cs} namespace Ice { enum OptionalFormat { OptionalFormatF1, OptionalFormatF2, OptionalFormatF4, OptionalFormatF8, OptionalFormatSize, OptionalFormatVSize, OptionalFormatFSize, OptionalFormatEndMarker } } {zcode} |
Refer to the encoding discussion for more information on the meaning of these values.
void destroy()
Here is a simple example that demonstrates how to extract a boolean and a sequence of strings from a stream:
{zcode:cs} byte[] data = ... Ice.InputStream inStream = Ice.Util.createInputStream(communicator, data); try { bool b = inStream.readBool(); string[] seq = inStream.readStringSeq(); } finally { inStream.destroy(); } {zcode} |