Golioth Firmware SDK
golioth_client

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/coap/auth
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
clientThe client handle
eventThe event that occurred
argUser argument, copied from golioth_client_register_event_callback. Can be NULL.

Definition at line 114 of file golioth_client.h.

◆ golioth_client_t

typedef void* golioth_client_t

Opaque handle to the Golioth client.

Definition at line 30 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 138 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
clientThe client handle from the original request.
responseResponse status and class/code
pathThe path from the original request
payloadThe application layer payload in the response packet. Can be NULL.
payload_sizeThe size of payload, in bytes
argUser argument, copied from the original request. Can be NULL.

Definition at line 131 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
clientThe client handle from the original request.
responseResponse status and class/code
pathThe path from the original request
argUser argument, copied from the original request. Can be NULL.

Definition at line 158 of file golioth_client.h.

Enumeration Type Documentation

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

◆ 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 56 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
configClient 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
clientThe 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
clientThe 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
clientThe 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
clientThe 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
clientThe 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
clientThe client handle
callbackCallback function to register
argOptional 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
percentPercent 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
clientThe 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
clientThe 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
clientThe client handle
timeout_msHow long to wait, in milliseconds, or -1 to wait forever
Returns
True, if connected, false otherwise.