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

Defines

DDS_HAS_READCDR 1

Set when function dds_has_readcdr is defined.

Typedefs

typedef dds_return_t (*dds_read_with_collector_fn_t)(void *arg, const dds_sample_info_t *si, const struct ddsi_sertype *st, struct ddsi_serdata *sd)

Function type for sample collector argument in read/take-with-collector

This defines the function type used by dds_read_with_collector and dds_take_with_collector for passing samples to be included in the result to an application defined function for collecting them in whatever way it needs. The function is called for each sample while the RHC is locked, and so it is advisable to only perform a small amount of work. Calling Cyclone DDS API functions is not supported.

It is called for the samples in the order compatible with the requirements of the DDS specification, in particular that means instances are contiguous.

Param arg

[in] A pointer to the application-defined argument passed to read/take

Param si

[in] A fully initialized sample info object

Param st

[in] The underlying ddsi_sertype (needed only if si.valid_data is false)

Param sd

[in] The sample, if si.valid_data is false, the type has been erased (hence the “st” argument)

Retval DDS_RETCODE_OK

the sample was successfully handled and reading can continue

Retval otherwise

an error, this will propagated to the caller if it occurs on the first call otherwise the return valu eof read/take will be the number of samples successfully collected

Return

An indication of success or failure

Functions

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

Read data from the data reader, read or query condition without updating state

Reads samples from the reader history cache without marking these samples as “read”. It starts with an arbitrary (matching) instance, reading (matching) samples from the oldest to the most recent, then continues with another arbitrarily selected (matching) instance, etc. This continues until it has traversed the entire history cache or has gathered maxs samples.

The dds_read operation can be used to mark the returned samples as “read”; the dds_take operation can be used to also remove the returned samples from the history cache.

For the plain dds_peek operation, all instances and samples match. This is different for the more selective variants, where the documentation refers to this function and only gives detailed information where it differs.

The buf parameter is used as follows:

• If buf[0] on entry is a null pointer:

  • on return buf[0] .. buf[k-1] will point to middleware-owned memory (a.k.a. loans); and

  • buf[k] will be a null pointer if 0 <= k < bufsz-1; and

  • 0 <= k <= maxs is the number of samples read (a.k.a. the return value).

• If buf[0] on entry is an outstanding sample loan (i.e., resulting from a previous call to, e.g., read), then:

  • all of buf[0] .. buf[k-1] must be pointers to outstanding loans; and

  • k = bufsz or buf[k] is a null pointer; where

  • 1 <= k < bufsz; and

  • all these outstanding loans are returned as-if through dds_return_loan; and

  • the result will be as if buf[0] had been a null pointer on entry.

• If buf[0] on entry is any other address, then:

  • all of buf[0] .. buf[bufsz-1] must point to memory suitable for storing samples; and

  • the C binding requires that this memory must be initialized such that all embedded strings, externals, optionals and sequences are initialized (null pointers are ok, sequences may also be all-0)

The loans returned by dds_peek operation are potentially shared copies of the data and the contents may not be modified. If a private copy is required, pass in non-null pointers to memory as in the third case above.

The si array is filled with sample information on all returned samples. If the valid_data flag is set in the sample info for a particular sample, all fields of that sample are valid. Otherwise, only the key value is valid. For the C binding, all other fields will be set to 0.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples (see above).

• 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_peek_mask(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs, uint32_t mask)

Read data matching sample/view/instance states from the data reader, read or query condition without updating state

See dds_peek. The matching criterion referred to there is that the sample/view/instance states must match the specification in the mask parameter.

If the sample/view/instance state component in the mask is 0 and reader_or_condition references a data reader (as opposed to a read or query condition), it is treated as equivalent to any sample/view/instance state. If reader_or_condition references a read or query condition, the matching states are the union of mask and the condition’s mask.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples.

• 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_peek_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)

Read data for a specific instance from the data reader, read or query condition without updating state

See dds_peek. The matching criterion referred to there is that the instance handle must equal the handle parameter.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples.

• 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_peek_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 data for a specific instance matching sample/view/instance states from the data reader, read or query condition without updating state

See dds_peek. The matching criterion referred to there is that:

• the instance handle must equal the handle parameter; and

• the sample/view/instance states must match the specification in the mask parameter.

If the sample/view/instance state component in the mask is 0 and reader_or_condition references a data reader (as opposed to a read or query condition), it is treated as equivalent to any sample/view/instance state. If reader_or_condition references a read or query condition, the matching states are the union of mask and the condition’s mask.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples.

• 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_peek_next(dds_entity_t reader, void **buf, dds_sample_info_t *si)

Read the first unread sample without updating state

Equivalent to dds_peek_mask(reader, buf, si, 1, 1, DDS_NOT_READ_SAMPLE_STATE).

Parameters

• reader – [in] The reader entity.

• buf – [inout] A pointer to a sample.

• 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(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs)

Read data from the data reader, read or query condition

Reads samples from the reader history cache, marking these samples as “read”. It starts with an arbitrary (matching) instance, reading (matching) samples from the oldest to the most recent, then continues with another arbitrarily selected (matching) instance, etc. This continues until it has traversed the entire history cache or has gathered maxs samples.

The dds_peek operation can be read samples without marking them as “read”; the dds_take operation can be used to also remove the returned samples from the history cache.

For the plain dds_read operation, all instances and samples match. This is different for the more selective variants, where the documentation refers to this function and only gives detailed information where it differs.

The buf parameter is used as follows:

• If buf[0] on entry is a null pointer:

  • on return buf[0] .. buf[k-1] will point to middleware-owned memory (a.k.a. loans); and

  • buf[k] will be a null pointer if 0 <= k < bufsz-1; and

  • 0 <= k <= maxs is the number of samples read (a.k.a. the return value).

• If buf[0] on entry is an outstanding sample loan (i.e., resulting from a previous call to, e.g., read), then:

  • all of buf[0] .. buf[k-1] must be pointers to outstanding loans; and

  • k = bufsz or buf[k] is a null pointer; where

  • 1 <= k < bufsz; and

  • all these outstanding loans are returned as-if through dds_return_loan; and

  • the result will be as if buf[0] had been a null pointer on entry.

• If buf[0] on entry is any other address, then:

  • all of buf[0] .. buf[bufsz-1] must point to memory suitable for storing samples; and

  • the C binding requires that this memory must be initialized such that all embedded strings, externals, optionals and sequences are initialized (null pointers are ok, sequences may also be all-0)

The loans returned by dds_read operation are potentially shared copies of the data and the contents may not be modified. If a private copy is required, pass in non-null pointers to memory as in the third case above.

The si array is filled with sample information on all returned samples. If the valid_data flag is set in the sample info for a particular sample, all fields of that sample are valid. Otherwise, only the key value is valid. For the C binding, all other fields will be set to 0.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples (see above).

• 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)

Read data from the data reader, read or query condition.

Deprecated:

Alias for dds_read where bufsz = maxs.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of maxs pointers to samples.

• 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 data matching sample/view/instance states from the data reader, read or query condition

See dds_read. The matching criterion referred to there is that the sample/view/instance states must match the specification in the mask parameter.

If the sample/view/instance state component in the mask is 0 and reader_or_condition references a data reader (as opposed to a read or query condition), it is treated as equivalent to any sample/view/instance state. If reader_or_condition references a read or query condition, the matching states are the union of mask and the condition’s mask.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples.

• 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)

Read data matching sample/view/instance states from the data reader, read or query condition.

Deprecated:

Alias for dds_read_mask where bufsz = maxs.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of maxs pointers to samples.

• 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)

Read data for a specific instance from the data reader, read or query condition

See dds_read. The matching criterion referred to there is that the instance handle must equal the handle parameter.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples.

• 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)

Read data for a specific instance from the data reader, read or query condition.

Deprecated:

Alias for dds_read_instance where bufsz = maxs.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of maxs pointers to samples.

• 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 data for a specific instance matching sample/view/instance states from the data reader, read or query condition

See dds_read. The matching criterion referred to there is that:

• the instance handle must equal the handle parameter; and

• the sample/view/instance states must match the specification in the mask parameter.

If the sample/view/instance state component in the mask is 0 and reader_or_condition references a data reader (as opposed to a read or query condition), it is treated as equivalent to any sample/view/instance state. If reader_or_condition references a read or query condition, the matching states are the union of mask and the condition’s mask.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples.

• 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)

Read data for a specific instance matching sample/view/instance states from the data reader, read or query condition.

Deprecated:

Alias for dds_read_instance_mask where bufsz = maxs.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of maxs pointers to samples.

• 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_read_next(dds_entity_t reader, void **buf, dds_sample_info_t *si)

Read the first unread sample

Equivalent to dds_read_mask(reader, buf, si, 1, 1, DDS_NOT_READ_SAMPLE_STATE).

Parameters

• reader – [in] The reader entity.

• buf – [inout] A pointer to a sample.

• 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 the first unread sample.

Deprecated:

Alias for dds_read_next.

Parameters

• reader – [in] The reader entity.

• buf – [inout] A pointer to a sample.

• 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(dds_entity_t reader_or_condition, void **buf, dds_sample_info_t *si, size_t bufsz, uint32_t maxs)

Take data from the data reader, read or query condition

Reads and removes samples from the reader history cache. It starts with an arbitrary (matching) instance, reading (matching) samples from the oldest to the most recent, then continues with another arbitrarily selected (matching) instance, etc. This continues until it has traversed the entire history cache or has gathered maxs samples.

The dds_read operation can be used to read samples without removing them from the history cache but marking them as “read”; the dds_peek operation can be used to read samples from the cache without changing any internal state.

For the plain dds_take operation, all instances and samples match. This is different for the more selective variants, where the documentation refers to this function and only gives detailed information where it differs.

The buf parameter is used as follows:

• If buf[0] on entry is a null pointer:

  • on return buf[0] .. buf[k-1] will point to middleware-owned memory (a.k.a. loans); and

  • buf[k] will be a null pointer if 0 <= k < bufsz-1; and

  • 0 <= k <= maxs is the number of samples read (a.k.a. the return value).

• If buf[0] on entry is an outstanding sample loan (i.e., resulting from a previous call to, e.g., read), then:

  • all of buf[0] .. buf[k-1] must be pointers to outstanding loans; and

  • k = bufsz or buf[k] is a null pointer; where

  • 1 <= k < bufsz; and

  • all these outstanding loans are returned as-if through dds_return_loan; and

  • the result will be as if buf[0] had been a null pointer on entry.

• If buf[0] on entry is any other address, then:

  • all of buf[0] .. buf[bufsz-1] must point to memory suitable for storing samples; and

  • the C binding requires that this memory must be initialized such that all embedded strings, externals, optionals and sequences are initialized (null pointers are ok, sequences may also be all-0)

The loans returned by dds_take operation are potentially shared copies of the data and the contents may not be modified. If a private copy is required, pass in non-null pointers to memory as in the third case above.

The si array is filled with sample information on all returned samples. If the valid_data flag is set in the sample info for a particular sample, all fields of that sample are valid. Otherwise, only the key value is valid. For the C binding, all other fields will be set to 0.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples (see above).

• 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)

Take data from the data reader, read or query condition.

Deprecated:

Alias for dds_take where bufsz = maxs.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of maxs pointers to samples.

• 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 data matching sample/view/instance states from the data reader, read or query condition

See dds_take. The matching criterion referred to there is that the sample/view/instance states must match the specification in the mask parameter.

If the sample/view/instance state component in the mask is 0 and reader_or_condition references a data reader (as opposed to a read or query condition), it is treated as equivalent to any sample/view/instance state. If reader_or_condition references a read or query condition, the matching states are the union of mask and the condition’s mask.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples.

• 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)

Take data matching sample/view/instance states from the data reader, read or query condition.

Deprecated:

Alias for dds_take_mask where bufsz = maxs.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of maxs pointers to samples.

• 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_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)

Take data for a specific instance from the data reader, read or query condition

See dds_take. The matching criterion referred to there is that the instance handle must equal the handle parameter.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples.

• 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)

Take data for a specific instance from the data reader, read or query condition.

Deprecated:

Alias for dds_take_instance where bufsz = maxs.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of maxs pointers to samples.

• 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 data for a specific instance matching sample/view/instance states from the data reader, read or query condition

See dds_take. The matching criterion referred to there is that:

• the instance handle must equal the handle parameter; and

• the sample/view/instance states must match the specification in the mask parameter.

If the sample/view/instance state component in the mask is 0 and reader_or_condition references a data reader (as opposed to a read or query condition), it is treated as equivalent to any sample/view/instance state. If reader_or_condition references a read or query condition, the matching states are the union of mask and the condition’s mask.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of bufsz pointers to samples.

• 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)

Take data for a specific instance matching sample/view/instance states from the data reader, read or query condition.

Deprecated:

Alias for dds_take_instance_mask where bufsz = maxs.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [inout] An array of maxs pointers to samples.

• 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)

Take the first unread sample

Equivalent to dds_take_mask(reader, buf, si, 1, 1, DDS_NOT_READ_SAMPLE_STATE).

Parameters

• reader – [in] The reader entity.

• buf – [inout] A pointer to a sample.

• 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)

Take the first unread sample.

Deprecated:

Alias for dds_take_next.

Parameters

• reader – [in] The reader entity.

• buf – [inout] A pointer to a sample.

• 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_peek_with_collector(dds_entity_t reader_or_condition, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask, dds_read_with_collector_fn_t collect_sample, void *collect_sample_arg)

Read samples while collecting result in an application-defined way without updating state

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

If the sample/view/instance state component in the mask is 0 and there is no read or query condition, to combine it with, it is treated as equivalent to any sample/view/instance state.

Collected samples are not marked as read.

Parameters

• reader_or_condition – [in] Handle of a reader or a read/query condition

• maxs – [in] Maximum number of samples (1 .. INT32_MAX)

• handle – [in] Instance handle or 0 if not reading a specific instance

• mask – [in] Sample/view/instance state mask

• collect_sample – [in] Function be called for each sample in the result

• collect_sample_arg – [in] Arbitrary argument passed to “collect_sample”

Return values

• > – 0 number of samples passed successfully collected by collect_sample

• 0 – success, no matching data

• 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.

• < – 0 Return value of failing collect_sample on first invocation

Returns

The number of returned samples or an error code

dds_return_t dds_read_with_collector(dds_entity_t reader_or_condition, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask, dds_read_with_collector_fn_t collect_sample, void *collect_sample_arg)

Read samples while collecting result in an application-defined way

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

If the sample/view/instance state component in the mask is 0 and there is no read or query condition, to combine it with, it is treated as equivalent to any sample/view/instance state.

Collected samples are marked as read.

Parameters

• reader_or_condition – [in] Handle of a reader or a read/query condition

• maxs – [in] Maximum number of samples (1 .. INT32_MAX)

• handle – [in] Instance handle or 0 if not reading a specific instance

• mask – [in] Sample/view/instance state mask

• collect_sample – [in] Function be called for each sample in the result

• collect_sample_arg – [in] Arbitrary argument passed to “collect_sample”

Return values

• > – 0 number of samples passed successfully collected by collect_sample

• 0 – success, no matching data

• 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.

• < – 0 Return value of failing collect_sample on first invocation

Returns

The number of returned samples or an error code

dds_return_t dds_take_with_collector(dds_entity_t reader_or_condition, uint32_t maxs, dds_instance_handle_t handle, uint32_t mask, dds_read_with_collector_fn_t collect_sample, void *collect_sample_arg)

Take samples while collecting result in an application-defined way

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

If the sample/view/instance state component in the mask is 0 and there is no read or query condition, to combine it with, it is treated as equivalent to any sample/view/instance state.

Collected samples are removed from the history cache.

Parameters

• reader_or_condition – [in] Handle of a reader or a read/query condition

• maxs – [in] Maximum number of samples (1 .. INT32_MAX)

• handle – [in] Instance handle or 0 if not taking from a specific instance

• mask – [in] Sample/view/instance state mask

• collect_sample – [in] Function be called for each sample in the result

• collect_sample_arg – [in] Arbitrary argument passed to “collect_sample”

Return values

• > – 0 number of samples passed successfully collected by collect_sample

• 0 – success, no matching data

• 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.

• < – 0 Return value of failing collect_sample on first invocation

Returns

The number of returned samples or an error code

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

Get references to a representation of the samples in a reader history cache and their accompanying sample infodata values (of same type) without updating state

This operation returns references to the internal representation of samples (struct ddsi_serdata), which can then be used in a variety of ways. Examples are converting it to application representation and obtaining a copy or a reference of the serialized representation. If the underlying implementation (struct ddsi_sertype) is known to the application, other options may exist as well.

The data is left in the reader history cache and the sample state and view state of the returned samples and their instances are not updated; dds_readcdr updates these states; dds_takecdr removes the data from the history cache.

The returned references must eventually be released by calling ddsi_serdata_unref. There is no guarantee the type pointer survives beyond the existence of the reader from which the references were read.

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

If the sample/view/instance state component in the mask is 0 and there is no read or query condition, to combine it with, it is treated as equivalent to any sample/view/instance state.

Note that this is a simple wrapper around dds_peek_with_collector.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [out] Filled with references ddsi_serdata structures.

• maxs – [in] Maximum number of samples to read.

• si – [out] Filled with sample info.

• 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_peekcdr_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)

Get references to a representation of the samples of a specific instance in a reader history cache and their accompanying sample infodata values (of same type) without updating state

This operation returns references to the internal representation of samples (struct ddsi_serdata), which can then be used in a variety of ways. Examples are converting it to application representation and obtaining a copy or a reference of the serialized representation. If the underlying implementation (struct ddsi_sertype) is known to the application, other options may exist as well.

The data is left in the reader history cache and the sample state and view state of the returned samples and their instances are not updated; dds_readcdr updates these states; dds_takecdr removes the data from the history cache.

The returned references must eventually be released by calling ddsi_serdata_unref. There is no guarantee the type pointer survives beyond the existence of the reader from which the references were read.

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

If the sample/view/instance state component in the mask is 0 and there is no read or query condition, to combine it with, it is treated as equivalent to any sample/view/instance state.

Note that this is a simple wrapper around dds_peek_with_collector.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [out] Filled with references ddsi_serdata structures.

• maxs – [in] Maximum number of samples to read.

• si – [out] Filled with sample info.

• handle – [in] Handle of instance from which to read samples.

• 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_readcdr(dds_entity_t reader_or_condition, struct ddsi_serdata **buf, uint32_t maxs, dds_sample_info_t *si, uint32_t mask)

Get references to a representation of the samples in a reader history cache and their accompanying sample infodata values (of same type) and marking them as read

This operation returns references to the internal representation of samples (struct ddsi_serdata), which can then be used in a variety of ways. Examples are converting it to application representation and obtaining a copy or a reference of the serialized representation. If the underlying implementation (struct ddsi_sertype) is known to the application, other options may exist as well.

The data is left in the reader history cache and the sample state and view state of the returned samples and their instances are updated; dds_peekcdr returns the data without updating these states; dds_takecdr removes the data from the history cache.

The returned references must eventually be released by calling ddsi_serdata_unref. There is no guarantee the type pointer survives beyond the existence of the reader from which the references were read.

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

If the sample/view/instance state component in the mask is 0 and there is no read or query condition, to combine it with, it is treated as equivalent to any sample/view/instance state.

Note that this is a simple wrapper around dds_read_with_collector.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [out] Filled with references ddsi_serdata structures.

• maxs – [in] Maximum number of samples to read.

• si – [out] Filled with sample info.

• 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)

Get references to a representation of the samples of a specific instance in a reader history cache and their accompanying sample infodata values (of same type) and marking them as read

This operation returns references to the internal representation of samples (struct ddsi_serdata), which can then be used in a variety of ways. Examples are converting it to application representation and obtaining a copy or a reference of the serialized representation. If the underlying implementation (struct ddsi_sertype) is known to the application, other options may exist as well.

The data is left in the reader history cache and the sample state and view state of the returned samples and their instances are updated; dds_peekcdr returns the data without updating these states; dds_takecdr removes the data from the history cache.

The returned references must eventually be released by calling ddsi_serdata_unref. There is no guarantee the type pointer survives beyond the existence of the reader from which the references were read.

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

If the sample/view/instance state component in the mask is 0 and there is no read or query condition, to combine it with, it is treated as equivalent to any sample/view/instance state.

Note that this is a simple wrapper around dds_read_with_collector.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [out] Filled with references ddsi_serdata structures.

• maxs – [in] Maximum number of samples to read.

• si – [out] Filled with sample info.

• handle – [in] Handle of instance from which to read samples.

• 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)

Get references to a representation of the samples in a reader history cache and their accompanying sample infodata values (of same type) and remove them from the cache

This operation returns references to the internal representation of samples (struct ddsi_serdata), which can then be used in a variety of ways. Examples are converting it to application representation and obtaining a copy or a reference of the serialized representation. If the underlying implementation (struct ddsi_sertype) is known to the application, other options may exist as well.

The data is removed from the reader history cache; dds_peekcdr leaves them in and leaves the sample and view states unchanged; dds_readcdr leaves the data in the cache but does update the sample and view states.

The returned references must eventually be released by calling ddsi_serdata_unref. There is no guarantee the type pointer survives beyond the existence of the reader from which the references were read.

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

If the sample/view/instance state component in the mask is 0 and there is no read or query condition, to combine it with, it is treated as equivalent to any sample/view/instance state.

Note that this is a simple wrapper around dds_take_with_collector.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [out] Filled with references ddsi_serdata structures.

• maxs – [in] Maximum number of samples to read.

• si – [out] Filled with sample info.

• 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)

Get references to a representation of the samples of a specific instance in a reader history cache and their accompanying sample infodata values (of same type) and remove them from the cache

This operation returns references to the internal representation of samples (struct ddsi_serdata), which can then be used in a variety of ways. Examples are converting it to application representation and obtaining a copy or a reference of the serialized representation. If the underlying implementation (struct ddsi_sertype) is known to the application, other options may exist as well.

The data is removed from the reader history cache; dds_peekcdr leaves them in and leaves the sample and view states unchanged; dds_readcdr leaves the data in the cache but does update the sample and view states.

The returned references must eventually be released by calling ddsi_serdata_unref. There is no guarantee the type pointer survives beyond the existence of the reader from which the references were read.

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

If the sample/view/instance state component in the mask is 0 and there is no read or query condition, to combine it with, it is treated as equivalent to any sample/view/instance state.

Note that this is a simple wrapper around dds_take_with_collector.

Parameters

• reader_or_condition – [in] Reader, readcondition or querycondition entity.

• buf – [out] Filled with references ddsi_serdata structures.

• maxs – [in] Maximum number of samples to read.

• si – [out] Filled with sample info.

• handle – [in] Handle of instance from which to read samples.

• 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_reader_store_loaned_sample (dds_entity_t reader, dds_loaned_sample_t *data) ddsrt_nonnull_all

insert data from a loaned sample into the reader history cache

Parameters

• reader – [in] The reader entity.

• data – [in] Pointer to the loaned sample of the entity received

Return values

• DDS_RETCODE_OK – The operation was successful.

• DDS_RETCODE_BAD_PARAMETER – One or more parameters are invalid.

• DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

• DDS_RETCODE_ALREADY_DELETED – The reader 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