Data Streams

Functions for reading, writing, etc data streams. More...

Functions

gos_result_t gos_write (gos_handle_t handle, const void *data, uint32_t size, bool auto_flush)
 Write data to stream. More...
 
gos_result_t gos_read (gos_handle_t handle, void *data, uint32_t max_size, uint32_t *bytes_read_ptr)
 Read data from stream. More...
 
gos_result_t gos_read_with_buffer (gos_handle_t handle, gos_buffer_t *buf)
 Read data from stream info gos_buffer_t. More...
 
gos_result_t gos_close (gos_handle_t handle)
 Close stream. More...
 
gos_result_t gos_poll (gos_handle_t handle, uint32_t *rx_available_ptr, uint32_t *tx_available_ptr)
 Poll stream for RX and TX buffer available. More...
 

Detailed Description

Functions for reading, writing, etc data streams.

Function Documentation

◆ gos_close()

gos_result_t gos_close ( gos_handle_t  handle)

Close stream.

See Gecko OS Command API documentation: stream_close.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleHandle of stream to close (use -1 to close all streams)
Returns
gos_result_t result of api call

◆ gos_poll()

gos_result_t gos_poll ( gos_handle_t  handle,
uint32_t *  rx_available_ptr,
uint32_t *  tx_available_ptr 
)

Poll stream for RX and TX buffer available.

This polls the given stream and returns if it has data to be read and available TX buffer space.

Note
Set the rx_available_ptr and/or tx_available_ptr arg NULL to ignore the parameter.
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleHandle of stream to poll
[out]rx_available_ptrPointer to hold number of bytes available to read
[out]tx_available_ptrPointer to hold available TX buffer space
Returns
gos_result_t result of api call

◆ gos_read()

gos_result_t gos_read ( gos_handle_t  handle,
void *  data,
uint32_t  max_size,
uint32_t *  bytes_read_ptr 
)

Read data from stream.

See Gecko OS Command API documentation: stream_read.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleStream handle returned by API call
[out]dataBuffer to hold read data
[in]max_sizeMaximum amount of data to read
[out]bytes_read_ptrPointer to hold actual amount of data read (set NULL if not used)
Returns
gos_result_t result of api call

◆ gos_read_with_buffer()

gos_result_t gos_read_with_buffer ( gos_handle_t  handle,
gos_buffer_t buf 
)

Read data from stream info gos_buffer_t.

This has similar functionality as gos_read() except a gos_buffer_t is passed as an argument allowing for zero memory copies.

Only the 'size' field of the given gos_buffer_t argument should be populated with the maximum amount of data to read. The 'data' field should be NULL. When the API call returns:

  • the 'size' field is updated with the amount of data actually read
  • the 'data' field will be populated with the data pointer (if data was available)

Example usage:

gos_buffer_t buffer =
{
.data = NULL, // data pointer is populated AFTER the API call
.size = 128 // return up to a maximum of 128 bytes
}
gos_read_with_buffer(0, &buffer); // attempt to read stream
GOS_LOG("Bytes read: %u", buffer.size);
GOS_LOG("Data read: %s", buffer.data);
Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleStream handle returned by API call
[out]bufBuffer to hold read data
Returns
gos_result_t result of api call

◆ gos_write()

gos_result_t gos_write ( gos_handle_t  handle,
const void *  data,
uint32_t  size,
bool  auto_flush 
)

Write data to stream.

See Gecko OS Command API documentation: stream_write.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleStream handle returned by API call
[in]dataData to write to stream
[in]sizeSize of data in bytes to write
[in]auto_flushIf true, only flush data when the internal buffer is full, false flush the data immediately
Returns
gos_result_t result of api call