Golioth Zephyr SDK
Golioth Remote Procedure Call

Data Structures

struct  golioth_rpc_method
 Data for each registered RPC method. More...
 
struct  golioth_rpc
 Global/shared RPC state data, placed in struct golioth_client. More...
 

Typedefs

typedef enum golioth_rpc_status(* golioth_rpc_cb_fn) (zcbor_state_t *request_params_array, zcbor_state_t *response_detail_map, void *callback_arg)
 Callback function type for remote procedure call. More...
 

Enumerations

enum  golioth_rpc_status {
  GOLIOTH_RPC_OK = 0 , GOLIOTH_RPC_CANCELED = 1 , GOLIOTH_RPC_UNKNOWN = 2 , GOLIOTH_RPC_INVALID_ARGUMENT = 3 ,
  GOLIOTH_RPC_DEADLINE_EXCEEDED = 4 , GOLIOTH_RPC_NOT_FOUND = 5 , GOLIOTH_RPC_ALREADYEXISTS = 6 , GOLIOTH_RPC_PERMISSION_DENIED = 7 ,
  GOLIOTH_RPC_RESOURCE_EXHAUSTED = 8 , GOLIOTH_RPC_FAILED_PRECONDITION = 9 , GOLIOTH_RPC_ABORTED = 10 , GOLIOTH_RPC_OUT_OF_RANGE = 11 ,
  GOLIOTH_RPC_UNIMPLEMENTED = 12 , GOLIOTH_RPC_INTERNAL = 13 , GOLIOTH_RPC_UNAVAILABLE = 14 , GOLIOTH_RPC_DATA_LOSS = 15 ,
  GOLIOTH_RPC_UNAUTHENTICATED = 16
}
 Enumeration of RPC status codes, sent in the RPC response. More...
 

Functions

int golioth_rpc_init (struct golioth_client *client)
 Initialize RPC. More...
 
int golioth_rpc_register (struct golioth_client *client, const char *method_name, golioth_rpc_cb_fn callback, void *callback_arg)
 Register an RPC method. More...
 
int golioth_rpc_observe (struct golioth_client *client)
 Observe for RPC method invocations. More...
 

Detailed Description

Functions for interacting with the Golioth Remote Procedure Call service

Typedef Documentation

◆ golioth_rpc_cb_fn

typedef enum golioth_rpc_status(* golioth_rpc_cb_fn) (zcbor_state_t *request_params_array, zcbor_state_t *response_detail_map, void *callback_arg)

Callback function type for remote procedure call.

If the RPC has input params, they can be extracted from request_params_array using zcbor functions like zcbor_float_decode, zcbor_tstr_decode, etc.

If the RPC needs to return data, it can be added to response_detail_map using zcbor functions like zcbor_tstr_put_lit, zcbor_float64_put, etc.

Here is an example of a callback function that implements the "on_multiply" method, which multiplies two input numbers and returns the result.

static enum golioth_rpc_status on_multiply(zcbor_state_t *request_params_array,
zcbor_state_t *response_detail_map,
void *callback_arg)
{
double a, b;
double value;
bool ok;
ok = zcbor_float_decode(request_params_array, &a) &&
zcbor_float_decode(request_params_array, &b);
if (!ok) {
LOG_ERR("Failed to decode array items");
}
value = a * b;
ok = zcbor_tstr_put_lit(response_detail_map, "value") &&
zcbor_float64_put(response_detail_map, value);
if (!ok) {
LOG_ERR("Failed to encode value");
}
}
golioth_rpc_status
Enumeration of RPC status codes, sent in the RPC response.
Definition: rpc.h:33
@ GOLIOTH_RPC_INVALID_ARGUMENT
Definition: rpc.h:37
@ GOLIOTH_RPC_RESOURCE_EXHAUSTED
Definition: rpc.h:42
@ GOLIOTH_RPC_OK
Definition: rpc.h:34
Parameters
request_params_arrayzcbor decode state, inside of the RPC request params array
response_detail_mapzcbor encode state, inside of the RPC response detail map
callback_argcallback_arg, unchanged from callback_arg of golioth_rpc_register
Returns
GOLIOTH_RPC_OK - if method was called successfully
GOLIOTH_RPC_INVALID_ARGUMENT - if params were invalid
otherwise - method failure

Definition at line 1 of file rpc.h.

Enumeration Type Documentation

◆ golioth_rpc_status

Enumeration of RPC status codes, sent in the RPC response.

Enumerator
GOLIOTH_RPC_OK 
GOLIOTH_RPC_CANCELED 
GOLIOTH_RPC_UNKNOWN 
GOLIOTH_RPC_INVALID_ARGUMENT 
GOLIOTH_RPC_DEADLINE_EXCEEDED 
GOLIOTH_RPC_NOT_FOUND 
GOLIOTH_RPC_ALREADYEXISTS 
GOLIOTH_RPC_PERMISSION_DENIED 
GOLIOTH_RPC_RESOURCE_EXHAUSTED 
GOLIOTH_RPC_FAILED_PRECONDITION 
GOLIOTH_RPC_ABORTED 
GOLIOTH_RPC_OUT_OF_RANGE 
GOLIOTH_RPC_UNIMPLEMENTED 
GOLIOTH_RPC_INTERNAL 
GOLIOTH_RPC_UNAVAILABLE 
GOLIOTH_RPC_DATA_LOSS 
GOLIOTH_RPC_UNAUTHENTICATED 

Definition at line 33 of file rpc.h.

Function Documentation

◆ golioth_rpc_init()

int golioth_rpc_init ( struct golioth_client client)

Initialize RPC.

Parameters
clientClient instance
Returns
0 - RPC initialized successfully
Otherwise - RPC error initializing

◆ golioth_rpc_observe()

int golioth_rpc_observe ( struct golioth_client client)

Observe for RPC method invocations.

User applications should call this function in the on_connect callback, if they wish to observe RPCs.

Establishes a single observation for endpoint ".rpc". The handler for this endpoint will look up the method in a table of registered RPCs (from golioth_rpc_register) and invoke the callback if the method is found.

Parameters
clientClient instance
Returns
0 - RPC observation established
<0 - Error observing RPC

◆ golioth_rpc_register()

int golioth_rpc_register ( struct golioth_client client,
const char *  method_name,
golioth_rpc_cb_fn  callback,
void *  callback_arg 
)

Register an RPC method.

Parameters
clientClient instance
method_nameThe name of the method to register
callbackThe callback to be invoked, when an RPC request with matching method name is received by the client.
callback_argUser data forwarded to callback when invoked. Optional, can be NULL.
Returns
0 - RPC method successfully registered
<0 - Error registering RPC method