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.
-
typedef aErr (*
-
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 lengthrecordTerminator
: - the byte array representing the record terminatorterminatorLength
: - 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.