golioth_stream

Typedefs
typedef enum golioth_status(*	stream_read_block_cb) (uint32_t block_idx, uint8_t *block_buffer, size_t *block_size, bool *is_last, void *arg)

Functions
enum golioth_status	golioth_stream_set_async (struct golioth_client *client, const char *path, enum golioth_content_type content_type, const uint8_t *buf, size_t buf_len, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_stream_set_sync (struct golioth_client *client, const char *path, enum golioth_content_type content_type, const uint8_t *buf, size_t buf_len, int32_t timeout_s)
enum golioth_status	golioth_stream_set_blockwise_sync (struct golioth_client *client, const char *path, enum golioth_content_type content_type, stream_read_block_cb cb, void *arg)

Detailed Description

Functions for interacting with Golioth Stream service.

https://docs.golioth.io/reference/protocols/coap/stream

Typedef Documentation

stream_read_block_cb

typedef enum golioth_status(* stream_read_block_cb) (uint32_t block_idx, uint8_t *block_buffer, size_t *block_size, bool *is_last, void *arg)

Read block callback

This callback will be called by the Golioth client each time it needs to fill a block.

When the callback runs, the buffer should be filled with block_size number of bytes. When the last block contains fewer bytes, set block_size to the actual number of bytes written. Set is_last to indicate all data has been written to buffer.

Parameters

block_idx	The index of the block to fill
block_buffer	The buffer that this callback should fill
block_size	(in/out) Contains the maximum size of block_buffer, and should be set to the size of data actually placed in block_buffer. Value must be > 0 when this function returns GOLIOTH_OK.
is_last	(out) Set this to true if this is the last block to transfer
arg	A user provided argument

Return values

GOLIOTH_OK	Callback ran successfully
GOLIOTH_ERR_*	Indicate error type encountered by callback

Definition at line 66 of file stream.h.

Function Documentation

golioth_stream_set_async()

enum golioth_status golioth_stream_set_async	(	struct golioth_client *	client,
		const char *	path,
		enum golioth_content_type	content_type,
		const uint8_t *	buf,
		size_t	buf_len,
		golioth_set_cb_fn	callback,
		void *	callback_arg )

Set an object in stream at a particular path asynchronously

This function will enqueue a request and return immediately without waiting for a response from the server. Optionally, the user may supply a callback that will be called when the response is received (indicating the request was acknowledged by the server) or a timeout occurs (response never received).

Parameters

client	The client handle from golioth_client_create
path	The path in stream to set (e.g. "my_obj")
content_type	The serialization format of buf
buf	A buffer containing the object to send
buf_len	Length of buf
callback	Callback to call on response received or timeout. Can be NULL.
callback_arg	Callback argument, passed directly when callback invoked. Can be NULL.

Return values

GOLIOTH_OK	request enqueued
GOLIOTH_ERR_NULL	invalid client handle
GOLIOTH_ERR_INVALID_STATE	client is not running, currently stopped
GOLIOTH_ERR_MEM_ALLOC	memory allocation error
GOLIOTH_ERR_QUEUE_FULL	request queue is full, this request is dropped

golioth_stream_set_blockwise_sync()

enum golioth_status golioth_stream_set_blockwise_sync	(	struct golioth_client *	client,
		const char *	path,
		enum golioth_content_type	content_type,
		stream_read_block_cb	cb,
		void *	arg )

Set an object in stream at a particular path synchronously

This function will block until the whole transfer is complete, or errors out.

Parameters

client	The client handle from golioth_client_create
path	The path in stream to set (e.g. "my_obj")
content_type	The content type of the object (e.g. JSON or CBOR)
cb	A callback that will be used to fill each block in the transfer
arg	An optional user provided argument that will be passed to cb

golioth_stream_set_sync()

enum golioth_status golioth_stream_set_sync	(	struct golioth_client *	client,
		const char *	path,
		enum golioth_content_type	content_type,
		const uint8_t *	buf,
		size_t	buf_len,
		int32_t	timeout_s )

Set an object in stream at a particular path synchronously

This function will block until one of three things happen (whichever comes first):

1. A response is received from the server
2. The user-provided timeout_s period expires without receiving a response
3. The default GOLIOTH_COAP_RESPONSE_TIMEOUT_S period expires without receiving a response

Parameters

client	The client handle from golioth_client_create
path	The path in stream to set (e.g. "my_obj")
content_type	The serialization format of buf
buf	A buffer containing the object to send
buf_len	Length of buf
timeout_s	The timeout, in seconds, for receiving a server response