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.

Param pData:: The data Buffer to fill.
Param ref:: Opaque reference to concrete stream implementation.
Retval aErrNone:: Successfully read the byte.
Retval aErrNotReady:: No bytes in stream to read.
Retval aErrEOF:: Reached the end of the stream.
Retval aErrIO:: An error encountered reading from stream.
Return:: Function returns aErr values.

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

Typedef aStreamPutProc.

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

Param pData:: The data Buffer to write.
Param ref:: opaque reference to concrete stream implementation.
Retval aErrNone:: Successfully wrote the byte.
Retval aErrIO:: An error encountered reading from stream.
Return:: Function returns aErr values.

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

Typedef aStreamDeleteProc.

This callback is defined to destroy the concrete stream implementation.

Param ref:: opaque reference to concrete stream implementation.
Retval aErrNone:: Successfully destroyed.
Retval aErrParam:: Invalid ref.
Return:: Function returns aErr values.

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

Typedef aStreamWriteProc. (Optional)

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

Param pData:: The pointer to the data to write to the stream.
Param nSize:: The size of the data buffer in bytes.
Param ref:: Opaque reference to concrete stream implementation.
Retval aErrNone:: Successfully destroyed.
Retval aErrIO:: An error encountered reading from stream.
Return:: Function returns aErr values.

enum aBaudRate¶

Enum aBaudRate.

Accepted serial stream baudrates.

Values:

enumerator aBAUD_2400¶: 2400 baud

enumerator aBAUD_4800¶: 4800 baud

enumerator aBAUD_9600¶: 9600 baud

enumerator aBAUD_19200¶: 19,200 baud

enumerator aBAUD_38400¶: 38,400 baud

enumerator aBAUD_57600¶: 57,600 baud

enumerator aBAUD_115200¶: 115,200 baud

enumerator aBAUD_230400¶: 230,400 buad

enum aSerial_Bits¶

Enum aSerial_Bits.

The accepted number of serial bits per byte.

Values:

enumerator aBITS_8¶: 8 bits

enumerator aBITS_7¶: 7 bits

enum aSerial_Stop_bits¶

Enum aSerial_Stop_bits.

The accepted number of serial stop bits.

Values:

enumerator aSTOP_BITS_1¶: 1 stop bit

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

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,

Returns:

Function returns aStreamRef on success and NULL on error.

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

Create a file input stream.

Creates a file input stream.

Parameters:

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

Return values:

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

Returns:

Function returns aErr values.

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

Create a file output stream.

Creates a file output stream.

Parameters:

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

Return values:

aErrNone – - Successful creation.
aErrIO – - A communication error occurred.

Returns:

Function returns aErr values.

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.

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 values:

aErrNone – - Successful creation.
aErrConnection – - The connection was unsuccessful.
aErrIO – - A communication error occurred.

Returns:

Function returns aErr values.

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.

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 values:

aErrNone – - Successful creation.
aErrConnection – - The connection was unsuccessful.
aErrIO – - A communication error occurred.

Returns:

Function returns aErr values.

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.

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 values:

aErrNone – - Successful creation.
aErrParam – - The memory block is invalid.
aErrIO – - A communication error occurred.

Returns:

Function returns aErr values.

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.

Parameters:

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

Return values:

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

Returns:

Function returns aErr values.

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

Create a stream buffer.

Creates a stream buffer.

StreamBuffers are typically used to aggregate 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.

Parameters:

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

Return values:

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

Returns:

Function returns aErr values.

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

Get the contents of the buffer.

StreamBuffers are typically used to aggregate 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.

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 values:

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

Returns:

Function returns aErr values.

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

Parameters:

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

Return values:

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

Returns:

Function returns aErr values.

aErr aStreamBuffer_Flush(aStreamRef bufferStreamRef, aStreamRef flushStream)¶

Flush the cotents of the buffer.

Flushes the content of the buffer into the flushStream.

Parameters:

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

Return values:

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

Returns:

Function returns aErr values.

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.

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 values:

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

Returns:

Function returns aErr values.

Returns:

aErrIO - A communication error occurred creating the logging stream.

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

Read a byte array record from a stream.

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 values:

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

Returns:

Function returns aErr values.

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

Write a byte array to a Stream.

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 values:

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

Returns:

Function returns aErr values.

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.

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 values:

aErrNone – - Successful read.

Returns:

Function returns aErr values.

Returns:

aErrMode - The streamRef is not readable.

Returns:

aErrIO - An error occurred reading the data.

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.

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 values:

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

Returns:

Function returns aErr values.

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

Read a null terminated string from Stream.

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 values:

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

Returns:

Function returns aErr values.

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

Write a null terminated string.

Parameters:

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

Return values:

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

Returns:

Function returns aErr values.

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.

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 values:

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

Returns:

Function returns aErr values.

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

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

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 values:

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

Returns:

Function returns aErr values.

aErr aStream_Flush(aStreamRef inStreamRef, aStreamRef outStreamRef)¶

Flush contents of inStream into outStream.

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

Parameters:

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

Return values:

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

Returns:

Function returns aErr values.

aErr aStream_Destroy(aStreamRef *pStreamRef)¶

Destroy a Stream.

Safely destroy a stream and deallocate the associated resources.

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 values:

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

Returns:

Function returns aErr values.