# 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

    See also

    dds_resume indicating that the set of modifications has completed.

    Parameters:

      - publisher – [in] The publisher for which all publications will be suspended.

    Return values:

      - DDS_RETCODE_OK – Publications suspended successfully.

      - DDS_RETCODE_BAD_PARAMETER – The pub parameter is not a valid publisher.

      - DDS_RETCODE_UNSUPPORTED – Operation is not supported.

    Returns:

      A dds_return_t indicating success or failure.

  dds_return_t dds_resume(dds_entity_t publisher)

    Resumes the publications of the Publisher.

    This operation is a hint to the Service to indicate that the application has completed changes initiated by a previous dds_suspend(). The Service is not required to use the hint.

    The call to resume_publications must match a previous call to

    See also

    suspend_publications.

    Parameters:

      - publisher – [in] The publisher for which all publications will be resumed.

    Return values:

      - DDS_RETCODE_OK – Publications resumed successfully.

      - DDS_RETCODE_BAD_PARAMETER – The pub parameter is not a valid publisher.

      - DDS_RETCODE_PRECONDITION_NOT_MET – No previous matching dds_suspend().

      - DDS_RETCODE_UNSUPPORTED – Operation is not supported.

    Returns:

      A dds_return_t indicating success or failure.

## 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 data)

  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.