Data Streams
Core

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] handle Handle 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] handle Handle of stream to poll
[out] rx_available_ptr Pointer to hold number of bytes available to read
[out] tx_available_ptr Pointer 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] handle Stream handle returned by API call
[out] data Buffer to hold read data
[in] max_size Maximum amount of data to read
[out] bytes_read_ptr Pointer 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] handle Stream handle returned by API call
[out] buf Buffer 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] handle Stream handle returned by API call
[in] data Data to write to stream
[in] size Size of data in bytes to write
[in] auto_flush If true, only flush data when the internal buffer is full, false flush the data immediately
Returns
gos_result_t result of api call