ObjectiveLib  1.0.0
Public Member Functions | Static Public Member Functions | Protected Attributes
OLObjectInStream Class Reference

A stream that can read objects and classes. More...

#import <ObjectiveLib/ObjectInStream.h>

Inheritance diagram for OLObjectInStream:
Inheritance graph
[legend]

List of all members.

Public Member Functions

(unsigned) - classVersion:
 Return the version of the given class name.
(BOOL) - readBool
 Read a boolean value from the stream.
(Class) - readClass
 Read a class.
(double) - readDouble
 Read a double value from the stream.
(float) - readFloat
 Read a float value from the stream.
(void) - readHeader
 Read the object stream header.
(unsigned) - readInt
 Read an integer value from the stream.
(uint16_t) - readInt16
 Read a 16-bit integer value from the stream.
(uint32_t) - readInt32
 Read a 32-bit integer value from the stream.
(uint64_t) - readInt64
 Read a 64-bit integer value from the stream.
(id) - readObject
 Read an object.
(unsigned) - systemVersion
 Return the version of the system stored in the stream.
Initializers and Deallocators
(id) - initWithInStream:
 Initialize the stream.
(void) - dealloc
 Finalize the stream and deallocate any allocated memory.
NSCoder Support

Support the streaming of objects that adopt the NSCoding protocol

(void *) - decodeBytesWithReturnedLength:
 Decode a buffer of data.
(NSData *) - decodeDataObject
 Decode a data object.
(id) - decodeObject
 Decode an object.
(void) - decodeValueOfObjCType:at:
 Decode a value of a specified Objective-C type.
(unsigned) - versionForClassName:
 Return the version of a class stored in the stream.

Static Public Member Functions

(id) + streamWithInStream:
 Create and return a new object in stream.

Protected Attributes

OLHashMapclasses
 The classes read by the stream.
OLSharedPointerTable * sharedPointers
 The shared pointers read by the stream.
uint32_t systemVersion
 The system version read by the stream.

Detailed Description

A stream that can read objects and classes.

In addition to reading objects and classes OLObjectInStream reads a tag of every type that OLObjectOutStream has written to the stream. If a certain type is expected but another type is found, then an exception is thrown indicating the inconsistency.

See also:
OLObjectOutStream

Member Function Documentation

- (unsigned) classVersion: (const char *)  className

Return the version of the given class name.

If the class has been read with the readClass method, then the version of the class will be returned.

Note:
The method readClass is called whenever an object is read for which the class of the object has not yet been read. Thus, reading an instance of OLText will also cause readClass for OLText to be called.
Parameters:
classNamethe name of the class that should be queried
Returns:
the version of the class if the class has been read or UINT_MAX otherwise
- (void) dealloc

Finalize the stream and deallocate any allocated memory.

Reimplemented from OLLayeredInStream.

- (void*) decodeBytesWithReturnedLength: (unsigned *)  numBytes

Decode a buffer of data.

This method is included solely to support objects that already support the NSCoding protocol, and relies on the lower-level message readBytes:count: (OLLayeredInStream). This message can be used to read data written by encodeBytes:length: (OLOutStream), however there is nothing to be gained by using this pair of messages over the preferred pair writeBytes:count: (OLOutStream) and readBytes:count: (OLLayeredInStream).

The returned pointer will be autoreleased before being returned and the value at the address numBytes will contain the number of bytes actually read.

Exceptions:
OLInputOutputExceptionif there is an error reading from the stream
OLEndOfStreamExceptionif the end of the stream has been reached
Parameters:
numBytesthe number of bytes read
Returns:
a pointer to the bytes read

Reimplemented from OLInStream.

- (NSData*) decodeDataObject

Decode a data object.

This method is included solely to support objects that already support the NSCoding protocol, and relies on the lower-level message readBytes:count: (OLLayeredInStream). This message can be used to read data written by encodeDataObject: (OLOutStream), however there is nothing to be gained by using this pair of messages over the preferred pair writeBytes:count: (OLOutStream) and readBytes:count: (OLLayeredInStream).

The returned data object will be autoreleased before being returned.

Exceptions:
OLInputOutputExceptionif there is an error reading from the stream
OLEndOfStreamExceptionif the end of the stream has been reached
Returns:
the read data object

Reimplemented from OLInStream.

- (id) decodeObject

Decode an object.

This method mere forwards the message to readObject, so there is nothing to be gained by using this message over that one.

Returns:
the object read

Reimplemented from OLInStream.

- (void) decodeValueOfObjCType: (const char *)  valueType
at: (void *)  address 

Decode a value of a specified Objective-C type.

Read a value of an arbitrary type from the stream. Note that in order to preserve platform-independence in the resulting stream, constraints are placed on how the data are read. Types that otherwise have indeterminate sizes will always be normalized to sizes chosen by ObjectiveLib. The sizes read are as follows:

TypeSize
char1
short2
int4
long4
long long8

Additionally, the behavior of returned pointers is different if the system is running under GNUstep or under Cocoa. Under GNUstep freshly allocated pointers returned from this method will be autoreleased, while under Cocoa the caller owns the pointer and must release it. This is not my fault.

Exceptions:
OLInputOutputExceptionif there is an error reading from the stream
OLEndOfStreamExceptionif the end of the stream has been reached
OLClassNotFoundExceptionif a class required by the request cannot be found in the current runtime
Parameters:
valueTypethe type of the value at address
addressthe location of the value to read

Reimplemented from OLInStream.

- (id) initWithInStream: (OLInStream *)  underStream

Initialize the stream.

The stream is created with underStream as the next stream below the new one in the stack of streams.

Parameters:
underStreamthe stream from which to read
Returns:
a reference to this stream

Reimplemented from OLLayeredInStream.

- (BOOL) readBool

Read a boolean value from the stream.

The value is read as if it had been written by writeBool: (OLOutStream). Specifically, one byte of data is read and YES is returned if that byte is non-zero, otherwise NO is returned.

Exceptions:
OLInputOutputExceptionif the value could not be read
OLEndOfStreamExceptionif the end of the stream has been reached
Returns:
the value read

Reimplemented from OLInStream.

- (Class) readClass

Read a class.

A class previously written by writeClass: (OLObjectOutStream) is read.

Exceptions:
OLInputOutputExceptionif there is an error reading from the stream
OLClassNotFoundExceptionif the class stored in the stream is not available in the current runtime
Returns:
the class
- (double) readDouble

Read a double value from the stream.

The value is read as if it had been written by writeDouble: (OLOutStream). Specifically, an 8-byte field of data is read and converted from network byte order to host byte order.

Exceptions:
OLInputOutputExceptionif the value could not be read
OLEndOfStreamExceptionif the end of the stream has been reached
Returns:
the value read

Reimplemented from OLInStream.

- (float) readFloat

Read a float value from the stream.

The value is read as if it had been written by writeFloat: (OLOutStream). Specifically, an 4-byte field of data is read and converted from network byte order to host byte order.

Exceptions:
OLInputOutputExceptionif the value could not be read
OLEndOfStreamExceptionif the end of the stream has been reached
Returns:
the value read

Reimplemented from OLInStream.

- (void) readHeader

Read the object stream header.

This method can be overridden to read a custom header from the object stream. The message will be called in due course, so it is never necessary to call this method.

Note:
Subclasses that override this method should call the superclass' method before reading any additional data.
Exceptions:
OLInputOutputExceptionif there is an error reading from the stream
- (unsigned) readInt

Read an integer value from the stream.

The value is read as if it had been written by writeInt: (OLOutStream). Specifically, an 4-byte field of data is read and converted from network byte order to host byte order.

Note:
Regardless of the size of the type int on the platform being used, the value read will always be exactly four bytes long and returned as an unsigned value.
Exceptions:
OLInputOutputExceptionif the value could not be read
OLEndOfStreamExceptionif the end of the stream has been reached
Returns:
the value read

Reimplemented from OLInStream.

- (uint16_t) readInt16

Read a 16-bit integer value from the stream.

The value is read as if it had been written by writeInt16: (OLOutStream). Specifically, an 2-byte field of data is read and converted from network byte order to host byte order.

Exceptions:
OLInputOutputExceptionif the value could not be read
OLEndOfStreamExceptionif the end of the stream has been reached
Returns:
the value read

Reimplemented from OLInStream.

- (uint32_t) readInt32

Read a 32-bit integer value from the stream.

The value is read as if it had been written by writeInt32: (OLOutStream). Specifically, an 4-byte field of data is read and converted from network byte order to host byte order.

Exceptions:
OLInputOutputExceptionif the value could not be read
OLEndOfStreamExceptionif the end of the stream has been reached
Returns:
the value read

Reimplemented from OLInStream.

- (uint64_t) readInt64

Read a 64-bit integer value from the stream.

The value is read as if it had been written by writeInt64: (OLOutStream). Specifically, an 8-byte field of data is read and converted from network byte order to host byte order.

Exceptions:
OLInputOutputExceptionif the value could not be read
OLEndOfStreamExceptionif the end of the stream has been reached
Returns:
the value read

Reimplemented from OLInStream.

- (id) readObject

Read an object.

An object previously written by writeObject: (OLObjectOutStream) is read.

Precondition:
The object being read must implement either the OLStreamable protocol or the NSCoding protocol. If both protocols are found, then the methods from OLStreamable are given preference.
Note:
If OpenStep is present the returned object will be autoreleased before being returned.
Exceptions:
OLInputOutputExceptionif there is an error reading from the stream
OLClassNotFoundExceptionif a class on which instantiating the object depends cannot be found in the current runtime
Returns:
the object
+ (id) streamWithInStream: (OLInStream *)  underStream

Create and return a new object in stream.

The stream is created with underStream as the next stream below the new one in the stack of streams.

Parameters:
underStreamthe stream from which to read
Returns:
a reference to the newly created stream
- (unsigned) systemVersion

Return the version of the system stored in the stream.

The version of the ObjectiveLib streaming system that is stored in the stream is returned.

Returns:
the stored system version
- (unsigned) versionForClassName: (NSString *)  className

Return the version of a class stored in the stream.

For the class named className the version that was written to the stream is returned. This method is typically used when a class is decoding an instance of itself to determine how the decoding should be performed.

Note:
If no class by the given name can be found in the runtime, then the value NSNotFound is returned.
Parameters:
classNamethe name of the class
Returns:
the version of the class

Member Data Documentation

- (OLHashMap*) classes [protected]

The classes read by the stream.

- (OLSharedPointerTable*) sharedPointers [protected]

The shared pointers read by the stream.

- (uint32_t) systemVersion [protected]

The system version read by the stream.


The documentation for this class was generated from the following file:

ObjectiveLibGenerated Sat Feb 15 2014 07:45:35, © 2004-2007 Will Mason