API Documentation

Messaging

The Messaging API is used to pass information on the PolySync bus through messages. During runtime, messages are published and subscribed to the PolySync bus by all participating nodes, communicating sensor data, diagnostic status, vehicle control commands, and more.

The data model IDL files contain abstracted message definitions for sensor and hardware data. These messages can be extended to include additional fields, and new messages (and IDL files) can be added to the data model. During runtime, message types are enumerated to a value that must be queried by PolySync applications using the Messaging API and the message names below.

Usage
#include <polysync_message.h>

Core Data Model
Sensor Data Model
Control Data Model

Many messages have fields defined by sequences of variable length. In the case of ps_objects_msg for instance, you can access the sequence of ps_object like an array using the following syntax.

Functions

psync_message_get_type ( … )

This will get the message type identifier of a message.

The type identifier is used to publish and subscribe to the message.

Parameters
In/Out Type Name Description
In const ps_msg_ref message A message reference.
Out ps_msg_type * const msg_type A pointer to ps_msg_type that receives the type identifier value.
Returns

psync_message_get_timestamp ( … )

This will get the header timestamp of a message, which represents the time immediately before the message was published to the PolySync bus.

Parameters
In/Out Type Name Description
In const ps_msg_ref message A message reference.
Out ps_timestamp *const timestamp A pointer to ps_timestamp that receives the timestamp value.
Returns

psync_message_set_timestamp ( … )

This function will set the header timestamp of a message.

Parameters
In/Out Type Name Description
In ps_msg_ref message A message reference.
In const ps_timestamp timestamp The timestamp value.
Returns

psync_message_get_source_guid ( … )

This will get the source GUID of a message.

Parameters
In/Out Type Name Description
In const ps_msg_ref message A message reference.
Out ps_guid *const guid A pointer to ps_guid that receives the source GUID value.
Returns

psync_message_set_source_guid ( … )

This will set the source GUID of a message.

Parameters
In/Out Type Name Description
In ps_msg_ref message A message reference.
In const ps_guid guid A source GUID value.
Returns

psync_message_get_header ( … )

This will get the header of a message.

Parameters
In/Out Type Name Description
In const ps_msg_ref message A message reference.
Out ps_msg_header *const header A pointer to ps_msg_header that receives the header values.
Returns

psync_message_is_type_supported ( … )

This will check if the message type is supported.

Parameters
In/Out Type Name Description
In const ps_node_ref node_ref A node reference to provide data model support.
In const ps_msg_type msg_type The message type identifier to check.
Returns

psync_message_get_count ( … )

This will get the total number of messages defined in the data model.

Parameters
In/Out Type Name Description
In const ps_node_ref node_ref A node reference to provide data model support.
Out unsigned long *const count A pointer to unsigned long that receives the count value.
Returns

psync_message_get_type_by_name ( … )

This function will get the message type identifier value using its name.

The type identifier is used to publish and subscribe to the message.

Parameters
In/Out Type Name Description
In const ps_node_ref node_ref A node reference to provide data model support.
In const char *const type_name A pointer to char buffer that specifies the name to lookup.
Out ps_msg_type *const msg_type A pointer to ps_msg_type that receives the type identifier value.
Returns

psync_message_get_name_by_type ( … )

This will get a message name value using its type identifier.

Parameters
In/Out Type Name Description
In const ps_node_ref node_ref A node reference to provide data model support.
In const ps_msg_type msg_type A message type identifier to lookup.
Out char *const name_buffer A pointer to char buffer that receives the name value.
In const size_t name_buffer_len The length of a provided name_buffer.
Returns

psync_message_register_listener ( … )

This will register a listener callback to a given message type identifier.

The callback will be called when a message of the given type is received from the PolySync bus.

All listeners are handled by a single thread context, having multiple listeners attached to a single callback routine is allowed.

Parameters
In/Out Type Name Description
In ps_node_ref node_ref A node reference to provide data model support.
In const ps_msg_type msg_type The message type identifier to listen for.
In const psync_message_ondata_listener user_callback The user callback function to handle the incoming message.
In const void *const user_data A pointer to user data provided to the callback function. NULL is allowed.
Returns

psync_message_unregister_listener ( … )

This will unregister a listener callback associated with a given message type identifier.

Parameters
In/Out Type Name Description
In ps_node_ref node_ref A node reference to provide data model support.
In const ps_msg_type msg_type A message type identifier to unregister.
Returns

psync_message_alloc ( … )

This will allocate a message of the specified type.

Parameters
In/Out Type Name Description
In ps_node_ref node_ref Node reference to provide data model support.
In const ps_msg_type msg_type Message type identifier to request.
Out ps_msg_ref * message_ptr A pointer to ps_msg_ref that receives the new instance.
Returns

psync_message_free ( … )

This function will free a message and its resources.

Parameters
In/Out Type Name Description
In ps_node_ref node_ref A node reference to provide data model support.
In ps_msg_ref * message_ptr A pointer to ps_msg_ref that gets released.
Returns

psync_message_publish ( … )

This function will publish a message from a local reference.

Parameters
In/Out Type Name Description
In ps_node_ref node_ref A node reference to provide data model support.
In ps_msg_ref message A message reference.
Returns

psync_message_copy ( … )

This will copy a message.

psync_message_copy must have allocated resources for the destination message with psync_message_alloc.

Parameters
In/Out Type Name Description
In const ps_node_ref node_ref A node reference to provide data model support.
In const ps_msg_ref src_message A message reference to copy from.
In const ps_msg_ref dst_message A message reference to copy to.
Returns

Macros

PSYNC_MSG_REF_INVALID

Type Value Description
int NULL Invalid ps_msg_ref value.

Typedefs

ps_msg_ref

Type Description
void * Opaque message reference data type.

Value PSYNC_MSG_REF_INVALID means invalid.

psync_message_ondata_listener

The function pointer type for a data model message listener user on-data callback.

Parameters
In/Out Type Name Description
In const ps_msg_type msg_type Message type identifier for the message, as seen by this data model.
In const ps_msg_ref message Message reference to be handled by the function.
In void * const user_data A pointer to user data, provided by psync_message_register_listener.