RSA BSAFE Cert-C API Reference

certio.h File Reference

This file defines the i/o interface.

#include "basetype.h"
#include "service.h"

Go to the source code of this file.

Typedefs
typedef POINTER	STREAM
	Use the STREAM handle to represent an open input or output stream when calling Cert-C file stream functions, such as C_ReadStream().
Functions
int	C_OpenStream (CERTC_CTX ctx, char *serviceName, POINTER streamName, unsigned int flags, STREAM *stream)
	Opens a stream managed by the specified service provider. More...
int	C_CloseStream (STREAM stream)
	Closes a previously opened I/O stream. More...
int	C_GetStreamLine (STREAM stream, char *str, unsigned int maxLen)
	Reads one line of characters, terminated by a newline character ('\n'). More...
int	C_PutStreamLine (STREAM stream, char *str)
	Writes a NUL-terminated string to the specified stream, followed by a newline character ('\n'). More...
int	C_ReadStream (STREAM stream, unsigned char *buf, unsigned int len, unsigned int *actualLen)
	Attempts to read the indicated number of bytes from the specified stream. More...
int	C_WriteStream (STREAM stream, unsigned char *buf, unsigned int len)
	Writes the indicated number of bytes to the specified stream. More...
int	C_RewindStream (STREAM stream)
	Repositions the point in the stream where the subsequent I/O occurs, to the beginning of that stream. More...

---

Function Documentation

int C_CloseStream (  STREAM    stream )  ;

Closes a previously opened I/O stream. Parameters: stream This input parameter is a stream handle that was returned by a previous call to C_OpenStream(). Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_GetStreamLine (  STREAM    stream, char *    str, unsigned int    maxLen )  ;

Reads one line of characters, terminated by a newline character ('\n'). C_GetStreamLine() reads characters from the current position in the stream up to and including the next newline character. It copies the characters read, except the newline character, into the indicated string buffer and appends a null character to the end of the string. If maxLen - 1 characters are read without a newline, C_GetStreamLine() copies the characters read to the string buffer, and null-terminates the buffer. Note that the definition of the end-of-line condition is determined by the service provider. In some cases, the end of a line may be defined as a sequence of two or more characters. If so, all of the characters in the newline sequence are read in by the service provider and translated to a single standard newline character ('\n'), which is returned to C_GetStreamLine(). Parameters: stream This input parameter is a stream handle returned by a previous call to C_OpenStream(). str This output parameter points to a buffer where characters from the line being read are copied. maxLen This input parameter determines the maximum number of characters that are read by C_GetStreamLine(). The function stops after reading maxLen - 1 characters without reading a newline. Returns: If successful, returns 0. If not, returns a Cert-C error code. The Cert-C error status E_EOS is returned when the end-of-stream is reached.

int C_OpenStream (  CERTC_CTX    ctx, char *    serviceName, POINTER    streamName, unsigned int    flags, STREAM *    stream )  ;

Opens a stream managed by the specified service provider. Parameters: ctx This input parameter points to an initialized Cert-C context. serviceName This input parameter contains the registered name of an I/O service provider. streamName This input parameter points to the name of the stream to open. The specific data type of the stream name depends on the service provider to be used. For example, if the application is using the standard file I/O service provider, the stream name is a NUL-terminated string containing the name of the file to open. In the case of a stream filter, the stream name might be the handle of another open stream. flags This input parameter contains flags that can modify the behavior of the service provider for this stream. The flags should be one or more of the IO_* constants combined by the bitwise 'OR' operator. I/O Stream Flag Description IO_RDONLY The stream is opened for input only. Calls to C_PutStreamLine() and C_Write() will fail. IO_WRONLY The stream is opened for writing only. Calls to C_GetStreamLine() and C_Read() will fail. IO_RDWR The stream is opened for reading and writing. Before switching from reading to writing, or vice versa, the application should first call C_Rewind(). IO_CREAT If the stream being opened does not already exist, it is created. IO_TRUNC If the stream being opened already exists, its previous contents are deleted. IO_EXCL If the stream being opened already exists, the C_Open() call will fail. This flag is usually combined with IO_CREAT. IO_TEXT Indicates the stream being opened contains text characters. This might cause some service providers to translate certain character sequences such as the end-of-line indicator into the standard 'C'-string representation for that character. IO_BINARY Indicates the stream being opened contains binary bytes. The service provider is requested not to translate. stream This output parameter points to where the initialized stream handle is stored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_PutStreamLine (  STREAM    stream, char *    str )  ;

Writes a NUL-terminated string to the specified stream, followed by a newline character ('\n'). Parameters: stream This input parameter is a stream handle returned by a previous call to C_OpenStream(). str This input parameter points to a NUL-terminated string of characters. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_ReadStream (  STREAM    stream, unsigned char *    buf, unsigned int    len, unsigned int *    actualLen )  ;

Attempts to read the indicated number of bytes from the specified stream. If the end of the stream is reached before the requested number of bytes is read, the actual number of bytes read is returned in the actualLen parameter. Parameters: stream This input parameter is a stream handle returned by a previous call to C_OpenStream(). buf This output parameter points to a buffer that stores a copy of the bytes that are read from the stream. len This input parameter is the requested number of bytes to be read from the stream. actualLen This output parameter points to a number that is the actual number of bytes that are read from the stream. The actual number of bytes read may be less than or equal to the number of bytes requested. Returns: If successful, returns 0. If not, returns a Cert-C error code. The Cert-C status code E_EOS is returned only when the end-of-stream is reached.

int C_RewindStream (  STREAM    stream )  ;

Repositions the point in the stream where the subsequent I/O occurs, to the beginning of that stream. This function may do nothing if the stream is an interactive communications channel. If the application has opened a stream for both reading and writing, it should call C_RewindStream() before switching from reading to writing or from writing to reading. Parameters: stream This input parameter is a stream handle that a previous call returns to C_OpenStream(). Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_WriteStream (  STREAM    stream, unsigned char *    buf, unsigned int    len )  ;

Writes the indicated number of bytes to the specified stream. Parameters: stream This input and output parameter is a stream handle returned by a previous call to C_OpenStream(). buf This input parameter points to the array of bytes to write to the stream. len This input parameter indicates the number of bytes to write to the stream. Returns: If successful, returns 0. If not, returns a Cert-C error code.

---

RSA BSAFE^® Cert-C 2.7 API Reference