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");
           return GOLIOTH_RPC_INVALID_ARGUMENT;
     }
 
     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");
           return GOLIOTH_RPC_RESOURCE_EXHAUSTED;
     }
 
     return GOLIOTH_RPC_OK;
}

Parameters

request_params_array	zcbor decode state, inside of the RPC request params array
response_detail_map	zcbor encode state, inside of the RPC response detail map
callback_arg	callback_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

enum 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

client

Client 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

client

Client 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

client	Client instance
method_name	The name of the method to register
callback	The callback to be invoked, when an RPC request with matching method name is received by the client.
callback_arg	User data forwarded to callback when invoked. Optional, can be NULL.

Returns

0 - RPC method successfully registered

<0 - Error registering RPC method