RPC C API

The RPC API provides client/server based RPC functionality. It consists of RPC clients and RPC servers and a method to discover remote RPC servers.

RPC Clients

SilKit_ReturnCode SilKit_RpcClient_Create(SilKit_RpcClient **outClient, SilKit_Participant *participant, const char *controllerName, SilKit_RpcSpec *rpcSpec, void *resultHandlerContext, SilKit_RpcCallResultHandler_t resultHandler)

Create a RPC client on a simulation participant with the provided properties.

Parameters:

  • outClient – Pointer to which the resulting RPC client reference will be written.

  • participant – The simulation participant for which the RPC client should be created.

  • controllerName – The name of this controller (UTF-8).

  • rpcSpec – The specification of function name, media type and labels.

  • resultHandlerContext – A user provided context that is reobtained on call result in the resultHandler.

  • resultHandler – A callback that is called when a call result is received.

SilKit_ReturnCode SilKit_RpcClient_Call(SilKit_RpcClient *self, const SilKit_ByteVector *argumentData, void *userContext)

Dispatch a call to one or multiple corresponding RPC servers.

Parameters:

  • self – The RPC client that should trigger the remote procedure call.

  • argumentData – The data that should be transmitted to the RPC server for this call.

  • userContext – A user provided context pointer that is passed to the result handler when a result is received.

SilKit_ReturnCode SilKit_RpcClient_CallWithTimeout(SilKit_RpcClient *self, const SilKit_ByteVector *argumentData, SilKit_NanosecondsTime timeout, void *userContext)

Initiate a remote procedure call with a specified timeout.

In a synchronized execution, simulation time is used for the timeout, in a unsynchronized execution, system time is used for the timeout.

Parameters:

  • self – The RPC client that should trigger the remote procedure call.

  • argumentData – A non-owning reference to an opaque block of raw data

  • timeout – A duration in nanoseconds after which the call runs into a timeout and the CallResultHandler is called with status timeout. After the timeout occurred, no further call result events will be triggered for this call.

  • userContext – An optional user provided pointer that is reobtained when receiving the call result.

An RpcClient is created with a handler for the call return by RPC servers: .. doxygentypedef:: SilKit_CallResultHandler_t

RPC Servers

SilKit_ReturnCode SilKit_RpcServer_Create(SilKit_RpcServer **outServer, SilKit_Participant *participant, const char *controllerName, SilKit_RpcSpec *rpcSpec, void *callHandlerContext, SilKit_RpcCallHandler_t callHandler)

Create a RPC server on a simulation participant with the provided properties.

Parameters:

  • outServer – Pointer to which the resulting RPC server reference will be written.

  • participant – The simulation participant for which the RPC server should be created.

  • controllerName – The name of this controller (UTF-8).

  • rpcSpec – A struct containing all matching related information

  • callHandlerContext – A user provided context pointer that is passed to the callHandler on call.

  • callHandler – A callback function that is triggered on invocation of the server functionality.

SilKit_ReturnCode SilKit_RpcServer_SubmitResult(SilKit_RpcServer *self, SilKit_RpcCallHandle *callHandle, const SilKit_ByteVector *returnData)

Submit a result for an earlier obtained call handle to an RPC client.

Parameters:

  • self – The RPC server that should submit the result of the remote procedure call.

  • callHandle – The call handle that was obtained earlier through an SilKit_RpcCallResultHandler_t.

  • returnData – The data that should be returned to the calling client.

An RpcServer is created with a handler to process incoming calls by RPC clients:

typedef void (*SilKit_RpcCallHandler_t)(void *context, SilKit_RpcServer *server, const SilKit_RpcCallEvent *event)

A callback function that is called on a RPC server triggered by client.

Param context:

The user provided context pointer that was provided when this handler was registered.

Param server:

The RPC server that received the call.

Param event:

The event contains information about the call by the client.

Data Structures

typedef struct SilKit_RpcCallHandle SilKit_RpcCallHandle

A unique handle of a remote call.

typedef uint32_t SilKit_RpcCallStatus

The status of a RpcCallResultEvent. Informs whether a call was successful.