A binary stream is an instance of os_bstream . When an os_bstream is constructed, it is associated with a particular I/O device via an intermediate adapter object called an os_adapter . When an item is streamed to an os_bstream , the item is converted into binary format and sent to the I/O device via the adapter. This technique enables the binary streaming mechanism to be fully decoupled from details of any particular I/O device.

The output of os_bstream is a stream of bytes sent via an os_adapter to a specific device. Because many types of devices are supported, the reader of the data stream can be on another machine. This commonly occurs when using sockets or when sharing files among multiple machines. So that two different architectures, such as Sparc and Intel, can communicate in these situations, data portability must be assured.

The os_ndr class is a helper class that is automatically used by os_bstream to implement the NDR protocol. When you construct an os_bstream , it automatically constructs os_ndr translators and uses them to ensure your data stream is portable between machines.

The reader and writer of an os_bstream exchange data format information by using a format label. Format labels are used to synchronize the reader to the format of the writer. Format labels are managed automatically by os_bstream , as follows.

RULE The scope of the reader os_bstream and writer os_bstream should be consistent. For example, if you construct a single os_bstream and write five objects to it, construct a single os_bstream and read five objects from it. Do not construct five os_bstream objects and read one object from each.

RULE Never connect two os_bstream objects to the same device at the same time.

RULE If you seek on a device, the os_bstream object connected to the device is no longer valid. Construct a new os_bstream on the device or reset the os_bstream objects using reset() before reading or writing. Note that this action causes a new format synchronization.

All read() and write() functions return a bool set to true on success or set to false on failure.

Interface

Constructor

os_bstream( const os_adapter& adapter )

Constructs a stream for the device adapter .

Throws: os_streaming_toolkit_error

Constructor

os_bstream( os_protocol& protocol )

Constructs a stream for the device managed by protocol . The protocol object must exist for the life of the stream and should not be shared among multiple streams.

Throws: os_streaming_toolkit_error

Destructor

~os_bstream()

Destroys the stream.

adapter

const os_adapter& adapter() const

Returns a reference to the device adapter used by this stream.

block_size

int block_size() const

Returns the number of bytes that the internal storage will increase each time the write buffer is filled. The default value is 4,096 bytes.

block_size

void block_size ( int size )

Sets the growth increment of the internal storage to size bytes.

clear

void clear()

Resets the state to good.

clear_precision_loss

void clear_precision_loss()

Resets the precision loss flag to false .

eof

bool eof() const

Returns true if the stream is at EOF.

fail

void fail()

Sets the state to indicate failure.

good

bool good() const

Returns true if the stream is in a good state and not at EOF.

bool ok() const

Returns true if the stream is in a good state.

precision_loss

bool precision_loss() const

Returns true if the stream experienced a precision loss conversion in a previous read. A precision loss can occur when streaming integer values between machines with dissimilar architectures.

protocol

const os_protocol& protocol() const

Returns a reference to the protocol adapter used by this stream.

read

bool read( bool& value )

Reads a bool into value .

Throws: os_streaming_toolkit_error

read

bool read( char& value )

Reads a char into value .

Throws: os_streaming_toolkit_error

read

int read( char*& buffer )

Reads a char* sequence into the heap and stores the pointer to the memory region in buffer . Returns the number of bytes read or returns -1 on error.

Throws: os_streaming_toolkit_error

read

bool read( double& value )

Reads a double into value .

Throws: os_streaming_toolkit_error

read

bool read( float& value )

Reads a float into value .

Throws: os_streaming_toolkit_error

read

bool read( int& value )

Reads an int into value .

Throws: os_streaming_toolkit_error

read

bool read( long& value )

Reads a long into value .

Throws: os_streaming_toolkit_error

read

bool read( long double& value )

Reads a long double into value .

Throws: os_streaming_toolkit_error

read

bool read( short& value )

Reads a short into value .

Throws: os_streaming_toolkit_error

read

bool read ( signed char& value )

Reads a

signed
    char

into value .

Throws: os_streaming_toolkit_error

read

bool read( os_int64_t& value )

Reads an os_int64_t into value .

Throws: os_streaming_toolkit_error

read

bool read( os_uint64_t& value )

Reads an os_uint64_t into value .

Throws: os_streaming_toolkit_error

read

bool read( unsigned char& value )

Reads an unsigned char into value .

Throws: os_streaming_toolkit_error

read

bool read( unsigned int& value )

Reads an unsigned int into value .

Throws: os_streaming_toolkit_error

read

bool read( unsigned long& value )

Reads an unsigned long into value .

Throws: os_streaming_toolkit_error

read

bool read( unsigned short& value )

Reads an unsigned short into value .

Throws: os_streaming_toolkit_error

read_chunk

int read_chunk( void* buffer , int bytes )

Reads a chunk of data, not to exceed bytes size, into buffer . Returns the number of bytes read on success or returns -1 on failure.

Throws: os_streaming_toolkit_error

read_chunk

int read_chunk( void*& buffer )

Reads a chunk of data into the heap and stores a pointer to the data in buffer . Returns the number of bytes read or returns -1 on failure.

Throws: os_streaming_toolkit_error

reset

void reset()

Resets the binary stream to a state as though it was just constructed. Format label synchronization occurs again.

tag_primitives

bool tag_primitives() const

Returns true if this stream is currently adding type information tags to the primitive data types it streams. Type-tagging is useful for debugging and cross-platform data conversions; however, the stream size increases.

tag_primitives

void tag_primitives( bool flag )

Sets the stream's type information tagging flag to flag .

write

bool write( bool value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( char value )

Writes value .

Throws: os_streaming_toolkit_error

write

int write( const char* buffer )

Writes buffer .

Throws: os_streaming_toolkit_error

write

bool write( double value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( float value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( int value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( long value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( long double value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write (signed char value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( short value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( unsigned char value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( unsigned int value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( unsigned long value )

Writes value .

Throws: os_streaming_toolkit_error

write

bool write( unsigned short value )

Writes value .

Throws: os_streaming_toolkit_error

write_chunk

int write_chunk( const void* buffer , int bytes )

Writes bytes number of characters from buffer .

Throws: os_streaming_toolkit_error

Non-Member Functions

os_bstream& operator<<( os_bstream& stream , bool value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , char value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , const char* value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , double value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , float value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , int value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , long value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , long double value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , short value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , signed char value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , unsigned char value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , unsigned int
value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , unsigned long value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , os_int64_t value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , os_uint64_t
value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator<<( os_bstream& stream , unsigned short value )

Writes value to stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , bool& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , char& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , char*& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , double& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , float& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , int& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , long& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , long double&
value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , os_int64_t&
value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , os_uint64_t&
value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , short& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , signed char&
value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , unsigned char& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , unsigned int& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , unsigned long& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

os_bstream& operator>>( os_bstream& stream , unsigned short& value )

Reads value from stream .

Throws: os_streaming_toolkit_error

`deque`	`list`
`map`	`multimap`
`multiset`	`priority_queue`
`queue`	`set`
`stack`	`vector`

bstream

Library

Declaration

Interface

Non-Member Functions

Other Non-Member Functions