Home > Support > Documentation

Input/Output Data Stream Utility Functions

Stream functions are used for unbuffered stream operations. More...

Classes

struct  OSRTSTREAM
 The stream control block. More...

Defines

#define OSRTSTRMF_INPUT   0x0001
#define OSRTSTRMF_OUTPUT   0x0002
#define OSRTSTRMF_BUFFERED   0x8000
#define OSRTSTRMF_UNBUFFERED   0x4000
#define OSRTSTRMF_POSMARKED   0x2000
#define OSRTSTRMF_BUF_INPUT   (OSRTSTRMF_INPUT|OSRTSTRMF_BUFFERED)
#define OSRTSTRMF_BUF_OUTPUT   (OSRTSTRMF_OUTPUT|OSRTSTRMF_BUFFERED)
#define OSRTSTRMID_FILE   1
#define OSRTSTRMID_SOCKET   2
#define OSRTSTRMID_MEMORY   3
#define OSRTSTRMID_BUFFERED   4
#define OSRTSTRMID_DIRECTBUF   5
#define OSRTSTRMID_CTXTBUF   6
#define OSRTSTRMID_USER   1000
#define OSRTSTRM_K_BUFSIZE   1024
#define OSRTSTRM_K_INVALIDMARK   ((size_t)-1)
#define OSRTSTREAM_BYTEINDEX(pctxt)
#define OSRTSTREAM_ID(pctxt)   ((pctxt)->pStream->id)
#define OSRTSTREAM_FLAGS(pctxt)   ((pctxt)->pStream->flags)

Typedefs

typedef long(* OSRTStreamReadProc )(struct OSRTSTREAM *pStream, OSOCTET *pbuffer, size_t bufSize)
 Stream read function pointer type.
typedef long(* OSRTStreamBlockingReadProc )(struct OSRTSTREAM *pStream, OSOCTET *pbuffer, size_t toReadBytes)
 Stream blockingRead function pointer type.
typedef long(* OSRTStreamWriteProc )(struct OSRTSTREAM *pStream, const OSOCTET *data, size_t numocts)
 Stream write function pointer type.
typedef int(* OSRTStreamFlushProc )(struct OSRTSTREAM *pStream)
 Stream flush function pointer type.
typedef int(* OSRTStreamCloseProc )(struct OSRTSTREAM *pStream)
 Stream close function pointer type.
typedef int(* OSRTStreamSkipProc )(struct OSRTSTREAM *pStream, size_t skipBytes)
 Stream skip function pointer type.
typedef int(* OSRTStreamMarkProc )(struct OSRTSTREAM *pStream, size_t readAheadLimit)
 Stream mark function pointer type.
typedef int(* OSRTStreamResetProc )(struct OSRTSTREAM *pStream)
 Stream reset function pointer type.

Functions

EXTERNRT int rtxStreamClose (OSCTXT *pctxt)
 This function closes the input or output stream and releases any system resources associated with the stream.
EXTERNRT int rtxStreamFlush (OSCTXT *pctxt)
 This function flushes the output stream and forces any buffered output octets to be written out.
EXTERNRT int rtxStreamInit (OSCTXT *pctxt)
 This function initializes a stream part of the context block.
EXTERNRT long rtxStreamRead (OSCTXT *pctxt, OSOCTET *pbuffer, size_t bufSize)
 This function reads up to 'bufsize' bytes of data from the input stream into an array of octets.
EXTERNRT long rtxStreamBlockingRead (OSCTXT *pctxt, OSOCTET *pbuffer, size_t readBytes)
 This function reads up to 'bufsize' bytes of data from the input stream into an array of octets.
EXTERNRT int rtxStreamSkip (OSCTXT *pctxt, size_t skipBytes)
 This function skips over and discards the specified amount of data octets from this input stream.
EXTERNRT long rtxStreamWrite (OSCTXT *pctxt, const OSOCTET *data, size_t numocts)
 This function writes the specified amount of octets from the specified array to the output stream.
EXTERNRT int rtxStreamGetIOBytes (OSCTXT *pctxt, size_t *pPos)
 This function returns the number of processed octets.
EXTERNRT int rtxStreamMark (OSCTXT *pctxt, size_t readAheadLimit)
 Marks the current position in this input stream.
EXTERNRT int rtxStreamReset (OSCTXT *pctxt)
 Repositions this stream to the position recorded by the last call to the rtxStreamMark function.
EXTERNRT OSBOOL rtxStreamMarkSupported (OSCTXT *pctxt)
 Tests if this input stream supports the mark and reset methods.
EXTERNRT OSBOOL rtxStreamIsOpened (OSCTXT *pctxt)
 Tests if this stream opened (for reading or writing).
EXTERNRT OSBOOL rtxStreamIsReadable (OSCTXT *pctxt)
 Tests if this stream opened for reading.
EXTERNRT OSBOOL rtxStreamIsWritable (OSCTXT *pctxt)
 Tests if this stream opened for writing.
EXTERNRT int rtxStreamRelease (OSCTXT *pctxt)
 This function releases the stream's resources.
EXTERNRT void rtxStreamSetCapture (OSCTXT *pctxt, OSRTMEMBUF *pmembuf)
 This function sets a capture buffer for the stream.
EXTERNRT OSRTMEMBUF * rtxStreamGetCapture (OSCTXT *pctxt)
 This function returns the capture buffer currently assigned to the stream.

Detailed Description

Stream functions are used for unbuffered stream operations.

All of the operations with streams are performed using a context block to maintain state information.

These functions may be used for any input/output operations with streams. Each stream should be initialized first by call to the rtxStreamInit function. After initialization, the stream may be opened for reading or writing by calling one of the following functions:

Typedef Documentation

typedef long(* OSRTStreamBlockingReadProc)(struct OSRTSTREAM *pStream, OSOCTET *pbuffer, size_t toReadBytes)
 

Stream blockingRead function pointer type.

A user may implement a customized read function for specific input streams. The blockingRead function is defined in the OSRTSTREAM control structure.

Definition at line 73 of file rtxStream.h.

typedef int(* OSRTStreamCloseProc)(struct OSRTSTREAM *pStream)
 

Stream close function pointer type.

A user may implement a customized close function for any specific input or output streams. The close function is defined in the OSRTSTREAM control structure.

Definition at line 95 of file rtxStream.h.

typedef int(* OSRTStreamFlushProc)(struct OSRTSTREAM *pStream)
 

Stream flush function pointer type.

A user may implement a customized flush function for any specific output streams. The flush function is defined in the OSRTSTREAM control structure.

Definition at line 88 of file rtxStream.h.

typedef int(* OSRTStreamMarkProc)(struct OSRTSTREAM *pStream, size_t readAheadLimit)
 

Stream mark function pointer type.

A user may implement a customized function for a specific input stream type. The mark function is defined in the OSRTSTREAM control structure.

Definition at line 111 of file rtxStream.h.

typedef long(* OSRTStreamReadProc)(struct OSRTSTREAM *pStream, OSOCTET *pbuffer, size_t bufSize)
 

Stream read function pointer type.

A user may implement a customized read function for specific input streams. The read function is defined in the OSRTSTREAM control structure.

Definition at line 65 of file rtxStream.h.

typedef int(* OSRTStreamResetProc)(struct OSRTSTREAM *pStream)
 

Stream reset function pointer type.

A user may implement a customized function for a specific input stream type. The reset function is defined in the OSRTSTREAM control structure.

Definition at line 118 of file rtxStream.h.

typedef int(* OSRTStreamSkipProc)(struct OSRTSTREAM *pStream, size_t skipBytes)
 

Stream skip function pointer type.

A user may implement a customized function for a specific input stream type. The skip function is defined in the OSRTSTREAM control structure.

Definition at line 103 of file rtxStream.h.

typedef long(* OSRTStreamWriteProc)(struct OSRTSTREAM *pStream, const OSOCTET *data, size_t numocts)
 

Stream write function pointer type.

A user may implement a customized write function for any specific output streams. The write function is defined in the OSRTSTREAM control structure.

Definition at line 80 of file rtxStream.h.

Function Documentation

EXTERNRT long rtxStreamBlockingRead (  OSCTXT *  pctxt,
OSOCTET *  pbuffer,
size_t  readBytes
) 
 

This function reads up to 'bufsize' bytes of data from the input stream into an array of octets.

An attempt is made to read as many as bufsize octets, but a smaller number may be read, possibly zero. The number of octets actually read is returned as an integer. This functions blocks until input data is available, end of file is detected, or another error is occurred.

Parameters:
pctxt Pointer to a context structure variable which has been initialized for stream operations via a call to rtxStreamInit.
pbuffer Pointer to a buffer to receive data.
readBytes Number of bytes to read.
Returns:
The total number of octets read into the buffer, or negative value with error code if any error is occurred.

EXTERNRT int rtxStreamClose (  OSCTXT *  pctxt  ) 
 

This function closes the input or output stream and releases any system resources associated with the stream.

For output streams this function also flushes all internal buffers to the stream.

Parameters:
pctxt Pointer to a context structure variable which has been initialized for stream operations via a call to rtxStreamInit.

EXTERNRT int rtxStreamFlush (  OSCTXT *  pctxt  ) 
 

This function flushes the output stream and forces any buffered output octets to be written out.

Parameters:
pctxt Pointer to a context structure variable which has been initialized for stream operations via a call to rtxStreamInit.
Returns:
Completion status of operation: 0 = success, negative return value is error.

EXTERNRT OSRTMEMBUF* rtxStreamGetCapture (  OSCTXT *  pctxt  ) 
 

This function returns the capture buffer currently assigned to the stream.

Parameters:
pctxt Pointer to a context structure variable that has been initialized for stream operations.
pmembuf Pointer to an initialized memory buffer structure. This argument may be set to NULL to disable capture if previously set.
Returns:
Pointer to memory buffer that was previously assigned as a capture buffer to the stream.

EXTERNRT int rtxStreamGetIOBytes (  OSCTXT *  pctxt,
size_t *  pPos
) 
 

This function returns the number of processed octets.

If the stream was opened as an input stream, then it returns the total number of read octets. If the stream was opened as an output stream, then it returns the total number of written octets. Otherwise, this function returns an error code.

Parameters:
pctxt Pointer to a context structure variable which has been initialized for stream operations via a call to rtxStreamInit.
pPos Pointer to argument to receive total number of processed octets.
Returns:
The total number of processed octets or error code (negative value).

EXTERNRT int rtxStreamInit (  OSCTXT *  pctxt  ) 
 

This function initializes a stream part of the context block.

This function should be called first before any operation with a stream.

Parameters:
pctxt Pointer to context structure variable, for which stream to be initialized.
Returns:
Completion status of operation: 0 = success, negative return value is error.

EXTERNRT OSBOOL rtxStreamIsOpened (  OSCTXT *  pctxt  ) 
 

Tests if this stream opened (for reading or writing).

Parameters:
pctxt Pointer to a context structure variable that has been initialized for stream operations.
Returns:
TRUE if this stream is opened for reading or writing; FALSE otherwise.

EXTERNRT OSBOOL rtxStreamIsReadable (  OSCTXT *  pctxt  ) 
 

Tests if this stream opened for reading.

Parameters:
pctxt Pointer to a context structure variable that has been initialized for stream operations.
Returns:
TRUE if this stream is opened for reading; FALSE otherwise.

EXTERNRT OSBOOL rtxStreamIsWritable (  OSCTXT *  pctxt  ) 
 

Tests if this stream opened for writing.

Parameters:
pctxt Pointer to a context structure variable that has been initialized for stream operations.
Returns:
TRUE if this stream is opened for writing; FALSE otherwise.

EXTERNRT int rtxStreamMark (  OSCTXT *  pctxt,
size_t  readAheadLimit
) 
 

Marks the current position in this input stream.

A subsequent call to the rtxStreamReset function repositions this stream at the last marked position so that subsequent reads re-read the same bytes. The readAheadLimit argument tells this input stream to allow many bytes to be read before the mark position gets invalidated.

Parameters:
pctxt Pointer to a context structure variable that has been initialized for stream operations.
readAheadLimit The maximum limit of bytes that can be read before the mark position becomes invalid.
Returns:
Completion status of operation: 0 = success, negative return value is error.

EXTERNRT OSBOOL rtxStreamMarkSupported (  OSCTXT *  pctxt  ) 
 

Tests if this input stream supports the mark and reset methods.

Whether or not mark and reset are supported is an invariant property of a particular input stream instance. By default, it returns FALSE.

Parameters:
pctxt Pointer to a context structure variable that has been initialized for stream operations.
Returns:
TRUE if this stream instance supports the mark and reset methods; FALSE otherwise.

EXTERNRT long rtxStreamRead (  OSCTXT *  pctxt,
OSOCTET *  pbuffer,
size_t  bufSize
) 
 

This function reads up to 'bufsize' bytes of data from the input stream into an array of octets.

An attempt is made to read as many as bufsize octets, but a smaller number may be read, possibly zero. The number of octets actually read is returned as an integer. This functions blocks until input data is available, end of file is detected, or another error is occurred.

Parameters:
pctxt Pointer to a context structure variable which has been initialized for stream operations via a call to rtxStreamInit.
pbuffer Pointer to a buffer to receive data.
bufSize Size of the buffer.
Returns:
The total number of octets read into the buffer, or negative value with error code if any error is occurred.

EXTERNRT int rtxStreamRelease (  OSCTXT *  pctxt  ) 
 

This function releases the stream's resources.

If it is opened for reading or writing it will be closed.

Parameters:
pctxt Pointer to a context structure variable that has been initialized for stream operations.
Returns:
Completion status of operation: 0 = success, negative return value is error.

EXTERNRT int rtxStreamReset (  OSCTXT *  pctxt  ) 
 

Repositions this stream to the position recorded by the last call to the rtxStreamMark function.

Parameters:
pctxt Pointer to a context structure variable that has been initialized for stream operations.
Returns:
Completion status of operation: 0 = success, negative return value is error.

EXTERNRT void rtxStreamSetCapture (  OSCTXT *  pctxt,
OSRTMEMBUF *  pmembuf
) 
 

This function sets a capture buffer for the stream.

This is used to record all data read from the stream.

Parameters:
pctxt Pointer to a context structure variable that has been initialized for stream operations.
pmembuf Pointer to an initialized memory buffer structure. This argument may be set to NULL to disable capture if previously set.

EXTERNRT int rtxStreamSkip (  OSCTXT *  pctxt,
size_t  skipBytes
) 
 

This function skips over and discards the specified amount of data octets from this input stream.

Parameters:
pctxt Pointer to a context structure variable which has been initialized for stream operations via a call to rtxStreamInit.
skipBytes The number of octets to be skipped.
Returns:
Completion status of operation: 0 = success, negative return value is error.

EXTERNRT long rtxStreamWrite (  OSCTXT *  pctxt,
const OSOCTET *  data,
size_t  numocts
) 
 

This function writes the specified amount of octets from the specified array to the output stream.

Parameters:
pctxt Pointer to a context structure variable which has been initialized for stream operations via a call to rtxStreamInit.
data The pointer to data to be written.
numocts The number of octets to write.
Returns:
Completion status of operation: 0 = success, negative return value is error.