Subscription¶

group subscription: DOC_TODO This contains the definitions regarding subscribing to data.

Subscriber¶

group subscriber

DOC_TODO The Subscriber is a DDS Entity

Functions

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

Creates a new instance of a DDS subscriber.

Parameters

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

Return values

>0 – A valid subscriber handle.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the parameters is invalid.

Returns

A valid subscriber handle or an error code.

dds_return_t dds_notify_readers(dds_entity_t subscriber)¶

Trigger DATA_AVAILABLE event on contained readers.

The DATA_AVAILABLE event is broadcast to all readers owned by this subscriber that currently have new data available. Any on_data_available listener callbacks attached to respective readers are invoked.

Parameters

subscriber – [in] A valid subscriber handle.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – The provided subscriber is invalid.

Returns

A dds_return_t indicating success or failure.

Reader¶

group reader

DOC_TODO The reader is a DDS Entity

Functions

dds_entity_t dds_create_reader(dds_entity_t participant_or_subscriber, dds_entity_t topic, const dds_qos_t *qos, const dds_listener_t *listener)¶

Creates a new instance of a DDS reader.

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

DOC_TODO: Complete list of error codes

Parameters

participant_or_subscriber – [in] The participant or subscriber on which the reader is being created.
topic – [in] The topic to read.
qos – [in] The QoS to set on the new reader (can be NULL).
listener – [in] Any listener functions associated with the new reader (can be NULL).

Return values

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

Returns

A valid reader handle or an error code.

dds_entity_t dds_create_reader_rhc(dds_entity_t participant_or_subscriber, dds_entity_t topic, const dds_qos_t *qos, const dds_listener_t *listener, struct dds_rhc *rhc)¶

Creates a new instance of a DDS reader with a custom history cache.

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

DOC_TODO: Complete list of error codes

Parameters

participant_or_subscriber – [in] The participant or subscriber on which the reader is being created.
topic – [in] The topic to read.
qos – [in] The QoS to set on the new reader (can be NULL).
listener – [in] Any listener functions associated with the new reader (can be NULL).
rhc – [in] Reader history cache to use, reader becomes the owner

Return values

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

Returns

A valid reader handle or an error code.

dds_return_t dds_reader_wait_for_historical_data(dds_entity_t reader, dds_duration_t max_wait)¶

Wait until reader receives all historic data.

The operation blocks the calling thread until either all “historical” data is received, or else the duration specified by the max_wait parameter elapses, whichever happens first. A return value of 0 indicates that all the “historical” data was received; a return value of TIMEOUT indicates that max_wait elapsed before all the data was received.

DOC_TODO: Complete list of error codes

Parameters

reader – [in] The reader on which to wait for historical data.
max_wait – [in] How long to wait for historical data before time out.

Returns

a status, 0 on success, TIMEOUT on timeout or a negative value to indicate error.

Reading Ops¶

group reading

There are a number of ways to aquire data, divided into variations of “read” and “take”. The return value of a read/take operation is the number of elements returned. “max_samples” should have the same type, as one can’t return more than MAX_INT this way, anyway. X, Y, CX, CY return to the various filtering options, see the DCPS spec.

O ::= read | take

X => CX (empty) (empty) _next_instance instance_handle_t prev

Y => CY (empty) uint32_t mask _cond cond_t cond — refers to a read condition (or query if implemented)

Defines

DDS_HAS_READCDR¶

Set when function dds_has_readcdr is defined.

Functions

dds_return_t dds_read(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs)¶

Access and read the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition.

Return value provides information about number of samples read, which will be <= maxs. Based on the count, the buffer will contain data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the Data. Data values once read will remain in the buffer with the sample_state set to READ and view_state set to NOT_NEW.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
bufsz – [in] The size of buffer provided.
maxs – [in] Maximum number of samples to read.

Return values

>=0 – Number of samples read.
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.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_read_wl(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs)¶

Access and read loaned samples of data reader, readcondition or querycondition.

After dds_read_wl function is being called and the data has been handled, dds_return_loan() function must be called to possibly free memory.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL)
si – [out] Pointer to an array of dds_sample_info_t returned for each data value
maxs – [in] Maximum number of samples to read

Return values

>=0 – Number of samples read.
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.

Returns

A dds_return_t with the number of samples read or an error code

dds_return_t dds_read_mask(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, uint32_t mask)¶

Read the collection of data values and sample info from the data reader, readcondition or querycondition based on mask.

When using a readcondition or querycondition, their masks are or’d with the given mask.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
bufsz – [in] The size of buffer provided.
maxs – [in] Maximum number of samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_read_mask_wl(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, uint32_t mask)¶

Access and read loaned samples of data reader, readcondition or querycondition based on mask.

When using a readcondition or querycondition, their masks are or’d with the given mask.

After dds_read_mask_wl function is being called and the data has been handled, dds_return_loan() function must be called to possibly free memory

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
maxs – [in] Maximum number of samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_read_instance(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, dds_instance_handle_t handle)¶

Access and read the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition, coped by the provided instance handle.

This operation implements the same functionality as dds_read, except that only data scoped to the provided instance handle is read.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
bufsz – [in] The size of buffer provided.
maxs – [in] Maximum number of samples to read.
handle – [in] Instance handle related to the samples to read.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_read_instance_wl(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, dds_instance_handle_t handle)¶

Access and read loaned samples of data reader, readcondition or querycondition, scoped by the provided instance handle.

This operation implements the same functionality as dds_read_wl, except that only data scoped to the provided instance handle is read.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
maxs – [in] Maximum number of samples to read.
handle – [in] Instance handle related to the samples to read.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_read_instance_mask(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask)¶

Read the collection of data values and sample info from the data reader, readcondition or querycondition based on mask and scoped by the provided instance handle.

This operation implements the same functionality as dds_read_mask, except that only data scoped to the provided instance handle is read.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
bufsz – [in] The size of buffer provided.
maxs – [in] Maximum number of samples to read.
handle – [in] Instance handle related to the samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_read_instance_mask_wl(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask)¶

Access and read loaned samples of data reader, readcondition or querycondition based on mask, scoped by the provided instance handle.

This operation implements the same functionality as dds_read_mask_wl, except that only data scoped to the provided instance handle is read.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
maxs – [in] Maximum number of samples to read.
handle – [in] Instance handle related to the samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_take(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs)¶

Access the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition.

Data value once read is removed from the Data Reader cannot to ‘read’ or ‘taken’ again. Return value provides information about number of samples read, which will be <= maxs. Based on the count, the buffer will contain data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the Data.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
bufsz – [in] The size of buffer provided.
maxs – [in] Maximum number of samples to read.

Return values

>=0 – Number of samples read.
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.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_take_wl(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs)¶

Access loaned samples of data reader, readcondition or querycondition.

After dds_take_wl function is being called and the data has been handled, dds_return_loan() function must be called to possibly free memory

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
maxs – [in] Maximum number of samples to read.

Return values

>=0 – Number of samples read.
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.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_take_mask(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, uint32_t mask)¶

Take the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition based on mask.

When using a readcondition or querycondition, their masks are or’d with the given mask.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
bufsz – [in] The size of buffer provided.
maxs – [in] Maximum number of samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_take_mask_wl(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, uint32_t mask)¶

Access loaned samples of data reader, readcondition or querycondition based on mask.

When using a readcondition or querycondition, their masks are or’d with the given mask.

After dds_take_mask_wl function is being called and the data has been handled, dds_return_loan() function must be called to possibly free memory

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
maxs – [in] Maximum number of samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_readcdr(dds_entity_t reader_or_condition, struct ddsi_serdata **buf, uint32_t maxs, dds_sample_info_t *si, uint32_t mask)¶

Access the collection of serialized data values (of same type) and sample info from the data reader, readcondition or querycondition.

This call accesses the serialized data from the data reader, readcondition or querycondition and makes it available to the application. The serialized data is made available through ddsi_serdata structures. Returned samples are marked as READ.

Return value provides information about the number of samples read, which will be <= maxs. Based on the count, the buffer will contain serialized data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the data.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to ddsi_serdata structures that contain the serialized data. The pointers can be NULL.
maxs – [in] Maximum number of samples to read.
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The precondition for this operation is not met.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_readcdr_instance(dds_entity_t reader_or_condition, struct ddsi_serdata **buf, uint32_t maxs, dds_sample_info_t *si, dds_instance_handle_t handle, uint32_t mask)¶

Access the collection of serialized data values (of same type) and sample info from the data reader, readcondition or querycondition scoped by the provided instance handle.

This operation implements the same functionality as dds_read_instance_wl, except that samples are now in their serialized form. The serialized data is made available through ddsi_serdata structures. Returned samples are marked as READ.

Return value provides information about the number of samples read, which will be <= maxs. Based on the count, the buffer will contain serialized data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the data.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to ddsi_serdata structures that contain the serialized data. The pointers can be NULL.
maxs – [in] Maximum number of samples to read.
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
handle – [in] Instance handle related to the samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_takecdr(dds_entity_t reader_or_condition, struct ddsi_serdata **buf, uint32_t maxs, dds_sample_info_t *si, uint32_t mask)¶

Access the collection of serialized data values (of same type) and sample info from the data reader, readcondition or querycondition.

This call accesses the serialized data from the data reader, readcondition or querycondition and makes it available to the application. The serialized data is made available through ddsi_serdata structures. Once read the data is removed from the reader and cannot be ‘read’ or ‘taken’ again.

Return value provides information about the number of samples read, which will be <= maxs. Based on the count, the buffer will contain serialized data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the data.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to ddsi_serdata structures that contain the serialized data. The pointers can be NULL.
maxs – [in] Maximum number of samples to read.
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The precondition for this operation is not met.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_takecdr_instance(dds_entity_t reader_or_condition, struct ddsi_serdata **buf, uint32_t maxs, dds_sample_info_t *si, dds_instance_handle_t handle, uint32_t mask)¶

Access the collection of serialized data values (of same type) and sample info from the data reader, readcondition or querycondition scoped by the provided instance handle.

This operation implements the same functionality as dds_take_instance_wl, except that samples are now in their serialized form. The serialized data is made available through ddsi_serdata structures. Returned samples are marked as READ.

Return value provides information about the number of samples read, which will be <= maxs. Based on the count, the buffer will contain serialized data to be read only when valid_data bit in sample info structure is set. The buffer required for data values, could be allocated explicitly or can use the memory from data reader to prevent copy. In the latter case, buffer and sample_info should be returned back, once it is no longer using the data.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to ddsi_serdata structures that contain the serialized data. The pointers can be NULL.
maxs – [in] Maximum number of samples to read.
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
handle – [in] Instance handle related to the samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_take_instance(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, dds_instance_handle_t handle)¶

Access the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition but scoped by the given instance handle.

This operation mplements the same functionality as dds_take, except that only data scoped to the provided instance handle is taken.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
bufsz – [in] The size of buffer provided.
maxs – [in] Maximum number of samples to read.
handle – [in] Instance handle related to the samples to read.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_take_instance_wl(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, dds_instance_handle_t handle)¶

Access loaned samples of data reader, readcondition or querycondition, scoped by the given instance handle.

This operation implements the same functionality as dds_take_wl, except that only data scoped to the provided instance handle is read.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
maxs – [in] Maximum number of samples to read.
handle – [in] Instance handle related to the samples to read.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_take_instance_mask(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask)¶

Take the collection of data values (of same type) and sample info from the data reader, readcondition or querycondition based on mask and scoped by the given instance handle.

This operation implements the same functionality as dds_take_mask, except that only data scoped to the provided instance handle is read.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
bufsz – [in] The size of buffer provided.
maxs – [in] Maximum number of samples to read.
handle – [in] Instance handle related to the samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>=0 – Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples read or an error code.

dds_return_t dds_take_instance_mask_wl(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask)¶

Access loaned samples of data reader, readcondition or querycondition based on mask and scoped by the given intance handle.

This operation implements the same functionality as dds_take_mask_wl, except that only data scoped to the provided instance handle is read.

Parameters

reader_or_condition – [in] Reader, readcondition or querycondition entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] Pointer to an array of dds_sample_info_t returned for each data value.
maxs – [in] Maximum number of samples to read.
handle – [in] Instance handle related to the samples to read.
mask – [in] Filter the data based on dds_sample_state_t|dds_view_state_t|dds_instance_state_t.

Return values

>= – 0 Number of samples read.
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_PRECONDITION_NOT_MET – The instance handle has not been registered with this reader.

Returns

A dds_return_t with the number of samples or an error code.

dds_return_t dds_take_next(dds_entity_t reader, void **buf, dds_sample_info_t *si)¶

Read, copy and remove the status set for the entity.

This operation copies the next, non-previously accessed data value and corresponding sample info and removes from the data reader. As an entity, only reader is accepted.

The read/take next functions return a single sample. The returned sample has a sample state of NOT_READ, a view state of ANY_VIEW_STATE and an instance state of ANY_INSTANCE_STATE.

Parameters

reader – [in] The reader entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] The pointer to dds_sample_info_t returned for a data value.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_take_next_wl(dds_entity_t reader, void **buf, dds_sample_info_t *si)¶

Read, copy and remove the status set for the entity.

This operation copies the next, non-previously accessed data value and corresponding sample info and removes from the data reader. As an entity, only reader is accepted.

The read/take next functions return a single sample. The returned sample has a sample state of NOT_READ, a view state of ANY_VIEW_STATE and an instance state of ANY_INSTANCE_STATE.

After dds_take_next_wl function is being called and the data has been handled, dds_return_loan() function must be called to possibly free memory.

Parameters

reader – [in] The reader entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] The pointer to dds_sample_info_t returned for a data value.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_read_next(dds_entity_t reader, void **buf, dds_sample_info_t *si)¶

Read and copy the status set for the entity.

This operation copies the next, non-previously accessed data value and corresponding sample info. As an entity, only reader is accepted.

The read/take next functions return a single sample. The returned sample has a sample state of NOT_READ, a view state of ANY_VIEW_STATE and an instance state of ANY_INSTANCE_STATE.

Parameters

reader – [in] The reader entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] The pointer to dds_sample_info_t returned for a data value.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_read_next_wl(dds_entity_t reader, void **buf, dds_sample_info_t *si)¶

Read and copy the status set for the loaned sample.

This operation copies the next, non-previously accessed data value and corresponding loaned sample info. As an entity, only reader is accepted.

The read/take next functions return a single sample. The returned sample has a sample state of NOT_READ, a view state of ANY_VIEW_STATE and an instance state of ANY_INSTANCE_STATE.

After dds_read_next_wl function is being called and the data has been handled, dds_return_loan() function must be called to possibly free memory.

Parameters

reader – [in] The reader entity.
buf – [out] An array of pointers to samples into which data is read (pointers can be NULL).
si – [out] The pointer to dds_sample_info_t returned for a data value.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

Subscription Data¶

group subdata

Every sample you read from DDS comes with some metadata, which you can inspect and filter on.

Typedefs

typedef enum dds_sample_state dds_sample_state_t¶: Read state for a data value

typedef enum dds_view_state dds_view_state_t¶: View state of an instance relative to the samples

typedef enum dds_instance_state dds_instance_state_t¶: Defines the state of the instance

typedef struct dds_sample_info dds_sample_info_t¶: Contains information about the associated data value

Enums

enum dds_sample_state¶

Read state for a data value

Values:

enumerator DDS_SST_READ¶: DataReader has already accessed the sample by read

enumerator DDS_SST_NOT_READ¶: DataReader has not accessed the sample before

enum dds_view_state¶

View state of an instance relative to the samples

Values:

enumerator DDS_VST_NEW¶: DataReader is accessing the sample for the first time when the instance is alive

enumerator DDS_VST_OLD¶: DataReader accessed the sample before

enum dds_instance_state¶

Defines the state of the instance

Values:

enumerator DDS_IST_ALIVE¶: Samples received for the instance from the live data writers

enumerator DDS_IST_NOT_ALIVE_DISPOSED¶: Instance was explicitly disposed by the data writer

enumerator DDS_IST_NOT_ALIVE_NO_WRITERS¶: Instance has been declared as not alive by data reader as there are no live data writers writing that instance

struct dds_sample_info¶

#include <dds.h>

Contains information about the associated data value

Public Members

dds_sample_state_t sample_state¶: Sample state

dds_view_state_t view_state¶: View state

dds_instance_state_t instance_state¶: Instance state

bool valid_data¶

Indicates whether there is a data associated with a sample

true, indicates the data is valid
false, indicates the data is invalid, no data to read

dds_time_t source_timestamp¶: timestamp of a data instance when it is written

dds_instance_handle_t instance_handle¶: handle to the data instance

dds_instance_handle_t publication_handle¶: handle to the publisher

uint32_t disposed_generation_count¶: count of instance state change from NOT_ALIVE_DISPOSED to ALIVE

uint32_t no_writers_generation_count¶: count of instance state change from NOT_ALIVE_NO_WRITERS to ALIVE

uint32_t sample_rank¶: indicates the number of samples of the same instance that follow the current one in the collection

uint32_t generation_rank¶: difference in generations between the sample and most recent sample of the same instance that appears in the returned collection

uint32_t absolute_generation_rank¶: difference in generations between the sample and most recent sample of the same instance when read/take was called