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)
struct blockwise_transfer *	golioth_stream_blockwise_start (struct golioth_client *client, const char *path, enum golioth_content_type content_type)
void	golioth_stream_blockwise_finish (struct blockwise_transfer *ctx)
enum golioth_status	golioth_stream_blockwise_set_block_async (struct blockwise_transfer *ctx, uint32_t block_idx, const uint8_t *block_buffer, size_t data_len, bool is_last, golioth_set_block_cb_fn callback, void *callback_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_blockwise_finish()

void golioth_stream_blockwise_finish

(

struct blockwise_transfer *

ctx

)

Destroy a multi-block upload context

Free the memory allocated for a given multi-block upload context.

Parameters

ctx	Block upload context to be destroyed

golioth_stream_blockwise_set_block_async()

enum golioth_status golioth_stream_blockwise_set_block_async	(	struct blockwise_transfer *	ctx,
		uint32_t	block_idx,
		const uint8_t *	block_buffer,
		size_t	data_len,
		bool	is_last,
		golioth_set_block_cb_fn	callback,
		void *	callback_arg )

Set an object in stream at a particular path by sending each block asynchronously

Call this function for each block. For each call you must increment the block_idx, adjust the block_buffer pointer and update the data_len. On the final block, set is_last to true. Block size is determined by the value of CONFIG_GOLIOTH_BLOCKWISE_DOWNLOAD_MAX_BLOCK_SIZE.

Create a new ctx by calling golioth_stream_blockwise_start. The same ctx must be used for all blocks in a related upload. Generate a new ctx for each new upload operation. Free the context memory by calling golioth_stream_blockwise_finish.

An optional callback and callback argument may be supplied. The callback will be called after the block is uploaded to provide access to status and CoAP response codes.

Parameters

ctx	Block upload context used for all blocks in a related upload operation
block_idx	The index of the block being sent
block_buffer	The buffer where the data for this block is located
data_len	The actual length of data (in bytes) for this block. This should be equal to CONFIG_GOLIOTH_BLOCKWISE_DOWNLOAD_MAX_BLOCK_SIZE for all blocks except for the final block, which may be shorter
is_last	Set this to true if this is the last block in the upload
callback	A callback that will be called after each block is sent (can be NULL)
callback_arg	An optional user provided argument that will be passed to callback (can be NULL)

golioth_stream_blockwise_start()

struct blockwise_transfer * golioth_stream_blockwise_start	(	struct golioth_client *	client,
		const char *	path,
		enum golioth_content_type	content_type )

Create a multipart blockwise upload context

Creates the context and returns a pointer to it. This context is used to associate all blocks of a multipart upload together. A new context is needed at the start of each multipart blockwise upload operation.

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)

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