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

Classes
struct	OSRTSTREAM
	The stream control block. More...

Macros
#define	rtxStreamBlockingRead rtxStreamRead
	rtxStreamBlockingRead is deprecated. More...

Typedefs
typedef long(*	OSRTStreamReadProc) (struct OSRTSTREAM pStream, OSOCTET pbuffer, size_t nocts)
	Stream read function pointer type. More...

typedef OSRTStreamReadProc	OSRTStreamBlockingReadProc
	OSRTStreamBlockingReadProc is deprecated. More...

typedef long(*	OSRTStreamWriteProc) (struct OSRTSTREAM pStream, const OSOCTET data, size_t numocts)
	Stream write function pointer type. More...

typedef int(*	OSRTStreamFlushProc) (struct OSRTSTREAM *pStream)
	Stream flush function pointer type. More...

typedef int(*	OSRTStreamCloseProc) (struct OSRTSTREAM *pStream)
	Stream close function pointer type. More...

typedef int(*	OSRTStreamSkipProc) (struct OSRTSTREAM *pStream, size_t skipBytes)
	Stream skip function pointer type. More...

typedef int(*	OSRTStreamMarkProc) (struct OSRTSTREAM *pStream, size_t readAheadLimit)
	Stream mark function pointer type. More...

typedef int(*	OSRTStreamResetProc) (struct OSRTSTREAM *pStream)
	Stream reset function pointer type. More...

typedef int(*	OSRTStreamGetPosProc) (struct OSRTSTREAM pStream, size_t ppos)
	Stream get position function pointer type. More...

typedef int(*	OSRTStreamSetPosProc) (struct OSRTSTREAM *pStream, size_t pos)
	Stream set position function pointer type. More...

typedef struct OSRTSTREAM	OSRTSTREAM
	The stream control block. More...

Functions
EXTERNRT int	rtxStreamClose (OSCTXT *pctxt)
	This function closes the input or output stream and releases any system resources associated with the stream. More...

EXTERNRT int	rtxStreamFlush (OSCTXT *pctxt)
	This function flushes the output stream and forces any buffered output octets to be written out. More...

EXTERNRT int	rtxStreamLoadInputBuffer (OSCTXT *pctxt, OSSIZE nbytes)
	This is for meant for internal use by the runtime. More...

EXTERNRT int	rtxStreamInit (OSCTXT *pctxt)
	This function initializes a stream part of the context block. More...

EXTERNRT int	rtxStreamInitCtxtBuf (OSCTXT *pctxt)
	This function initializes a stream to use the context memory buffer for stream buffering. More...

EXTERNRT int	rtxStreamRemoveCtxtBuf (OSCTXT *pctxt)
	This function removes the use of a context memory buffer from a stream. More...

EXTERNRT long	rtxStreamRead (OSCTXT pctxt, OSOCTET pbuffer, size_t nocts)
	Read up to nocts bytes of data from the input stream into an array of octets. More...

EXTERNRT long	rtxStreamRead2 (OSCTXT pctxt, OSOCTET pbuffer, size_t nocts, size_t bufSize)
	Attempt to read nocts bytes from the input stream into an array of octets. More...

EXTERNRT int	rtxStreamSkip (OSCTXT *pctxt, size_t skipBytes)
	This function skips over and discards the specified amount of data octets from this input stream. More...

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. More...

EXTERNRT int	rtxStreamGetIOBytes (OSCTXT pctxt, size_t pPos)
	This function returns the number of processed octets. More...

EXTERNRT int	rtxStreamMark (OSCTXT *pctxt, size_t readAheadLimit)
	Marks the current position in this input stream. More...

EXTERNRT int	rtxStreamReset (OSCTXT *pctxt)
	Repositions this stream to the position recorded by the last call to the rtxStreamMark function. More...

EXTERNRT OSBOOL	rtxStreamMarkSupported (OSCTXT *pctxt)
	Tests if this input stream supports the mark and reset methods. More...

EXTERNRT OSBOOL	rtxStreamIsOpened (OSCTXT *pctxt)
	Tests if this stream opened (for reading or writing). More...

EXTERNRT OSBOOL	rtxStreamIsReadable (OSCTXT *pctxt)
	Tests if this stream opened for reading. More...

EXTERNRT OSBOOL	rtxStreamIsWritable (OSCTXT *pctxt)
	Tests if this stream opened for writing. More...

EXTERNRT int	rtxStreamRelease (OSCTXT *pctxt)
	This function releases the stream's resources. More...

EXTERNRT void	rtxStreamSetCapture (OSCTXT pctxt, OSRTMEMBUF pmembuf)
	This function sets a capture buffer for the stream. More...

EXTERNRT OSRTMEMBUF *	rtxStreamGetCapture (OSCTXT *pctxt)
	This function returns the capture buffer currently assigned to the stream. More...

EXTERNRT int	rtxStreamGetPos (OSCTXT pctxt, size_t ppos)
	Get the current position in input stream. More...

EXTERNRT int	rtxStreamSetPos (OSCTXT *pctxt, size_t pos)
	Set the current position in input stream. More...

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:

rtxStreamFileOpen
rtxStreamFileAttach
rtxStreamSocketAttach
rtxStreamMemoryCreate
rtxStreamMemoryAttach

Macro Definition Documentation

◆ rtxStreamBlockingRead

#define rtxStreamBlockingRead rtxStreamRead

rtxStreamBlockingRead is deprecated.

Use rtxStreamRead.

Definition at line 344 of file rtxStream.h.

Typedef Documentation

◆ OSRTSTREAM

typedef struct OSRTSTREAM OSRTSTREAM

The stream control block.

A user may implement a customized stream by defining read, skip, close functions for input streams and write, flush, close for output streams.

◆ OSRTStreamBlockingReadProc

typedef OSRTStreamReadProc OSRTStreamBlockingReadProc

OSRTStreamBlockingReadProc is deprecated.

Use OSRTStreamReadProc.

Definition at line 83 of file rtxStream.h.

◆ OSRTStreamCloseProc

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 105 of file rtxStream.h.

◆ OSRTStreamFlushProc

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 98 of file rtxStream.h.

◆ OSRTStreamGetPosProc

typedef int(* OSRTStreamGetPosProc) (struct OSRTSTREAM *pStream, size_t *ppos)

Stream get position 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 136 of file rtxStream.h.

◆ OSRTStreamMarkProc

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 121 of file rtxStream.h.

◆ OSRTStreamReadProc

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

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.

The read function may read fewer bytes than requested, but it will read at least one byte (assuming nocts > 0) unless EOF is reached or there is an error. Thus, if nocts > 0, this will return 0 only if EOF is reached. Reaching EOF shall not be considered an error.

Parameters

pStream	Identifies the stream control structure.
pbuffer	is the buffer into which bytes shall be read.
nocts	is the number of bytes to be read; the buffer must be at least this large.

Returns: The number of bytes read (possibly 0), or a negative error code.

Definition at line 78 of file rtxStream.h.

◆ OSRTStreamResetProc

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 128 of file rtxStream.h.

◆ OSRTStreamSetPosProc

typedef int(* OSRTStreamSetPosProc) (struct OSRTSTREAM *pStream, size_t pos)

Stream set position 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 144 of file rtxStream.h.

◆ OSRTStreamSkipProc

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 113 of file rtxStream.h.

◆ OSRTStreamWriteProc

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 90 of file rtxStream.h.

Function Documentation

◆ rtxStreamClose()

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.

◆ rtxStreamFlush()

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.

◆ rtxStreamGetCapture()

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.

Returns: Pointer to memory buffer that was previously assigned as a capture buffer to the stream.

◆ rtxStreamGetIOBytes()

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).

◆ rtxStreamGetPos()

EXTERNRT int rtxStreamGetPos	(	OSCTXT *	pctxt,
		size_t *	ppos
	)

Get the current position in input stream.

Parameters

pctxt	Pointer to a context structure variable that has been initialized for stream operations.
ppos	Pointer to a variable to receive position.

Returns: Completion status of operation: 0 = success, negative return value is error.

◆ rtxStreamInit()

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.

◆ rtxStreamInitCtxtBuf()

EXTERNRT int rtxStreamInitCtxtBuf ( OSCTXT * pctxt )

This function initializes a stream to use the context memory buffer for stream buffering.

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.

◆ rtxStreamIsOpened()

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.

◆ rtxStreamIsReadable()

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.

◆ rtxStreamIsWritable()

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.

◆ rtxStreamLoadInputBuffer()

EXTERNRT int rtxStreamLoadInputBuffer	(	OSCTXT *	pctxt,
		OSSIZE	nbytes
	)

This is for meant for internal use by the runtime.

Read at least as many bytes, from the context's input stream into the context buffer, as necessary to make nbytes of data available in the context buffer.

Upon return, pctxt.buffer.byteIndex + nbytes <= pctxt.buffer.size OR EOF has been reached OR an error has been logged and is being returned.

If the context buffer has not been created, this will create it. If the context buffer needs to be made larger, this will enlarge it or else log, and return, an error.

Any bytes read from the stream will be sent to the capture buffer, if there is one.

Parameters

pctxt A context with an attached stream using the context's buffer as a buffer for the stream.

Returns: 0 or or negative error. EOF is not considered an error.

◆ rtxStreamMark()

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.

◆ rtxStreamMarkSupported()

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.

◆ rtxStreamRead()

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

Read up to nocts bytes of data from the input stream into an array of octets.

This function blocks until nocts of data are read, end of file is detected, or an error occurs. EOF is not treated as an error.

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.
nocts	Number of bytes to read.

Returns: The total number of octets read into pbuffer, or negative value with error code if an error occurs.

◆ rtxStreamRead2()

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

Attempt to read nocts bytes from the input stream into an array of octets.

It may read more bytes (as many as bufSize). It may read fewer bytes if end of file is detected or an error occurs. EOF is not treated as an error.

This function blocks until nocts of data are read, end of file is detected, or an error occurs. EOF is not treated as an error.

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.
nocts	Number of octets to read; nocts >= 1
bufSize	Size of the buffer.

Returns: The total number of octets read into pbuffer, or negative value with error code if an error occurs.

◆ rtxStreamRelease()

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.

◆ rtxStreamRemoveCtxtBuf()

EXTERNRT int rtxStreamRemoveCtxtBuf ( OSCTXT * pctxt )

This function removes the use of a context memory buffer from a stream.

Parameters

pctxt Pointer to context structure variable which is assumed to contain an initialized stream with context buffering enabled.

Returns: Completion status of operation: 0 = success, negative return value is error.

◆ rtxStreamReset()

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.

◆ rtxStreamSetCapture()

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.

◆ rtxStreamSetPos()

EXTERNRT int rtxStreamSetPos	(	OSCTXT *	pctxt,
		size_t	pos
	)

Set the current position in input stream.

Parameters

pctxt	Pointer to a context structure variable that has been initialized for stream operations.
pos	Stream position.

Returns: Completion status of operation: 0 = success, negative return value is error.

◆ rtxStreamSkip()

EXTERNRT int rtxStreamSkip	(	OSCTXT *	pctxt,
		size_t	skipBytes
	)

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

An attempt to skip past the end of the input is an error. (This skips bytes of input, which may be held in a buffer, so it does not necessarily skip bytes in the underlying stream. Also, pctxt->buffer.bitOffset is irrelevant to this function.)

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.

◆ rtxStreamWrite()

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.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ rtxStreamBlockingRead

Typedef Documentation

◆ OSRTSTREAM

◆ OSRTStreamBlockingReadProc

◆ OSRTStreamCloseProc

◆ OSRTStreamFlushProc

◆ OSRTStreamGetPosProc

◆ OSRTStreamMarkProc

◆ OSRTStreamReadProc

◆ OSRTStreamResetProc

◆ OSRTStreamSetPosProc

◆ OSRTStreamSkipProc

◆ OSRTStreamWriteProc

Function Documentation

◆ rtxStreamClose()

◆ rtxStreamFlush()

◆ rtxStreamGetCapture()

◆ rtxStreamGetIOBytes()

◆ rtxStreamGetPos()

◆ rtxStreamInit()

◆ rtxStreamInitCtxtBuf()

◆ rtxStreamIsOpened()

◆ rtxStreamIsReadable()

◆ rtxStreamIsWritable()

◆ rtxStreamLoadInputBuffer()

◆ rtxStreamMark()

◆ rtxStreamMarkSupported()

◆ rtxStreamRead()

◆ rtxStreamRead2()

◆ rtxStreamRelease()

◆ rtxStreamRemoveCtxtBuf()

◆ rtxStreamReset()

◆ rtxStreamSetCapture()

◆ rtxStreamSetPos()

◆ rtxStreamSkip()

◆ rtxStreamWrite()