rtxBuffer.h File Reference

Common runtime functions for reading from or writing to the message buffer defined within the context structure. More...

#include "rtxsrc/rtxContext.h"
#include "rtxsrc/rtxSList.h"

Go to the source code of this file.

Classes
struct	_OSRTBufLocDescr
	Buffer location descriptor. More...
Typedefs
typedef struct _OSRTBufLocDescr	OSRTBufLocDescr
	Buffer location descriptor.
Functions
EXTERNRT int	rtxCheckOutputBuffer (OSCTXT *pctxt, size_t nbytes)
	This function checks to ensure that the output buffer has sufficient space to hold the requested number of bytes.
EXTERNRT int	rtxExpandOutputBuffer (OSCTXT *pctxt, size_t nbytes)
	This function attempts to expand the output buffer by the requested number of bytes.
EXTERNRT int	rtxReadBytesSafe (OSCTXT *pctxt, OSOCTET *buffer, size_t bufsize, size_t nocts)
	This function safely reads bytes from the currently open stream or memory buffer into the given static buffer.
EXTERNRT int	rtxReadBytes (OSCTXT *pctxt, OSOCTET *pdata, size_t nocts)
	This function reads bytes from the currently open stream or memory buffer.
EXTERNRT int	rtxReadBytesDynamic (OSCTXT *pctxt, OSOCTET **ppdata, size_t nocts, OSBOOL *pMemAlloc)
	This function reads bytes from the currently open stream or memory buffer.
EXTERNRT int	rtxWriteBytes (OSCTXT *pctxt, const OSOCTET *pdata, size_t nocts)
	This function writes bytes to the currently open stream or memory buffer.
EXTERNRT int	rtxEncCanonicalSort (OSCTXT *pctxt, OSCTXT *pMemCtxt, OSRTSList *pList)
	Encode the encodings held in pMemCtxt into pctxt, first sorting them as required for canonical BER (and other encoding rules) by X.690 11.6.
EXTERNRT void	rtxGetBufLocDescr (OSCTXT *pctxt, OSRTBufLocDescr *pDescr)
	Set the buffer location description's offset (pDescr->offset) to the current position in pCtxt's buffer.
EXTERNRT void	rtxAddBufLocDescr (OSCTXT *pctxt, OSRTSList *pElemList, OSRTBufLocDescr *pDescr)
	Create a new Asn1BufLocDescr for an element just encoded and append it to pElemList.

---

Detailed Description

Common runtime functions for reading from or writing to the message buffer defined within the context structure.

Definition in file rtxBuffer.h.

---

Function Documentation

EXTERNRT void rtxAddBufLocDescr	(	OSCTXT *	pctxt,
		OSRTSList *	pElemList,
		OSRTBufLocDescr *	pDescr
	)

Create a new Asn1BufLocDescr for an element just encoded and append it to pElemList.

Parameters:

	pctxt	Pointer to context where data has been encoded.
	pElemList	List of Asn1BufLocDescr to which a new entry will be added.
	pDescr	Pointer to Asn1BufLocDescr whose offset indicates the start of the element just encoded. The new Asn1BufLocDescr that is added will have the same offset and will have numocts determined by this offset and pctxt's current buffer position.

EXTERNRT int rtxCheckOutputBuffer	(	OSCTXT *	pctxt,
		size_t	nbytes
	)

This function checks to ensure that the output buffer has sufficient space to hold the requested number of bytes.

Dynamic buffers are resized if the check fails, while static buffers induce a buffer overflow error. This function may return RTERR_NOMEM if reallocating the dynamic buffer fails.

Parameters:

	pctxt	Pointer to a context structure.
	nbytes	The requested capacity for the buffer.

Returns:

0 on success, or less than zero on failure.

EXTERNRT int rtxEncCanonicalSort	(	OSCTXT *	pctxt,
		OSCTXT *	pMemCtxt,
		OSRTSList *	pList
	)

Encode the encodings held in pMemCtxt into pctxt, first sorting them as required for canonical BER (and other encoding rules) by X.690 11.6.

Parameters:

	pctxt	Pointer to context structure into which the sorted encodings should be encoded.
	pMemCtxt	Pointer to context structure which holds the unsorted encodings.
	pList	List of Asn1BufLocDescr, each of which locates an encoding in pMemCtxt's buffer, the whole being the encodings that are to be sorted.

EXTERNRT int rtxExpandOutputBuffer	(	OSCTXT *	pctxt,
		size_t	nbytes
	)

This function attempts to expand the output buffer by the requested number of bytes.

Dynamic buffers are resized if the check fails, while static buffers induce a buffer overflow error. This function may return RTERR_NOMEM if reallocating the dynamic buffer fails.

Parameters:

	pctxt	Pointer to a context structure.
	nbytes	The requested capacity for the buffer.

Returns:

0 on success, or less than zero on failure.

EXTERNRT int rtxReadBytes	(	OSCTXT *	pctxt,
		OSOCTET *	pdata,
		size_t	nocts
	)

This function reads bytes from the currently open stream or memory buffer.

Parameters:

	pctxt	Pointer to a context structure.
	pdata	Pointer to byte array where bytes are to be copied.
	nocts	Number of bytes (octets) to read.

Returns:

Status of the operation: 0 if success, negative value if error.

EXTERNRT int rtxReadBytesDynamic	(	OSCTXT *	pctxt,
		OSOCTET **	ppdata,
		size_t	nocts,
		OSBOOL *	pMemAlloc
	)

This function reads bytes from the currently open stream or memory buffer.

In this case the function MAY allocate memory to hold the read bytes. It will only do this if the requested number of bytes will not fit in the context buffer; othwerwise, a pointer to a location in the context buffer is returned. If memory was allocated, it should be freed using rtxMemFreePtr.

Parameters:

	pctxt	Pointer to a context structure.
	ppdata	Pointer to byte buffer pointer.
	nocts	Number of bytes (octets) to read.
	pMemAlloc	Pointer to boolean value which is set to true if memory was allocated to hold requested bytes.

Returns:

Status of the operation: 0 if success, negative value if error.

EXTERNRT int rtxReadBytesSafe	(	OSCTXT *	pctxt,
		OSOCTET *	buffer,
		size_t	bufsize,
		size_t	nocts
	)

This function safely reads bytes from the currently open stream or memory buffer into the given static buffer.

This function is preferred over rtxReadBytes because it will detect buffer overflow.

Parameters:

	pctxt	Pointer to a context structure.
	buffer	Static buffer into which bytes are to be read.
	bufsize	Size of the static buffer.
	nocts	Number of bytes (octets) to read.

Returns:

Status of the operation: 0 if success, negative value if error.

EXTERNRT int rtxWriteBytes	(	OSCTXT *	pctxt,
		const OSOCTET *	pdata,
		size_t	nocts
	)

This function writes bytes to the currently open stream or memory buffer.

Parameters:

	pctxt	Pointer to a context structure.
	pdata	Pointer to location where bytes are to be copied.
	nocts	Number of bytes to read.

Returns:

I/O byte count.