WPILibC++  2019.1.1-beta-3-2-g4159660
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
Remote Procedure Call Functions

Typedefs

typedef void(* NT_RpcCallback )(void *data, const struct NT_RpcAnswer *call)
 Remote Procedure Call (RPC) callback function. More...
 

Functions

void NT_CreateRpc (NT_Entry entry, const char *def, size_t def_len, void *data, NT_RpcCallback callback)
 Create a callback-based RPC entry point. More...
 
NT_RpcCallPoller NT_CreateRpcCallPoller (NT_Inst inst)
 Create a RPC call poller. More...
 
void NT_DestroyRpcCallPoller (NT_RpcCallPoller poller)
 Destroy a RPC call poller. More...
 
void NT_CreatePolledRpc (NT_Entry entry, const char *def, size_t def_len, NT_RpcCallPoller poller)
 Create a polled RPC entry point. More...
 
struct NT_RpcAnswerNT_PollRpc (NT_RpcCallPoller poller, size_t *len)
 Get the next incoming RPC call. More...
 
struct NT_RpcAnswerNT_PollRpcTimeout (NT_RpcCallPoller poller, size_t *len, double timeout, NT_Bool *timed_out)
 Get the next incoming RPC call. More...
 
void NT_CancelPollRpc (NT_RpcCallPoller poller)
 Cancel a PollRpc call. More...
 
NT_Bool NT_WaitForRpcCallQueue (NT_Inst inst, double timeout)
 Wait for the incoming RPC call queue to be empty. More...
 
NT_Bool NT_PostRpcResponse (NT_Entry entry, NT_RpcCall call, const char *result, size_t result_len)
 Post RPC response (return value) for a polled RPC. More...
 
NT_RpcCall NT_CallRpc (NT_Entry entry, const char *params, size_t params_len)
 Call a RPC function. More...
 
char * NT_GetRpcResult (NT_Entry entry, NT_RpcCall call, size_t *result_len)
 Get the result (return value) of a RPC call. More...
 
char * NT_GetRpcResultTimeout (NT_Entry entry, NT_RpcCall call, size_t *result_len, double timeout, NT_Bool *timed_out)
 Get the result (return value) of a RPC call. More...
 
void NT_CancelRpcResult (NT_Entry entry, NT_RpcCall call)
 Ignore the result of a RPC call. More...
 
char * NT_PackRpcDefinition (const struct NT_RpcDefinition *def, size_t *packed_len)
 Pack a RPC version 1 definition. More...
 
NT_Bool NT_UnpackRpcDefinition (const char *packed, size_t packed_len, struct NT_RpcDefinition *def)
 Unpack a RPC version 1 definition. More...
 
char * NT_PackRpcValues (const struct NT_Value **values, size_t values_len, size_t *packed_len)
 Pack RPC values as required for RPC version 1 definition messages. More...
 
struct NT_Value ** NT_UnpackRpcValues (const char *packed, size_t packed_len, const enum NT_Type *types, size_t types_len)
 Unpack RPC values as required for RPC version 1 definition messages. More...
 

Detailed Description

Typedef Documentation

typedef void(* NT_RpcCallback)(void *data, const struct NT_RpcAnswer *call)

Remote Procedure Call (RPC) callback function.

Parameters
datadata pointer provided to NT_CreateRpc()
callcall information

Note: NT_PostRpcResponse() must be called by the callback to provide a response to the call.

Function Documentation

NT_RpcCall NT_CallRpc ( NT_Entry  entry,
const char *  params,
size_t  params_len 
)

Call a RPC function.

May be used on either the client or server.

This function is non-blocking. Either NT_GetRpcResult() or NT_CancelRpcResult() must be called to either get or ignore the result of the call.

Parameters
entryentry handle of RPC entry
paramsparameter
params_lenlength of param in bytes
Returns
RPC call handle (for use with NT_GetRpcResult() or NT_CancelRpcResult()).
void NT_CancelPollRpc ( NT_RpcCallPoller  poller)

Cancel a PollRpc call.

This wakes up a call to PollRpc for this poller and causes it to immediately return an empty array.

Parameters
pollerpoller handle
void NT_CancelRpcResult ( NT_Entry  entry,
NT_RpcCall  call 
)

Ignore the result of a RPC call.

This function is non-blocking.

Parameters
entryentry handle of RPC entry
callRPC call handle returned by NT_CallRpc()
void NT_CreatePolledRpc ( NT_Entry  entry,
const char *  def,
size_t  def_len,
NT_RpcCallPoller  poller 
)

Create a polled RPC entry point.

Only valid to use on the server.

The caller is responsible for calling NT_PollRpc() or NT_PollRpcTimeout() to poll for servicing incoming RPC calls.

Parameters
entryentry handle of RPC entry
defRPC definition
def_lenlength of def in bytes
pollerpoller handle
void NT_CreateRpc ( NT_Entry  entry,
const char *  def,
size_t  def_len,
void *  data,
NT_RpcCallback  callback 
)

Create a callback-based RPC entry point.

Only valid to use on the server. The callback function will be called when the RPC is called.

Parameters
entryentry handle of RPC entry
defRPC definition
def_lenlength of def in bytes
datadata pointer to pass to callback function
callbackcallback function
NT_RpcCallPoller NT_CreateRpcCallPoller ( NT_Inst  inst)

Create a RPC call poller.

Only valid to use on the server.

A poller provides a single queue of poll events. Events linked to this poller (using NT_CreatePolledRpc()) will be stored in the queue and must be collected by calling NT_PollRpc() or NT_PollRpcTimeout(). The returned handle must be destroyed with NT_DestroyRpcCallPoller().

Parameters
instinstance handle
Returns
poller handle
void NT_DestroyRpcCallPoller ( NT_RpcCallPoller  poller)

Destroy a RPC call poller.

This will abort any blocked polling call and prevent additional events from being generated for this poller.

Parameters
pollerpoller handle
char* NT_GetRpcResult ( NT_Entry  entry,
NT_RpcCall  call,
size_t *  result_len 
)

Get the result (return value) of a RPC call.

This function blocks until the result is received.

Parameters
entryentry handle of RPC entry
callRPC call handle returned by NT_CallRpc()
result_lenlength of returned result in bytes
Returns
NULL on error, or result.
char* NT_GetRpcResultTimeout ( NT_Entry  entry,
NT_RpcCall  call,
size_t *  result_len,
double  timeout,
NT_Bool timed_out 
)

Get the result (return value) of a RPC call.

This function blocks until the result is received or it times out.

Parameters
entryentry handle of RPC entry
callRPC call handle returned by NT_CallRpc()
result_lenlength of returned result in bytes
timeouttimeout, in seconds
timed_outtrue if the timeout period elapsed (output)
Returns
NULL on error or timeout, or result.
char* NT_PackRpcDefinition ( const struct NT_RpcDefinition def,
size_t *  packed_len 
)

Pack a RPC version 1 definition.

Parameters
defRPC version 1 definition
packed_lenlength of return value in bytes
Returns
Raw packed bytes. Use C standard library std::free() to release.
char* NT_PackRpcValues ( const struct NT_Value **  values,
size_t  values_len,
size_t *  packed_len 
)

Pack RPC values as required for RPC version 1 definition messages.

Parameters
valuesarray of values to pack
values_lenlength of values
packed_lenlength of return value in bytes
Returns
Raw packed bytes. Use C standard library std::free() to release.
struct NT_RpcAnswer* NT_PollRpc ( NT_RpcCallPoller  poller,
size_t *  len 
)

Get the next incoming RPC call.

This blocks until the next incoming RPC call is received. This is intended to be used with NT_CreatePolledRpc(void); RPC calls created using NT_CreateRpc() will not be serviced through this function. Upon successful return, NT_PostRpcResponse() must be called to send the return value to the caller. The returned array must be freed using NT_DisposeRpcAnswerArray().

Parameters
pollerpoller handle
lenlength of returned array (output)
Returns
Array of RPC call information. Only returns NULL if an error occurred (e.g. the instance was invalid or is shutting down).
struct NT_RpcAnswer* NT_PollRpcTimeout ( NT_RpcCallPoller  poller,
size_t *  len,
double  timeout,
NT_Bool timed_out 
)

Get the next incoming RPC call.

This blocks until the next incoming RPC call is received or it times out. This is intended to be used with NT_CreatePolledRpc(); RPC calls created using NT_CreateRpc() will not be serviced through this function. Upon successful return, NT_PostRpcResponse() must be called to send the return value to the caller. The returned array must be freed using NT_DisposeRpcAnswerArray().

Parameters
pollerpoller handle
lenlength of returned array (output)
timeouttimeout, in seconds
timed_outtrue if the timeout period elapsed (output)
Returns
Array of RPC call information. If NULL is returned and timed_out is also false, an error occurred (e.g. the instance was invalid or is shutting down).
NT_Bool NT_PostRpcResponse ( NT_Entry  entry,
NT_RpcCall  call,
const char *  result,
size_t  result_len 
)

Post RPC response (return value) for a polled RPC.

The rpc and call parameters should come from the NT_RpcAnswer returned by NT_PollRpc().

Parameters
entryentry handle of RPC entry (from NT_RpcAnswer)
callRPC call handle (from NT_RpcAnswer)
resultresult raw data that will be provided to remote caller
result_lenlength of result in bytes
Returns
true if the response was posted, otherwise false
NT_Bool NT_UnpackRpcDefinition ( const char *  packed,
size_t  packed_len,
struct NT_RpcDefinition def 
)

Unpack a RPC version 1 definition.

This can be used for introspection or validation.

Parameters
packedraw packed bytes
packed_lenlength of packed in bytes
defRPC version 1 definition (output)
Returns
True if successfully unpacked, false otherwise.
struct NT_Value** NT_UnpackRpcValues ( const char *  packed,
size_t  packed_len,
const enum NT_Type types,
size_t  types_len 
)

Unpack RPC values as required for RPC version 1 definition messages.

Parameters
packedraw packed bytes
packed_lenlength of packed in bytes
typesarray of data types (as provided in the RPC definition)
types_lenlength of types
Returns
Array of NT_Value's.
NT_Bool NT_WaitForRpcCallQueue ( NT_Inst  inst,
double  timeout 
)

Wait for the incoming RPC call queue to be empty.

This is primarily useful for deterministic testing. This blocks until either the RPC call queue is empty (e.g. there are no more events that need to be passed along to callbacks or poll queues) or the timeout expires.

Parameters
instinstance handle
timeouttimeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
Returns
False if timed out, otherwise true.