Using Streams: 1.4 Using Streams: The Basics: Reading Data from a Stream

StreamRead(), StreamReadByte()

To read data in a stream, call the routine StreamRead() . This routine takes six arguments:

The GeodeHandle of the stream driver.
The StreamToken of the stream.
A member of the StreamBlocker enumerated type, as described in Blocking on Read or Write .
The amount of data to be read, in bytes.
A pointer to a data buffer; the data will be read from the stream into that buffer.
A pointer to an integer. StreamRead() will write the number of bytes actually read to that integer.

If the requested amount of data was read successfully, StreamRead() will return zero and write the number of bytes read (i.e. the size of the data buffer passed) to the integer pointed to by the sixth argument. If it could not successfully read the requested amount of data, it will return one of the following StreamError values:

STREAM_WOULD_BLOCK: STREAM_BLOCK had been passed, and there was no data waiting in the stream. The sixth argument will be set to zero.
STREAM_SHORT_READ_WRITE: If STREAM_NOBLOCK had been passed, this means the stream did not have the amount of data requested. If STREAM_BLOCK had been passed, this means the stream was closed before the requested amount of data could be read. The sixth argument will contain the number of bytes actually read from the stream.
STREAM_CLOSING: The stream is in the process of being closed; no reading is permitted while this is happening. The sixth argument will be set to zero.

You may often want to read a single byte from the stream. There is a special routine to do this, StreamReadByte() . This routine takes four arguments:

The GeodeHandle of the stream driver.
The StreamToken of the stream.
A member of the StreamBlocker enumerated type, as described in Blocking on Read or Write .
A pointer to a byte-sized variable; the data byte read will be written to this variable.

If the byte is written successfully, StreamReadByte() will return zero. Otherwise, it will return one of the following error values:

STREAM_WOULD_BLOCK: STREAM_BLOCK had been passed, and there was no data waiting in the stream.
STREAM_CLOSING: The stream is in the process of being closed; no reading is permitted while this is happening.

GEOS SDK TechDocs |

1.3 Writing Data to a Stream | Next:

1.5 Shutting Down a Stream