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

  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 &#8212; refers to a read condition (or query if implemented)

  Defines

  DDS_HAS_READCDR 1

    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 (Data access)

  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