aStream.h¶

group aStream

Platform Independent Stream Abstraction.

aStream.h provides a platform independent stream abstraction for common I/O streams. Provides facilities for creating and destroying as well as writing and reading from streams.

typedef void *aStreamRef¶: Typedef aStreamRef Opaque reference to stream primitive.

group StreamCallbacks

Typedefs

typedef aErr (*aStreamGetProc)(uint8_t *pData, void *ref)¶

Typedef aStreamGetProc.

This callback is defined to read one byte from the concrete stream implementation.

Return

Function returns aErr values.

Parameters

pData: The data Buffer to fill.
ref: Opaque reference to concrete stream implementation.

Return Value

aErrNone: Successfully read the byte.
aErrNotReady: No bytes in stream to read.
aErrEOF: Reached the end of the stream.
aErrIO: An error encountered reading from stream.

typedef aErr (*aStreamPutProc)(const uint8_t *pData, void *ref)¶

Typedef aStreamPutProc.

This callback is defined to write one byte to the concrete stream implementation.

Return

Function returns aErr values.

Parameters

pData: The data Buffer to write.
ref: opaque reference to concrete stream implementation.

Return Value

aErrNone: Successfully wrote the byte.
aErrIO: An error encountered reading from stream.

typedef aErr (*aStreamDeleteProc)(void *ref)¶

Typedef aStreamDeleteProc.

This callback is defined to destroy the concrete stream implementation.

Return

Function returns aErr values.

Parameters

ref: opaque reference to concrete stream implementation.

Return Value

aErrNone: Successfully destroyed.
aErrParam: Invalid ref.

typedef aErr (*aStreamWriteProc)(const uint8_t *pData, const size_t nSize, void *ref)¶

Typedef aStreamWriteProc. (Optional)

Optional multi-byte write for efficiency, not required..

Return

Function returns aErr values.

Parameters

ref: Opaque reference to concrete stream implementation.

Return Value

aErrNone: Successfully destroyed.
aErrIO: An error encountered reading from stream.

enum aBaudRate¶

Enum aBaudRate.

Accepted serial stream baudrates.

Values:

aBAUD_2400¶: 2400 baud

aBAUD_4800¶: 4800 baud

aBAUD_9600¶: 9600 baud

aBAUD_19200¶: 19,200 baud

aBAUD_38400¶: 38,400 baud

aBAUD_57600¶: 57,600 baud

aBAUD_115200¶: 115,200 baud

aBAUD_230400¶: 230,400 buad

enum aSerial_Bits¶

Enum aSerial_Bits.

The accepted number of serial bits per byte.

Values:

aBITS_8¶: 8 bits

aBITS_7¶: 7 bits

enum aSerial_Stop_bits¶

Enum aSerial_Stop_bits.

The accepted number of serial stop bits.

Values:

aSTOP_BITS_1¶: 1 stop bit

aSTOP_BITS_2¶: 2 stop bits

aStreamRef aStream_Create(aStreamGetProc getProc, aStreamPutProc putProc, aStreamWriteProc writeProc, aStreamDeleteProc deleteProc, const void *procRef)¶

Base Stream creation procedure.

Creates a Stream Reference.

Return

Function returns aStreamRef on success and NULL on error.

Parameters

getProc: - Callback for reading bytes from the underlying stream.
putProc: - Callback for writing bytes to the underlying stream.
writeProc: - Optional callback for optimized writing of multiple bytes.
deleteProc: - Callback for safe destruction of underlying resource.
procRef: - opaque reference to the underlying resource,

aErr aStream_CreateFileInput(const char *pFilename, aStreamRef *pStreamRef)¶

Create a file input stream.

Creates a file input stream.

Return

Function returns aErr values.

Parameters

pFilename: - The filename and path of the file to read from.
pStreamRef: - The resulting stream accessor for the input file.

Return Value

aErrNone: - Successful creation.
aErrNotFound: - The file to read was not found.
aErrIO: - A communication error occured.

aErr aStream_CreateFileOutput(const char *pFilename, aStreamRef *pStreamRef)¶

Create a file output stream.

Creates a file output stream.

Return

Function returns aErr values.

Parameters

pFilename: - The filename and path of the file to write to.
pStreamRef: - The resulting stream accessor for the output file.

Return Value

aErrNone: - Successful creation.
aErrIO: - A communication error occured.

aErr aStream_CreateSerial(const char *pPortName, const aBaudRate nBaudRate, const bool parity, const aSerial_Bits bits, const aSerial_Stop_bits stop, aStreamRef *pStreamRef)¶

Create a serial communication stream.

Creates a serial stream.

Return

Function returns aErr values.

Parameters

pPortName: - The portname of the serial device.
nBaudRate: - The baudrate to connect to the device at.
parity: - Whether serial parity is enabled.
bits: - The number of bits per serial byte.
stop: - The number of stop bits per byte.
pStreamRef: - The resulting stream accessor for the serial device.

Return Value

aErrNone: - Successful creation.
aErrConnection: - The connection was unsuccessful.
aErrIO: - A communication error occured.

aErr aStream_CreateSocket(const uint32_t address, const uint16_t port, aStreamRef *pStreamRef)¶

Create a TCP/IP socket stream.

Creates a TCP/IP socket stream.

Return

Function returns aErr values.

Parameters

address: - The IP4 address of the connection.
port: - The TCP port to connect to.
pStreamRef: - The resulting stream accessor for the TCP connection.

Return Value

aErrNone: - Successful creation.
aErrConnection: - The connection was unsuccessful.
aErrIO: - A communication error occured.

aErr aStream_CreateMemory(const aMemPtr pMemory, const size_t size, aStreamRef *pStreamRef)¶

Create a stream accessor for a block of memory.

Creates a stream accessor for a block of allocated memory. Reads and Writes like any other stream. The memory stream does not make a copy of the memory and doesn’t free it but rather provides a stream layer to access it.

Return

Function returns aErr values.

Parameters

pMemory: - a pointer to a block of memory.
size: - The size of the block in bytes.
pStreamRef: - The resulting stream accessor for the memory block.

Return Value

aErrNone: - Successful creation.
aErrParam: - The memory block is invalid.
aErrIO: - A communication error occured.

aErr aStream_CreateUSB(const uint32_t serialNum, aStreamRef *pStreamRef)¶

Create a stream to a USB device.

Creates a BrainStem link stream to a USB based module.

Return

Function returns aErr values.

Parameters

serialNum: - The BrainStem serial number.
pStreamRef: - The resulting stream accessor for the BrainStem module.

Return Value

aErrNone: - Successful creation.
aErrNotFound: - The brainstem device was not found.
aErrIO: - A communication error occured.

aErr aStreamBuffer_Create(const size_t nIncSize, aStreamRef *pBufferStreamRef)¶

Create a stream buffer.

Creates a stream buffer.

StreamBuffers are typically used to agregate a bunch of output into a single pile of bytes. This pile can then be checked for size or accessed as a single block of bytes using the aStreamBuffer_Get call. Finally, these bytes can then be read back out of the buffer until it is empty when it will report an error of aErrEOF. While this stream is thread-safe for different threads doing reads and writes, it is not the best candidate for managing a pipe between threads. Use the aStream_CreatePipe in that scenario as it can be filled and emptied over and over which is typically the use case for cross-thread pipes.

Return

Function returns aErr values.

Parameters

nIncSize: - The Increment size to expand the buffer by when it becomes full.
pBufferStreamRef: - The buffer stream resulting from the call.

Return Value

aErrNone: - The buffer was successfully created.
aErrResource: - The resources were not available to create the buffer.

aErr aStreamBuffer_Get(aStreamRef bufferStreamRef, size_t *aSize, uint8_t **ppData)¶

Get the contents of the buffer.

StreamBuffers are typically used to agregate a bunch of output into a single pile of bytes. This pile can then be checked for size or accessed as a single block of bytes using the aStreamBuffer_Get call. Finally, these bytes can then be read back out of the buffer until it is empty when it will report an error of aErrEOF. While this stream is thread-safe for different threads doing reads and writes, it is not the best candidate for managing a pipe between threads. Use the aStream_CreatePipe in that scenario as it can be filled and emptied over and over which is typically the use case for cross-thread pipes.

Return

Function returns aErr values.

Parameters

bufferStreamRef: - The buffer stream resulting from the call.
aSize: - The size of the buffered data in bytes.
ppData: - The resulting buffer of the bytes.

Return Value

aErrNone: - The buffer was successfully created.
aErrParam: - An invalid stream ref was given.

aErr aStream_CreatePipe(aStreamRef *pBufferStreamRef)¶

Create a pipe buffered stream.

Get the contents of the buffer. Offers a pipe that is thread-safe for reading and writing between two different contexts. Returns aErrNotReady when data is not available on reads. Expands a buffer internally to hold data when written to until it is read out (FIFO).

Return

Function returns aErr values.

Parameters

pBufferStreamRef: - The buffered stream to create the pipe out of.

Return Value

aErrNone: - Successful creation.
aErrParam: - The bufferStream is invalid.

aErr aStreamBuffer_Flush(aStreamRef bufferStreamRef, aStreamRef flushStream)¶

Flush the cotents of the buffer.

Flushes the content of the buffer into the flushStream.

Return

Function returns aErr values.

Parameters

bufferStreamRef: - The buffered stream to flush.
flushStream: - the stream to flush the buffer into.

Return Value

aErrNone: - The flush succeeded.
aErrParam: - The bufferStream is invalid.
aErrIO: - IO error writing to flushStream.

aErr aStream_CreateLogStream(const aStreamRef streamToLog, const aStreamRef upStreamLog, const aStreamRef downStreamLog, aStreamRef *pLogStreamRef)¶

Create a Logging stream.

Creates a stream which contains an upstream log stream and a downstream log stream. The logging stream logs reads to the upstream log and writes to the downstream log, while passing all data to and from the pLogStreamRef.

Return

Function returns aErr values.

Return

aErrIO - A communication error occured creating the logging stream.

Parameters

streamToLog: - The reference to the stream to log.
upStreamLog: - Log stream for reads.
downStreamLog: - Log stream for writes.
pLogStreamRef: - The logged stream reference.

Return Value

aErrNone: - Successful creation.
aErrParam: - The stream to log is invalid.

aErr aStream_Read(aStreamRef streamRef, uint8_t *pBuffer, const size_t length)¶

Read a byte array record from a stream.

Return

Function returns aErr values.

Parameters

streamRef: - The reference to the stream to read from.
pBuffer: - byte array buffer to read into.
length: - the length of the read buffer.

Return Value

aErrNone: - Successful read.
aErrMode: - The streamRef is not readable.
aErrIO: - An error occured reading the data.

aErr aStream_Write(aStreamRef streamRef, const uint8_t *pBuffer, const size_t length)¶

Write a byte array to a Stream.

Return

Function returns aErr values.

Parameters

streamRef: - The reference to the stream to write to.
pBuffer: - byte array to write out to the stream.
length: - the byte array length

Return Value

aErrNone: - Successful write.
aErrMode: - The streamRef is not writable.
aErrIO: - An error occured writing the data.

aErr aStream_ReadRecord(aStreamRef streamRef, uint8_t *pBuffer, size_t *lengthRead, const size_t maxLength, const uint8_t *recordTerminator, const size_t terminatorLength)¶

Read a byte array record from a stream with a record terminator.

Return

Function returns aErr values.

Return

aErrMode - The streamRef is not readable.

Return

aErrIO - An error occured reading the data.

Parameters

streamRef: - The reference to the stream to read from.
pBuffer: - Byte array buffer to read into.
lengthRead: - The length of the read buffer.
maxLength: - The Maximum record length.
recordTerminator: - The byte array representing the record terminator.
terminatorLength: - The length of the record terminator.

Return Value

aErrNone: - Successful read.

aErr aStream_WriteRecord(aStreamRef streamRef, const uint8_t *pBuffer, const size_t bufferLength, const uint8_t *recordTerminator, const size_t terminatorLength)¶

Write a byte array with a record terminator to a Stream.

Return

Function returns aErr values.

Parameters

streamRef: - The reference to the stream to write to.
pBuffer: - byte array to write out to the stream.
bufferLength: - the byte array length
recordTerminator: - the byte array representing the record terminator
terminatorLength: - the length of the record terminator.

Return Value

aErrNone: - Successful write.
aErrMode: - The streamRef is not writable.
aErrIO: - An error occured writing the data.

aErr aStream_ReadCString(aStreamRef streamRef, char *pBuffer, const size_t maxLength)¶

Read a null terminated string from Stream.

Return

Function returns aErr values.

Parameters

streamRef: - The reference to the stream to read from.
pBuffer: - Character array buffer to read into.
maxLength: - The maximum length of the string.

Return Value

aErrNone: - Successful read.
aErrMode: - The streamRef is not readable.
aErrIO: - An error occured reading the data.

aErr aStream_WriteCString(aStreamRef streamRef, const char *pBuffer)¶

Write a null terminated string.

Return

Function returns aErr values.

Parameters

streamRef: - The reference to the stream to write to.
pBuffer: - character array to write.

Return Value

aErrNone: - Successful write.
aErrMode: - The streamRef is not writable.
aErrIO: - An error occured writing the data.

aErr aStream_ReadCStringRecord(aStreamRef streamRef, char *pBuffer, const size_t maxLength, const char *recordTerminator)¶

Read a null terminated string with a record terminator to pBuffer.

Return

Function returns aErr values.

Parameters

streamRef: - The reference to the stream to read to.
pBuffer: - character array to read to.
maxLength: - The maximum number of characters to read.
recordTerminator: - The record terminator to read to.

Return Value

aErrNone: - Successful read.
aErrMode: - The streamRef is not readable.
aErrIO: - An error occured reading the data.

aErr aStream_WriteCStringRecord(aStreamRef streamRef, const char *pBuffer, const char *recordTerminator)¶

Write a null terminated string with a record terminator to the stream.

Return

Function returns aErr values.

Parameters

streamRef: - The reference to the stream to be written to.
pBuffer: - Null terminated string to write to the stream.
recordTerminator: - The record terminator to write after the contents.

Return Value

aErrNone: - Successful write.
aErrMode: - The streamRef is not writable.
aErrIO: - An error occured writing the data.

aErr aStream_Flush(aStreamRef inStreamRef, aStreamRef outStreamRef)¶

Flush contents of inStream into outStream.

Flush the entire current content of the instream into the outstream.

Return

Function returns aErr values.

Parameters

inStreamRef: - The reference to the stream to be flushed into the outstream.
outStreamRef: - The reference to the stream instream is flushed into.

Return Value

aErrNone: - Successful Flush.
aErrMode: - The outstream is not writable or instream is not readable.
aErrIO: - An error occured flushing the data.

aErr aStream_Destroy(aStreamRef *pStreamRef)¶

Destroy a Stream.

Safely destroy a stream and deallocate the associated resources.

Return

Function returns aErr values.

Parameters

pStreamRef: - A pointer to a pointer of a valid streamRef. The StreamRef will be set to NULL on successful destruction of the stream.

Return Value

aErrNone: - The stream was successfully destroyed.
aErrParam: - If the streamRef is invalid.