Data Publish/Subscribe C API

The publish/subscribe API provides a topic-based publish/subscribe mechanism to exchange arbitrary user data. It consists of data publishers and data subscribers.

Data Publishers

SilKit_ReturnCode SilKit_DataPublisher_Create(SilKit_DataPublisher **outPublisher, SilKit_Participant *participant, const char *controllerName, SilKit_DataSpec *dataSpec, uint8_t history)

Create a DataPublisher on the provided simulation participant with the provided properties.

Parameters

  • outPublisher – Pointer to which the resulting DataPublisher reference will be written.

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

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

  • dataSpec – The specification of topic, media type and labels.

  • history – A number indicating the number of historic values that should be replayed for a new DataSubscriber. Restricted to {0|1}.

SilKit_ReturnCode SilKit_DataPublisher_Publish(SilKit_DataPublisher *self, const SilKit_ByteVector *data)

Publish data through the provided DataPublisher.

Parameters

  • self – The DataPublisher that should publish the data.

  • data – The data that should be published.

Data Subscribers

SilKit_ReturnCode SilKit_DataSubscriber_Create(SilKit_DataSubscriber **outSubscriber, SilKit_Participant *participant, const char *controllerName, SilKit_DataSpec *dataSpec, void *dataHandlerContext, SilKit_DataMessageHandler_t dataHandler)

Create a DataSubscriber on the provided simulation participant with the provided properties.

Parameters

  • outSubscriber – Pointer to which the resulting DataSubscriber reference will be written.

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

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

  • dataSpec – The specification of topic, media type and labels.

  • dataHandlerContext – A user provided context that is reobtained on data reception in the dataHandler.

  • dataHandler – The handler that is called on data reception. Can be overwritten by SilKit_DataSubscriber_SetDataMessageHandler.

SilKit_ReturnCode SilKit_DataSubscriber_SetDataMessageHandler(SilKit_DataSubscriber *self, void *context, SilKit_DataMessageHandler_t dataHandler)

Sets / overwrites the default handler to be called on data reception.

Parameters

  • self – The DataSubscriber for which the handler should be set.

  • context – A user provided context, that is reobtained on data reception in the dataHandler.

  • dataHandler – A handler that is called on data reception.

Handlers

The DataSubscriber is created with a handler for data reception:

typedef void (*SilKit_DataMessageHandler_t)(void *context, SilKit_DataSubscriber *subscriber, const SilKit_DataMessageEvent *dataMessageEvent)

Handler type for incoming data message events on DataSubscribers.

Param context

The context that the user provided on registration.

Param subscriber

The affected subscriber.

Param dataMessageEvent

Contains the raw data and send timestamp.

Data Structures

struct SilKit_DataMessageEvent

An incoming DataMessage of a DataPublisher containing raw data and timestamp.

Public Members

SilKit_StructHeader structHeader
SilKit_NanosecondsTime timestamp

Send timestamp of the event.

SilKit_ByteVector data

Data field containing the payload.