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.

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.

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.

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.

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.

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.

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.

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.

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.

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.