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) (QCBORDecodeContext *request_params_array, QCBOREncodeContext *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_register (struct golioth_client *client, const char *method_name, golioth_rpc_cb_fn callback, void *callback_arg)
 Register an RPC method. 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) (QCBORDecodeContext *request_params_array, QCBOREncodeContext *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 QCBOR functions like QCBORDecode_GetDouble, QCBORDecode_GetTextString, etc.

If the RPC needs to return data, it can be added to response_detail_map using QCBOR functions like QCBOREncode_AddDoubleToMap, QCBOREncode_AddTextToMap, 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(QCBORDecodeContext* request_params_array,
QCBOREncodeContext* response_detail_map,
void *callback_arg)
{
double a, b;
QCBORDecode_GetDouble(request_params_array, &a);
QCBORDecode_GetDouble(request_params_array, &b);
QCBORError qerr = QCBORDecode_GetError(request_params_array);
if (qerr != QCBOR_SUCCESS) {
LOG_ERR("Failed to decode array items: %d (%s)", qerr, qcbor_err_to_str(qerr));
}
double value = a * b;
QCBOREncode_AddDoubleToMap(response_detail_map, "value", value);
}
Parameters
request_params_arrayQCBOR decode context, inside of the RPC request params array
response_detail_mapQCBOR encode context, 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 91 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 31 of file rpc.h.

Function Documentation

◆ 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
GOLIOTH_RPC_INVALID_ARGUMENT
@ GOLIOTH_RPC_INVALID_ARGUMENT
Definition: rpc.h:35
QCBORDecodeContext
struct _QCBORDecodeContext QCBORDecodeContext
Definition: rpc.h:16
QCBOREncodeContext
struct _QCBOREncodeContext QCBOREncodeContext
Definition: rpc.h:17
golioth_rpc_status
golioth_rpc_status
Enumeration of RPC status codes, sent in the RPC response.
Definition: rpc.h:31
GOLIOTH_RPC_OK
@ GOLIOTH_RPC_OK
Definition: rpc.h:32