Publication¶

group publication

DOC_TODO This contains the definitions regarding publication of data.

Functions

dds_return_t dds_wait_for_acks(dds_entity_t publisher_or_writer, dds_duration_t timeout)¶

Waits at most for the duration timeout for acks for data in the publisher or writer.

This operation blocks the calling thread until either all data written by the publisher or writer is acknowledged by all matched reliable reader entities, or else the duration specified by the timeout parameter elapses, whichever happens first.

Parameters

publisher_or_writer – [in] Publisher or writer whose acknowledgments must be waited for
timeout – [in] How long to wait for acknowledgments before time out

Return values

DDS_RETCODE_OK – All acknowledgments successfully received with the timeout.
DDS_RETCODE_BAD_PARAMETER – The publisher_or_writer is not a valid publisher or writer.
DDS_RETCODE_TIMEOUT – Timeout expired before all acknowledgments from reliable reader entities were received.
DDS_RETCODE_UNSUPPORTED – Operation is not supported.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_begin_coherent(dds_entity_t entity)¶

Begin coherent publishing or begin accessing a coherent set in a subscriber.

Invoking on a Writer or Reader behaves as if dds_begin_coherent was invoked on its parent Publisher or Subscriber respectively.

Parameters

entity – [in] The entity that is prepared for coherent access.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – The provided entity is invalid or not supported.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_end_coherent(dds_entity_t entity)¶

End coherent publishing or end accessing a coherent set in a subscriber.

Invoking on a Writer or Reader behaves as if dds_end_coherent was invoked on its parent Publisher or Subscriber respectively.

Parameters

entity – [in] The entity on which coherent access is finished.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – The provided entity is invalid or not supported.

Returns

A dds_return_t indicating success or failure.

Publisher¶

group publisher

DOC_TODO The Publisher is a DDS Entity

Functions

dds_entity_t dds_create_publisher(dds_entity_t participant, const dds_qos_t *qos, const dds_listener_t *listener)¶

Creates a new instance of a DDS publisher.

Parameters

participant – [in] The participant to create a publisher for.
qos – [in] The QoS to set on the new publisher (can be NULL).
listener – [in] Any listener functions associated with the new publisher (can be NULL).

Return values

>0 – A valid publisher handle.
DDS_RETCODE_ERROR – An internal error has occurred.

Returns

A valid publisher handle or an error code.

dds_return_t dds_suspend(dds_entity_t publisher)¶

Suspends the publications of the Publisher.

This operation is a hint to the Service so it can optimize its performance by e.g., collecting modifications to DDS writers and then batching them. The Service is not required to use the hint.

Every invocation of this operation must be matched by a corresponding call to

Writer¶

group writer

DOC_TODO The writer is a DDS Entity

Functions

dds_entity_t dds_create_writer(dds_entity_t participant_or_publisher, dds_entity_t topic, const dds_qos_t *qos, const dds_listener_t *listener)¶

Creates a new instance of a DDS writer.

When a participant is used to create a writer, an implicit publisher is created. This implicit publisher will be deleted automatically when the created writer is deleted.

DOC_TODO: Complete list of error codes

Parameters

participant_or_publisher – [in] The participant or publisher on which the writer is being created.
topic – [in] The topic to write.
qos – [in] The QoS to set on the new writer (can be NULL).
listener – [in] Any listener functions associated with the new writer (can be NULL).

Returns

A valid writer handle or an error code.

Returns

>0 A valid writer handle.

Returns

DDS_RETCODE_ERROR An internal error occurred.

Writing Operations¶

group writing

Writing data (and variants of it) is straightforward. The first set is equivalent to the second set with -1 passed for “timestamp”, meaning, substitute the result of a call to time(). The dispose and unregister operations take an object of the topic’s type, but only touch the key fields; the remained may be undefined.

Functions

dds_return_t dds_register_instance(dds_entity_t writer, dds_instance_handle_t *handle, const void *data)¶

Registers an instance.

This operation registers an instance with a key value to the data writer and returns an instance handle that could be used for successive write & dispose operations. When the handle is not allocated, the function will return an error and the handle will be un-touched.

Parameters

writer – [in] The writer to which instance has be associated.
handle – [out] The instance handle.
data – [in] The instance with the key value.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_unregister_instance(dds_entity_t writer, const void *data)¶

Unregisters an instance by instance.

This operation reverses the action of register instance, removes all information regarding the instance and unregisters an instance with a key value from the data writer.

Parameters

writer – [in] The writer to which instance is associated.
data – [in] The instance with the key value.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_unregister_instance_ih(dds_entity_t writer, dds_instance_handle_t handle)¶

Unregisters an instance by instance handle.

This operation unregisters the instance which is identified by the key fields of the given typed instance handle.

Parameters

writer – [in] The writer to which instance is associated.
handle – [in] The instance handle.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_unregister_instance_ts(dds_entity_t writer, const void *data, dds_time_t timestamp)¶

Unregisters an instance by instance with timestamp.

This operation reverses the action of register instance, removes all information regarding the instance and unregisters an instance with a key value from the data writer. It also provides a value for the timestamp explicitly.

Parameters

writer – [in] The writer to which instance is associated.
data – [in] The instance with the key value.
timestamp – [in] The timestamp used at registration.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_unregister_instance_ih_ts(dds_entity_t writer, dds_instance_handle_t handle, dds_time_t timestamp)¶

Unregisters an instance by instance handle with timestamp.

This operation unregisters an instance with a key value from the handle. Instance can be identified from instance handle. If an unregistered key ID is passed as an instance data, an error is logged and not flagged as return value.

Parameters

writer – [in] The writer to which instance is associated.
handle – [in] The instance handle.
timestamp – [in] The timestamp used at registration.

Return values

DDS_RETCODE_OK – The operation was successful
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_writedispose(dds_entity_t writer, const void *data)¶

This operation modifies and disposes a data instance.

This operation requests the Data Distribution Service to modify the instance and mark it for deletion. Copies of the instance and its corresponding samples, which are stored in every connected reader and, dependent on the QoS policy settings (also in the Transient and Persistent stores) will be modified and marked for deletion by setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED.

Blocking: If the history QoS policy is set to DDS_HISTORY_KEEP_ALL, the dds_writedispose operation on the writer may block if the modification would cause data to be lost because one of the limits, specified in the resource_limits QoS policy, to be exceeded. In case the synchronous attribute value of the reliability Qos policy is set to true for communicating writers and readers then the writer will wait until all synchronous readers have acknowledged the data. Under these circumstances, the max_blocking_time attribute of the reliability QoS policy configures the maximum time the dds_writedispose operation may block. If max_blocking_time elapses before the writer is able to store the modification without exceeding the limits and all expected acknowledgements are received, the dds_writedispose operation will fail and returns DDS_RETCODE_TIMEOUT.

Parameters

writer – [in] The writer to dispose the data instance from.
data – [in] The data to be written and disposed.

Return values

DDS_RETCODE_OK – The sample is written and the instance is marked for deletion.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – At least one of the arguments is invalid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.
DDS_RETCODE_TIMEOUT – Either the current action overflowed the available resources as specified by the combination of the reliability QoS policy, history QoS policy and resource_limits QoS policy, or the current action was waiting for data delivery acknowledgement by synchronous readers. This caused blocking of this operation, which could not be resolved before max_blocking_time of the reliability QoS policy elapsed.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_writedispose_ts(dds_entity_t writer, const void *data, dds_time_t timestamp)¶

This operation modifies and disposes a data instance with a specific timestamp.

This operation performs the same functions as dds_writedispose() except that the application provides the value for the source_timestamp that is made available to connected reader objects. This timestamp is important for the interpretation of the destination_order QoS policy.

Parameters

writer – [in] The writer to dispose the data instance from.
data – [in] The data to be written and disposed.
timestamp – [in] The timestamp used as source timestamp.

Return values

DDS_RETCODE_OK – The sample is written and the instance is marked for deletion.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – At least one of the arguments is invalid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.
DDS_RETCODE_TIMEOUT – Either the current action overflowed the available resources as specified by the combination of the reliability QoS policy, history QoS policy and resource_limits QoS policy, or the current action was waiting for data delivery acknowledgement by synchronous readers. This caused blocking of this operation, which could not be resolved before max_blocking_time of the reliability QoS policy elapsed.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_dispose(dds_entity_t writer, const void *data)¶

This operation disposes an instance, identified by the data sample.

This operation requests the Data Distribution Service to modify the instance and mark it for deletion. Copies of the instance and its corresponding samples, which are stored in every connected reader and, dependent on the QoS policy settings (also in the Transient and Persistent stores) will be modified and marked for deletion by setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED.

Blocking: If the history QoS policy is set to DDS_HISTORY_KEEP_ALL, the dds_writedispose operation on the writer may block if the modification would cause data to be lost because one of the limits, specified in the resource_limits QoS policy, to be exceeded. In case the synchronous attribute value of the reliability Qos policy is set to true for communicating writers and readers then the writer will wait until all synchronous readers have acknowledged the data. Under these circumstances, the max_blocking_time attribute of the reliability QoS policy configures the maximum time the dds_writedispose operation may block. If max_blocking_time elapses before the writer is able to store the modification without exceeding the limits and all expected acknowledgements are received, the dds_writedispose operation will fail and returns DDS_RETCODE_TIMEOUT.

Parameters

writer – [in] The writer to dispose the data instance from.
data – [in] The data sample that identifies the instance to be disposed.

Return values

DDS_RETCODE_OK – The sample is written and the instance is marked for deletion.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – At least one of the arguments is invalid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.
DDS_RETCODE_TIMEOUT – Either the current action overflowed the available resources as specified by the combination of the reliability QoS policy, history QoS policy and resource_limits QoS policy, or the current action was waiting for data delivery acknowledgement by synchronous readers. This caused blocking of this operation, which could not be resolved before max_blocking_time of the reliability QoS policy elapsed.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_dispose_ts(dds_entity_t writer, const void *data, dds_time_t timestamp)¶

This operation disposes an instance with a specific timestamp, identified by the data sample.

This operation performs the same functions as dds_dispose() except that the application provides the value for the source_timestamp that is made available to connected reader objects. This timestamp is important for the interpretation of the destination_order QoS policy.

Parameters

writer – [in] The writer to dispose the data instance from.
data – [in] The data sample that identifies the instance to be disposed.
timestamp – [in] The timestamp used as source timestamp.

Return values

DDS_RETCODE_OK – The sample is written and the instance is marked for deletion
DDS_RETCODE_ERROR – An internal error has occurred
DDS_RETCODE_BAD_PARAMETER – At least one of the arguments is invalid
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted
DDS_RETCODE_TIMEOUT – Either the current action overflowed the available resources as specified by the combination of the reliability QoS policy, history QoS policy and resource_limits QoS policy, or the current action was waiting for data delivery acknowledgment by synchronous readers. This caused blocking of this operation, which could not be resolved before max_blocking_time of the reliability QoS policy elapsed.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_dispose_ih(dds_entity_t writer, dds_instance_handle_t handle)¶

This operation disposes an instance, identified by the instance handle.

This operation requests the Data Distribution Service to modify the instance and mark it for deletion. Copies of the instance and its corresponding samples, which are stored in every connected reader and, dependent on the QoS policy settings (also in the Transient and Persistent stores) will be modified and marked for deletion by setting their dds_instance_state_t to DDS_IST_NOT_ALIVE_DISPOSED.

Instance Handle: The given instance handle must correspond to the value that was returned by either the dds_register_instance operation, dds_register_instance_ts or dds_lookup_instance. If there is no correspondence, then the result of the operation is unspecified.

Parameters

writer – [in] The writer to dispose the data instance from.
handle – [in] The handle to identify an instance.

Return values

DDS_RETCODE_OK – The sample is written and the instance is marked for deletion.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – At least one of the arguments is invalid
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted
DDS_RETCODE_PRECONDITION_NOT_MET – The instance handle has not been registered with this writer

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_dispose_ih_ts(dds_entity_t writer, dds_instance_handle_t handle, dds_time_t timestamp)¶

This operation disposes an instance with a specific timestamp, identified by the instance handle.

This operation performs the same functions as dds_dispose_ih() except that the application provides the value for the source_timestamp that is made available to connected reader objects. This timestamp is important for the interpretation of the destination_order QoS policy.

Parameters

writer – [in] The writer to dispose the data instance from.
handle – [in] The handle to identify an instance.
timestamp – [in] The timestamp used as source timestamp.

Return values

DDS_RETCODE_OK – The sample is written and the instance is marked for deletion.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – At least one of the arguments is invalid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.
DDS_RETCODE_PRECONDITION_NOT_MET – The instance handle has not been registered with this writer.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_write(dds_entity_t writer, const void *data)¶

Write the value of a data instance.

With this API, the value of the source timestamp is automatically made available to the data reader by the service.

Parameters

writer – [in] The writer entity.
data – [in] Value to be written.

Returns

dds_return_t indicating success or failure.

void dds_write_flush(dds_entity_t writer)¶

Flush a writers batched writes.

When using the WriteBatch mode you can manually batch small writes into larger datapackets for network efficiency. The normal dds_write() calls will no longer automatically decide when to send data, you will do that manually using this function.

DOC_TODO check if my assumptions about how this function works are correct

Parameters

writer – [in] The writer entity.

dds_return_t dds_writecdr(dds_entity_t writer, struct ddsi_serdata *serdata)¶

Write a serialized value of a data instance.

This call causes the writer to write the serialized value that is provided in the serdata argument. Timestamp and statusinfo fields are set to the current time and 0 (indicating a regular write), respectively.

Parameters

writer – [in] The writer entity.
serdata – [in] Serialized value to be written.

Return values

DDS_RETCODE_OK – The writer successfully wrote the serialized value.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.
DDS_RETCODE_TIMEOUT – The writer failed to write the serialized value reliably within the specified max_blocking_time.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_forwardcdr(dds_entity_t writer, struct ddsi_serdata *serdata)¶

Write a serialized value of a data instance.

This call causes the writer to write the serialized value that is provided in the serdata argument. Timestamp and statusinfo are used as is.

Parameters

writer – [in] The writer entity.
serdata – [in] Serialized value to be written.

Return values

DDS_RETCODE_OK – The writer successfully wrote the serialized value.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.
DDS_RETCODE_TIMEOUT – The writer failed to write the serialized value reliably within the specified max_blocking_time.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_write_ts(dds_entity_t writer, const void *data, dds_time_t timestamp)¶

Write the value of a data instance along with the source timestamp passed.

Parameters

writer – [in] The writer entity.
data – [in] Value to be written.
timestamp – [in] Source timestamp.

Returns

A dds_return_t indicating success or failure.