Data Structures
struct	golioth_response_t
	Response status and CoAP class/code. More...

struct	golioth_psk_credentials_t

struct	golioth_pki_credentials_t

struct	golioth_tls_credentials_t
	TLS Authentication Credentials. More...

struct	golioth_client_config_t
	Golioth client configuration, passed into golioth_client_create. More...

Typedefs
typedef void *	golioth_client_t
	Opaque handle to the Golioth client. More...

typedef void(*	golioth_client_event_cb_fn) (golioth_client_t client, golioth_client_event_t event, void *arg)

typedef void(*	golioth_get_cb_fn) (golioth_client_t client, const golioth_response_t response, const char path, const uint8_t payload, size_t payload_size, void arg)

typedef void(*	golioth_get_block_cb_fn) (golioth_client_t client, const golioth_response_t response, const char path, const uint8_t payload, size_t payload_size, bool is_last, void arg)

typedef void(*	golioth_set_cb_fn) (golioth_client_t client, const golioth_response_t response, const char path, void *arg)

Enumerations
enum	golioth_client_event_t { GOLIOTH_CLIENT_EVENT_CONNECTED , GOLIOTH_CLIENT_EVENT_DISCONNECTED }
	Golioth client events. More...

enum	golioth_tls_auth_type_t { GOLIOTH_TLS_AUTH_TYPE_PSK , GOLIOTH_TLS_AUTH_TYPE_PKI }
	TLS authentication type. More...

Functions
golioth_client_t	golioth_client_create (const golioth_client_config_t *config)

bool	golioth_client_wait_for_connect (golioth_client_t client, int timeout_ms)

golioth_status_t	golioth_client_start (golioth_client_t client)

golioth_status_t	golioth_client_stop (golioth_client_t client)

void	golioth_client_destroy (golioth_client_t client)

bool	golioth_client_is_running (golioth_client_t client)

bool	golioth_client_is_connected (golioth_client_t client)

void	golioth_client_register_event_callback (golioth_client_t client, golioth_client_event_cb_fn callback, void *arg)

uint32_t	golioth_client_num_items_in_request_queue (golioth_client_t client)

void	golioth_client_set_packet_loss_percent (uint8_t percent)

bool	golioth_client_has_allocation_leaks (void)

golioth_sys_thread_t	golioth_client_get_thread (golioth_client_t 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/protocols/coap
https://docs.golioth.io/reference/protocols/device-auth

Typedef Documentation

◆ golioth_client_event_cb_fn

typedef void(* golioth_client_event_cb_fn) (golioth_client_t client, golioth_client_event_t 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 112 of file golioth_client.h.

◆ golioth_client_t

typedef void* golioth_client_t

Opaque handle to the Golioth client.

Definition at line 28 of file golioth_client.h.

◆ golioth_get_block_cb_fn

typedef void(* golioth_get_block_cb_fn) (golioth_client_t client, const golioth_response_t *response, const char *path, const uint8_t *payload, size_t payload_size, bool is_last, void *arg)

Definition at line 136 of file golioth_client.h.

◆ golioth_get_cb_fn

typedef void(* golioth_get_cb_fn) (golioth_client_t client, const golioth_response_t *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 129 of file golioth_client.h.

◆ golioth_set_cb_fn

typedef void(* golioth_set_cb_fn) (golioth_client_t client, const golioth_response_t *response, const char *path, void *arg)

Callback function type for all asynchronous set and delete 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). 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 156 of file golioth_client.h.

Enumeration Type Documentation

◆ golioth_client_event_t

enum golioth_client_event_t

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 31 of file golioth_client.h.

◆ golioth_tls_auth_type_t

enum golioth_tls_auth_type_t

TLS 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)

Definition at line 54 of file golioth_client.h.

Function Documentation

◆ golioth_client_create()

golioth_client_t golioth_client_create ( const golioth_client_config_t * 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 ( golioth_client_t 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 ( golioth_client_t client )

Return the thread handle of the client thread.

Parameters

client The client handle

Returns: The thread handle of the client thread

◆ golioth_client_has_allocation_leaks()

bool golioth_client_has_allocation_leaks ( void )

Return whether there exists an allocated resource that has not been freed by the client.

Intended only for Golioth SDK developers, for test and debug purposes.

Returns: true There is at least one allocation leak (turn on debug logs to see which ones); false There are no allocation leaks

◆ golioth_client_is_connected()

bool golioth_client_is_connected ( golioth_client_t 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

Returns: 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 ( golioth_client_t client )

Returns whether the client is currently running

Parameters

client The client handle

Returns: 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 ( golioth_client_t 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	(	golioth_client_t	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()

golioth_status_t golioth_client_start ( golioth_client_t 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

Returns: GOLIOTH_OK Client started; GOLIOTH_ERR_NULL Client handle invalid

◆ golioth_client_stop()

golioth_status_t golioth_client_stop ( golioth_client_t 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

Returns: GOLIOTH_OK Client stopped; GOLIOTH_ERR_NULL Client handle invalid

◆ golioth_client_wait_for_connect()

bool golioth_client_wait_for_connect	(	golioth_client_t	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.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ golioth_client_event_cb_fn

◆ golioth_client_t

◆ golioth_get_block_cb_fn

◆ golioth_get_cb_fn

◆ golioth_set_cb_fn

Enumeration Type Documentation

◆ golioth_client_event_t

◆ golioth_tls_auth_type_t

Function Documentation

◆ golioth_client_create()

◆ golioth_client_destroy()

◆ golioth_client_get_thread()

◆ golioth_client_has_allocation_leaks()

◆ golioth_client_is_connected()

◆ golioth_client_is_running()

◆ golioth_client_num_items_in_request_queue()

◆ golioth_client_register_event_callback()

◆ golioth_client_set_packet_loss_percent()

◆ golioth_client_start()

◆ golioth_client_stop()

◆ golioth_client_wait_for_connect()