golioth_client

Data Structures
struct	golioth_response
	Response status and CoAP class/code. More...
struct	golioth_psk_credential
struct	golioth_pki_credential
struct	golioth_credential
	TLS Authentication Credential. More...
struct	golioth_client_config
	Golioth client configuration, passed into golioth_client_create. More...

Typedefs
typedef void(*	golioth_client_event_cb_fn) (struct golioth_client *client, enum golioth_client_event event, void *arg)
typedef void(*	golioth_get_cb_fn) (struct golioth_client *client, const struct golioth_response *response, const char *path, const uint8_t *payload, size_t payload_size, void *arg)
typedef void(*	golioth_get_block_cb_fn) (struct golioth_client *client, const struct golioth_response *response, const char *path, const uint8_t *payload, size_t payload_size, bool is_last, void *arg)
typedef void(*	golioth_set_cb_fn) (struct golioth_client *client, const struct golioth_response *response, const char *path, void *arg)

Enumerations
enum	golioth_client_event { GOLIOTH_CLIENT_EVENT_CONNECTED , GOLIOTH_CLIENT_EVENT_DISCONNECTED }
	Golioth client events. More...
enum	golioth_content_type { GOLIOTH_CONTENT_TYPE_JSON , GOLIOTH_CONTENT_TYPE_CBOR , GOLIOTH_CONTENT_TYPE_OCTET_STREAM }
	Golioth Content Type. More...
enum	golioth_auth_type { GOLIOTH_TLS_AUTH_TYPE_PSK , GOLIOTH_TLS_AUTH_TYPE_PKI , GOLIOTH_TLS_AUTH_TYPE_TAG }
	Authentication type. More...

Functions
struct golioth_client *	golioth_client_create (const struct golioth_client_config *config)
bool	golioth_client_wait_for_connect (struct golioth_client *client, int timeout_ms)
enum golioth_status	golioth_client_start (struct golioth_client *client)
enum golioth_status	golioth_client_stop (struct golioth_client *client)
void	golioth_client_destroy (struct golioth_client *client)
bool	golioth_client_is_running (struct golioth_client *client)
bool	golioth_client_is_connected (struct golioth_client *client)
void	golioth_client_register_event_callback (struct golioth_client *client, golioth_client_event_cb_fn callback, void *arg)
uint32_t	golioth_client_num_items_in_request_queue (struct golioth_client *client)
void	golioth_client_set_packet_loss_percent (uint8_t percent)
golioth_sys_thread_t	golioth_client_get_thread (struct golioth_client *client)

Detailed Description

Functions for creating a Golioth client and managing client lifetime.

Used to connect to Golioth cloud using the CoAP protocol over DTLS.

For authentication, you can use either pre-shared key (PSK) or X.509 certificates (aka Public Key Infrastructure, PKI).

https://docs.golioth.io/reference/device-api

Typedef Documentation

golioth_client_event_cb_fn

typedef void(* golioth_client_event_cb_fn) (struct golioth_client *client, enum golioth_client_event event, void *arg)

Callback function type for client events

Parameters

client	The client handle
event	The event that occurred
arg	User argument, copied from golioth_client_register_event_callback. Can be NULL.

Definition at line 139 of file client.h.

golioth_get_block_cb_fn

typedef void(* golioth_get_block_cb_fn) (struct golioth_client *client, const struct golioth_response *response, const char *path, const uint8_t *payload, size_t payload_size, bool is_last, void *arg)

Callback for blockwise get requests

Will be called repeatedly, once for each block received from the server or on timeout (i.e. response never received). The callback function should check response->status to determine which case it is (response received or timeout).

Parameters

client	The client handle from the original request.
response	Response status and class/code
path	The path from the original request
payload	The application layer payload in the response packet. Can be NULL.
payload_size	The size of payload, in bytes
is_last	True if this is the final block of the get request
arg	User argument, copied from the original request. Can be NULL.

Definition at line 175 of file client.h.

golioth_get_cb_fn

typedef void(* golioth_get_cb_fn) (struct golioth_client *client, const struct golioth_response *response, const char *path, const uint8_t *payload, size_t payload_size, void *arg)

Callback function type for all asynchronous get and observe requests

Will be called when a response is received or on timeout (i.e. response never received). The callback function should check response->status to determine which case it is (response received or timeout).

Parameters

client	The client handle from the original request.
response	Response status and class/code
path	The path from the original request
payload	The application layer payload in the response packet. Can be NULL.
payload_size	The size of payload, in bytes
arg	User argument, copied from the original request. Can be NULL.

Definition at line 155 of file client.h.

golioth_set_cb_fn

typedef void(* golioth_set_cb_fn) (struct golioth_client *client, const struct golioth_response *response, const char *path, void *arg)

Callback function type for all asynchronous set and delete requests as well as blockwise uploads

Will be called when a response is received or on timeout (i.e. response never received). The callback function should check response->status to determine which case it is (response received or timeout). If response->status is GOLIOTH_OK, then the set or delete request was successful.

Parameters

client	The client handle from the original request.
response	Response status and class/code
path	The path from the original request
arg	User argument, copied from the original request. Can be NULL.

Definition at line 195 of file client.h.

Enumeration Type Documentation

golioth_auth_type

enum golioth_auth_type

Authentication type.

Enumerator
GOLIOTH_TLS_AUTH_TYPE_PSK	Authenticate with pre-shared key (psk-id and psk)
GOLIOTH_TLS_AUTH_TYPE_PKI	Authenticate with PKI certificates (CA cert, public client cert, private client key)
GOLIOTH_TLS_AUTH_TYPE_TAG	Authenticate with TLS credential tag (Zephyr specific)

Definition at line 68 of file client.h.

golioth_client_event

enum golioth_client_event

Golioth client events.

Enumerator
GOLIOTH_CLIENT_EVENT_CONNECTED	Client was previously not connected, and is now connected.
GOLIOTH_CLIENT_EVENT_DISCONNECTED	Client was previously connected, and is now disconnected.

Definition at line 35 of file client.h.

golioth_content_type

enum golioth_content_type

Golioth Content Type.

Enumerator
GOLIOTH_CONTENT_TYPE_JSON
GOLIOTH_CONTENT_TYPE_CBOR
GOLIOTH_CONTENT_TYPE_OCTET_STREAM

Definition at line 44 of file client.h.

Function Documentation

golioth_client_create()

struct golioth_client * golioth_client_create

(

const struct golioth_client_config *

config

)

Create a Golioth client

Dynamically creates a client and returns an opaque handle to the client. The handle is a required parameter for most other Golioth SDK functions.

An RTOS thread and request queue is created and the client is automatically started (no need to call golioth_client_start).

Parameters

config

Client configuration

Returns

Non-NULL The client handle (success)

NULL There was an error creating the client

golioth_client_destroy()

void golioth_client_destroy

(

struct golioth_client *

client

)

Destroy a Golioth client

Frees dynamically created resources from golioth_client_create.

Parameters

client

The handle of the client to destroy

golioth_client_get_thread()

golioth_sys_thread_t golioth_client_get_thread

(

struct golioth_client *

client

)

Return the thread handle of the client thread.

Parameters

client

The client handle

Returns

The thread handle of the client thread

golioth_client_is_connected()

bool golioth_client_is_connected

(

struct golioth_client *

client

)

Returns whether the client is currently connected to Golioth servers.

If client requests receive responses, this is the indication of being connected. If requests time out (no response from server), then the client is considered disconnected.

Parameters

client

The client handle

Return values

true	The client is connected to Golioth
false	The client is not connected, or the client handle is not valid

golioth_client_is_running()

bool golioth_client_is_running

(

struct golioth_client *

client

)

Returns whether the client is currently running

Parameters

client

The client handle

Return values

true	The client is running
false	The client is not running, or the client handle is not valid

golioth_client_num_items_in_request_queue()

uint32_t golioth_client_num_items_in_request_queue

(

struct golioth_client *

client

)

The number of items currently in the client thread request queue.

Will be a number between 0 and GOLIOTH_COAP_REQUEST_QUEUE_MAX_ITEMS.

Parameters

client

The client handle

Returns

The number of items currently in the client thread request queue.

golioth_client_register_event_callback()

void golioth_client_register_event_callback	(	struct golioth_client *	client,
		golioth_client_event_cb_fn	callback,
		void *	arg )

Register a callback that will be called on client events (e.g. connected, disconnected)

Parameters

client	The client handle
callback	Callback function to register
arg	Optional argument, forwarded directly to the callback when invoked. Can be NULL.

golioth_client_set_packet_loss_percent()

void golioth_client_set_packet_loss_percent

(

uint8_t

percent

)

Simulate packet loss at a particular percentage (0 to 100).

Intended for testing and troubleshooting in packet loss scenarios. Does nothing if percent is outside of the range [0, 100].

Parameters

percent

Percent packet loss (0 is no packets lost, 100 is all packets lost)

golioth_client_start()

enum golioth_status golioth_client_start

(

struct golioth_client *

client

)

Start the Golioth client

Does nothing if the client is already started. The client is started after calling golioth_client_create.

Parameters

client

The client handle

Return values

GOLIOTH_OK	Client started
GOLIOTH_ERR_NULL	Client handle invalid

golioth_client_stop()

enum golioth_status golioth_client_stop

(

struct golioth_client *

client

)

Stop the Golioth client

Client will finish the current request (if there is one), then enter a dormant state where no packets will be sent or received with Golioth, and the client thread will be in a blocked state.

This function will block until the client thread is actually stopped.

Does nothing if the client is already stopped.

Parameters

client

The client handle

Return values

GOLIOTH_OK	Client stopped
GOLIOTH_ERR_NULL	Client handle invalid

golioth_client_wait_for_connect()

bool golioth_client_wait_for_connect	(	struct golioth_client *	client,
		int	timeout_ms )

Wait (block) until connected to Golioth, or timeout occurs.

If timeout_ms set to -1, it will wait forever until connected.

Parameters

client	The client handle
timeout_ms	How long to wait, in milliseconds, or -1 to wait forever

Returns

True, if connected, false otherwise.