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.