Golioth Firmware SDK
Loading...
Searching...
No Matches
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/protocols/coap
https://docs.golioth.io/reference/protocols/device-auth

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

Definition at line 131 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)

Definition at line 153 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
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 147 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
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 173 of file client.h.

Enumeration Type Documentation

◆ 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 64 of file client.h.

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

◆ golioth_content_type

Golioth Content Type.

Enumerator
GOLIOTH_CONTENT_TYPE_JSON 
GOLIOTH_CONTENT_TYPE_CBOR 
GOLIOTH_CONTENT_TYPE_OCTET_STREAM 

Definition at line 40 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
configClient 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
clientThe 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
clientThe 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
clientThe client handle
Return values
trueThe client is connected to Golioth
falseThe 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
clientThe client handle
Return values
trueThe client is running
falseThe 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
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 ( 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
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()

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
clientThe client handle
Return values
GOLIOTH_OKClient started
GOLIOTH_ERR_NULLClient 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
clientThe client handle
Return values
GOLIOTH_OKClient stopped
GOLIOTH_ERR_NULLClient 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
clientThe client handle
timeout_msHow long to wait, in milliseconds, or -1 to wait forever
Returns
True, if connected, false otherwise.