CoreDX DDS C Reference Manual
Related Functions | List of all members
DDS_DataReader Struct Reference

The DDS_DataReader entity allows the application to subscribe to and read data. More...

Related Functions

(Note that these are not member functions.)

DDS_ReturnCode_t DDS_DataReader_enable (DDS_DataReader dr)
 Enables the DDS_DataReader. More...
 
DDS_InstanceHandle_t DDS_DataReader_get_instance_handle (DDS_DataReader dr)
 This operation returns the InstanceHandle_t that identifies the DataReader.
 
DDS_StatusMask DDS_DataReader_get_status_changes (DDS_DataReader dr)
 This returns the list of triggered communication statuses in the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_delete_contained_entities (DDS_DataReader dr)
 This operation deletes all the ReadCondition and QueryCondition objects previously created by means of the DDS_DataReader_create_readcondition() and DDS_DataReader_create_querycondition() operations. More...
 
DDS_ReturnCode_t DDS_DataReader_set_qos (DDS_DataReader dr, const DDS_DataReaderQos *qos)
 Sets the DDS_DataReaderQos values. More...
 
DDS_ReturnCode_t DDS_DataReader_get_qos (DDS_DataReader dr, DDS_DataReaderQos *qos)
 Returns the current DDS_DataReaderQos settings held in the DataReader dr. More...
 
DDS_ReturnCode_t DDS_DataReader_set_listener (DDS_DataReader dr, DDS_DataReaderListener *a_listener, DDS_StatusMask mask)
 Installs a DDS_DataReaderListener on DataReader dr. More...
 
DDS_ReturnCode_t DDS_DataReader_set_listener_cd (DDS_DataReader dr, DDS_DataReaderListener_cd *a_listener, DDS_StatusMask mask, void *callback_data)
 Installs a DDS_DataReaderListener_cd on DataReader dr. More...
 
DDS_DataReaderListenerDDS_DataReader_get_listener (DDS_DataReader dr)
 This operation returns the currently installed DDS_DataReaderListener. More...
 
DDS_DataReaderListener_cdDDS_DataReader_get_listener_cd (DDS_DataReader dr)
 This operation returns the currently installed DDS_DataReaderListener_cd. More...
 
DDS_TopicDescription DDS_DataReader_get_topicdescription (DDS_DataReader dr)
 Returns the DDS_TopicDescription associated with DataReader dr. More...
 
DDS_Subscriber DDS_DataReader_get_subscriber (DDS_DataReader dr)
 Returns the DDS_Subscribier that contains DataReader dr.
 
DDS_ReturnCode_t DDS_DataReader_wait_for_historical_data (DDS_DataReader dr, const DDS_Duration_t *max_wait)
 This routine blocks until all 'historical' data is received.
 
DDS_StatusCondition DDS_DataReader_get_statuscondition (DDS_DataReader dr)
 This operation allows access to the DDS_StatusCondition associated with the DataReader. More...
 
DDS_ReadCondition DDS_DataReader_create_readcondition (DDS_DataReader dr, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 Creates a DDS_ReadCondition that is associated with this DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_delete_readcondition (DDS_DataReader dr, DDS_ReadCondition a_condition)
 Destroys a DDS_ReadCondition (or DDS_QueryCondition). More...
 
DDS_QueryCondition DDS_DataReader_create_querycondition (DDS_DataReader dr, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states, const char *query_expression, const DDS_StringSeq *query_parameters)
 Creates a DDS_QueryCondition. More...
 
DDS_ReturnCode_t DDS_DataReader_get_matched_publications (DDS_DataReader dr, DDS_InstanceHandleSeq *publication_handles)
 This operation retrieves the list of DataWriters currently matched with the DataReader dr. More...
 
DDS_ReturnCode_t DDS_DataReader_get_matched_publication_data (DDS_DataReader dr, DDS_PublicationBuiltinTopicData *publication_data, const DDS_InstanceHandle_t publication_handle)
 This operation returns data that describes a particular matched DataWriter identified by publication_handle. More...
 
DDS_ReturnCode_t DDS_DataReader_return_loan (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos)
 Returns data and sample_info values to a DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_sample_rejected_status (DDS_DataReader dr, DDS_SampleRejectedStatus *status)
 Provides access to the current DDS_SampleRejectedStatus of the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_liveliness_changed_status (DDS_DataReader dr, DDS_LivelinessChangedStatus *status)
 Provides access to the current DDS_LivelinessChangedStatus of the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_requested_deadline_missed_status (DDS_DataReader dr, DDS_RequestedDeadlineMissedStatus *status)
 Provides access to the current DDS_RequestedDeadlineMissedStatus of the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_requested_incompatible_qos_status (DDS_DataReader dr, DDS_RequestedIncompatibleQosStatus *status)
 Provides access to the current DDS_RequestedIncompatibleQosStatus of the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status (DDS_DataReader dr, DDS_SubscriptionMatchedStatus *status)
 Provides access to the current DDS_SubscriptionMatchedStatus of the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_sample_lost_status (DDS_DataReader dr, DDS_SampleLostStatus *status)
 Provides access to the current DDS_SampleLostStatus of the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_guid (DDS_DataReader dr, DDS_GUID_t *guid)
 Access the GUID which uniquely identifies this reader.
 
DDS_ReturnCode_t DDS_DataReader_get_cache_stats (DDS_DataReader dr, DDS_CacheStatistics *stats)
 Provides access to the current cache statistics of the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_get_key_value (DDS_DataReader dr, void *key_holder, DDS_InstanceHandle_t handle)
 This routine will populate the data structure indicated by key_holder with the key infomation identified by handle. More...
 
DDS_InstanceHandle_t DDS_DataReader_lookup_instance (DDS_DataReader dr, void *instance_data)
 Returns the handle that identifies the data instance provided in instance_data. More...
 
DDS_ReturnCode_t DDS_DataReader_read (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 This operation accesses a collection of data values (with associated DDS_SampleInfo) within the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_take (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 This operation takes a collection of data values (with associated DDS_SampleInfo) from the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_read_w_condition (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_ReadCondition a_condition)
 This operation accesses a collection of data values (with associated DDS_SampleInfo), subject to a filter, within the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_take_w_condition (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_ReadCondition a_condition)
 This operation takes a collection of data values (with associated DDS_SampleInfo), subject to a filter, from the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_read_next_sample (DDS_DataReader dr, void *received_data, DDS_SampleInfo *sample_info)
 This operation accesses a data value (with associated DDS_SampleInfo) within the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_take_next_sample (DDS_DataReader dr, void *received_data, DDS_SampleInfo *sample_info)
 This operation takes a data value (with associated DDS_SampleInfo) from the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_read_instance (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_InstanceHandle_t a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 This operation accesses a collection of data values (with associated DDS_SampleInfo), belonging to a particular instance, within the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_take_instance (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_InstanceHandle_t a_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 This operation takes a collection of data values (with associated DDS_SampleInfo), belonging to a particular instance, from the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_read_next_instance (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_InstanceHandle_t previous_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 This operation accesses a collection of data values (with associated DDS_SampleInfo), instance by instance, within the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_take_next_instance (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_InstanceHandle_t previous_handle, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
 This operation takes a collection of data values (with associated DDS_SampleInfo), instance by instance, from the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_read_next_instance_w_condition (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_InstanceHandle_t previous_handle, DDS_ReadCondition a_condition)
 This operation accesses a collection of data values (with associated DDS_SampleInfo), instance by instance subject to a filter, within the DataReader. More...
 
DDS_ReturnCode_t DDS_DataReader_take_next_instance_w_condition (DDS_DataReader dr, DDS_PointerSeq *received_data, DDS_SampleInfoSeq *sample_infos, int32_t max_samples, DDS_InstanceHandle_t previous_handle, DDS_ReadCondition a_condition)
 This operation takes a collection of data values (with associated DDS_SampleInfo), instance by instance subject to a filter, from the DataReader. More...
 

Detailed Description

The DDS_DataReader entity allows the application to subscribe to and read data.

The DataReadre is an abstract 'class' that is extended to support a particular data type required by the application. A DataReader is associated with a single TopicDescription (Topic, MultiTopic, or ContentFilteredTopic).

Friends And Related Function Documentation

DDS_QueryCondition DDS_DataReader_create_querycondition ( DDS_DataReader  dr,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states,
const char *  query_expression,
const DDS_StringSeq *  query_parameters 
)
related

Creates a DDS_QueryCondition.

The returned QueryCondition can be used as an argument to read_w_condition() or take_w_condition().

The query_expression is an SQL like condition expression, and query_parameters provide optional parameters that are referenced by the query_expression. The syntax of the query expression is similar to the WHERE clause in SQL. For example "x<4" is a valid query expression. It would test that data member 'x' is less than value '4'. If the query expression evaluates to TRUE, then the data sample will be available, otherwise the data sample will be 'filtered' (excluded).

CoreDX DDS supports the 'LIKE' operator (and NOT LIKE) for regular expression string matching. The pattern string in a LIKE clause can contain '' to match zero or more characters, '_' to match a single character, or '[<characters>]' to match a range of characters.

CoreDX DDS also includes support for the 'IN' operator. This provides a very powerful mechanism for testing that a value appears in a set of values. For example "symbol IN ('ge', 'msft', 'ibm')" will select all samples that have a symbol value of 'ge', 'msft', or 'ibm'. This could also be written as a series of equality tests combined with the OR operator; however, the IN operator is much more efficient. A query that matches on several hundred or even thousands of values can be implemented very efficiently using the 'IN' operator.

The query_expression can refer to parameters. The syntax for paramters is the percent sign '' followed by a number. The number is the index of the paramter in the query_paramters sequence. Parameters are counted starting at zero. So, "%0" refers to the first parameter, and "%4" refers to the fifth paramter. Using this syntax, the expression "x<%0" would test the value of 'x' against the first parameter in the sequence.

See also
DDS_QueryCondition
DDS_DataReader_read_w_condition()
DDS_DataReader_take_w_condition()
DDS_ReadCondition DDS_DataReader_create_readcondition ( DDS_DataReader  dr,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)
related

Creates a DDS_ReadCondition that is associated with this DataReader.

The returned condition can be added to a DDS_WaitSet or used in a call to the specialized read() or take() operations. For example see DDS_DataReader_read_w_condition().

DDS_ReturnCode_t DDS_DataReader_delete_contained_entities ( DDS_DataReader  dr)
related

This operation deletes all the ReadCondition and QueryCondition objects previously created by means of the DDS_DataReader_create_readcondition() and DDS_DataReader_create_querycondition() operations.

After successful execution, the application may delete the Publisher by calling DDS_Subscriber_delete_datareader().

If any of the objects cannot be deleted, this routine will return DDS_RETCODE_PRECONDITION_NOT_MET.

DDS_ReturnCode_t DDS_DataReader_delete_readcondition ( DDS_DataReader  dr,
DDS_ReadCondition  a_condition 
)
related

Destroys a DDS_ReadCondition (or DDS_QueryCondition).

The provided a_condition must have been previously created via a call to DDS_DataReader_create_readcondition() or DDS_DataReader_create_querycondition().

The a_condition argument must belong to DataReader dr. Otherwise, the error DDS_RETCODE_PRECONDITION_NOT_MET will be returned.

If the DataReader is actively processing the ReadCondition, this routine will return DDS_RETCODE_ERROR; in this case, the delete_readcondition() call should be re-tried.

DDS_ReturnCode_t DDS_DataReader_enable ( DDS_DataReader  dr)
related

Enables the DDS_DataReader.

A DataReader is created either enabled or not based on the DDS_SubscriberQos setting entity_factory. When a DataReader is not enabled, only the following sub-set of all DataReader operations are legal:

  • operations to get and set QoS policies,
  • get_statuscondition(),
  • get_status_changes(),

Any other operation may return the DDS_NOT_ENABLED error. DDS_DataReader_enable() may be called on an already enabled DataReader [it will have no effect].

DDS_ReturnCode_t DDS_DataReader_get_cache_stats ( DDS_DataReader  dr,
DDS_CacheStatistics stats 
)
related

Provides access to the current cache statistics of the DataReader.

This routine will populate 'stats' with the current statistics.

DDS_ReturnCode_t DDS_DataReader_get_key_value ( DDS_DataReader  dr,
void *  key_holder,
DDS_InstanceHandle_t  handle 
)
related

This routine will populate the data structure indicated by key_holder with the key infomation identified by handle.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
DDS_DataReaderListener * DDS_DataReader_get_listener ( DDS_DataReader  dr)
related

This operation returns the currently installed DDS_DataReaderListener.

Note
Because the infrastructure makes a copy of the listener provided in DDS_DataReader_set_listener(), the returned structure pointer will not match the pointer originally provided. However, the function pointers within the structure will match. Also, the application should not free the data referenced by the returned pointer.
DDS_DataReaderListener_cd * DDS_DataReader_get_listener_cd ( DDS_DataReader  dr)
related

This operation returns the currently installed DDS_DataReaderListener_cd.

Note
Because the infrastructure holds a pointer to the listener provided in DDS_DataReader_set_listener(), the returned structure pointer will match the pointer originally provided. The application should not free the data referenced by the returned pointer.
DDS_ReturnCode_t DDS_DataReader_get_liveliness_changed_status ( DDS_DataReader  dr,
DDS_LivelinessChangedStatus status 
)
related

Provides access to the current DDS_LivelinessChangedStatus of the DataReader.

As a side-effect, this routine will reset the total_count_change status field to zero.

DDS_ReturnCode_t DDS_DataReader_get_matched_publication_data ( DDS_DataReader  dr,
DDS_PublicationBuiltinTopicData publication_data,
const DDS_InstanceHandle_t  publication_handle 
)
related

This operation returns data that describes a particular matched DataWriter identified by publication_handle.

An appropriate handle can be obtained through a call to DDS_DataReader_get_matched_publications().

If publication_handle does not identify a matched DataWriter, this routine will return DDS_RETCODE_PRECONDITION_NOT_MET. To reclaim any memory returned in the 'publication_data' parameter, call DDS_DCPSPublication_clear(publication_data).

DDS_ReturnCode_t DDS_DataReader_get_matched_publications ( DDS_DataReader  dr,
DDS_InstanceHandleSeq *  publication_handles 
)
related

This operation retrieves the list of DataWriters currently matched with the DataReader dr.

This list will include the handles that identify DataWriters which have matching Topic and compatible QoS with DataReader.

If a DataWriter has been ignored by a call to DDS_DomainParticipant_ignore_publication(), then it will not appear in the list.

DDS_ReturnCode_t DDS_DataReader_get_qos ( DDS_DataReader  dr,
DDS_DataReaderQos qos 
)
related

Returns the current DDS_DataReaderQos settings held in the DataReader dr.

This routines copies data from the DataReader QoS properties into qos.

Note
The qos structure may contain sequences or strings that are populated with dynamic memory. The caller is responsible for freeing the dynamic memory of these items.
For example, the sequence 'qos->user_data' may have dynamically allocated memory assigned. This can be released by a call to seq_clear(&qos->user_data).
DDS_ReturnCode_t DDS_DataReader_get_requested_deadline_missed_status ( DDS_DataReader  dr,
DDS_RequestedDeadlineMissedStatus status 
)
related

Provides access to the current DDS_RequestedDeadlineMissedStatus of the DataReader.

As a side-effect, this routine will reset the total_count_change status field to zero.

DDS_ReturnCode_t DDS_DataReader_get_requested_incompatible_qos_status ( DDS_DataReader  dr,
DDS_RequestedIncompatibleQosStatus status 
)
related

Provides access to the current DDS_RequestedIncompatibleQosStatus of the DataReader.

As a side-effect, this routine will reset the total_count_change status field to zero.

DDS_ReturnCode_t DDS_DataReader_get_sample_lost_status ( DDS_DataReader  dr,
DDS_SampleLostStatus status 
)
related

Provides access to the current DDS_SampleLostStatus of the DataReader.

As a side-effect, this routine will reset the total_count_change status field to zero.

DDS_ReturnCode_t DDS_DataReader_get_sample_rejected_status ( DDS_DataReader  dr,
DDS_SampleRejectedStatus status 
)
related

Provides access to the current DDS_SampleRejectedStatus of the DataReader.

As a side-effect, this routine will reset the total_count_change status field to zero.

DDS_StatusMask DDS_DataReader_get_status_changes ( DDS_DataReader  dr)
related

This returns the list of triggered communication statuses in the DataReader.

If the DataReader is not enabled, all statuses will be untriggered.

DDS_StatusCondition DDS_DataReader_get_statuscondition ( DDS_DataReader  dr)
related

This operation allows access to the DDS_StatusCondition associated with the DataReader.

The returned condition can be added to a DDS_WaitSet.

DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status ( DDS_DataReader  dr,
DDS_SubscriptionMatchedStatus status 
)
related

Provides access to the current DDS_SubscriptionMatchedStatus of the DataReader.

As a side-effect, this routine will reset the total_count_change status field to zero.

DDS_TopicDescription DDS_DataReader_get_topicdescription ( DDS_DataReader  dr)
related

Returns the DDS_TopicDescription associated with DataReader dr.

The returned TopicDescription is really a DDS_Topic, DDS_ContentFilteredTopic or DDS_MultiTopic.

DDS_InstanceHandle_t DDS_DataReader_lookup_instance ( DDS_DataReader  dr,
void *  instance_data 
)
related

Returns the handle that identifies the data instance provided in instance_data.

The 'key' field values of the data are associated with a unique handle.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
DDS_ReturnCode_t DDS_DataReader_read ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)
related

This operation accesses a collection of data values (with associated DDS_SampleInfo) within the DataReader.

This routine, and the related take(), provide the interface for an application to access published data. There are several varieties of read() and take(), to facilitate different access patterns or approaches.

The primary difference between read() and take() is that take() removes all returned data samples from the DataReader while read() does not. Sequential read() calls will return the same data samples each time (if nothing else changes); while sequential take() calls will return data samples for only the first call. Subsequent take() calls will return an empty collection (if no new data arrives).

The specific behavior of read() depends on several things: input paramters, the QoS settings of the DataReader, and the state of recieved data. First, the received_data and sample_infos arguments affect the following:

  • how many samples are returned, and
  • whether the returned data should be 'loaned' or copied.

The argument max_samples is used to further limit the number of samples returned.

The sample_states, view_states, and instance_states arguments are used to selectively add data samples to the returned collections. These arguments indicate the desired 'states' for data samples and instances. These state arguments are bit masks; they can be the bit-wise OR of several individual state flags or they may use the special 'ANY' constants (e.g.: DDS_ANY_SAMPLE_STATE). Only samples that have a matching state for all three categories are added to the returned collection.

The order of samples in the returned collections is determined by the PRESENTATION and DESTINATION_ORDER QoS policies.

The returned collection is held in recieved_data and samples_infos. These two sequences operate together to represent a sequence of pairs (data, SampleInfo). Each data item in received_data has a corresponding entry in sample_infos that provides associated 'meta-data'. See DDS_SampleInfo for a description of this meta-data.

In CoreDX DDS, the returned sequences contain 'loaned' data. This provides zero-copy access to the data, and provides a very efficient data access mechanism. Becuase the data is 'loaned' to the application, the application is required to indicate when it is finished accessing the data. This is accomplished by calling DDS_DataReader_return_loan().

The read() operation will set the DDS_SampleInfo::sample_state to DDS_READ_SAMPLE_STATE.

The read() operation may set the DDS_SampleInfo::view_state to DDS_NOT_NEW_VIEW_STATE, if a sample of the most recent generation of the instance is read.

If there is no data found, then the read() will return DDS_RETCODE_NO_DATA.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
DDS_ReturnCode_t DDS_DataReader_read_instance ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_InstanceHandle_t  a_handle,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)
related

This operation accesses a collection of data values (with associated DDS_SampleInfo), belonging to a particular instance, within the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_read()
DDS_ReturnCode_t DDS_DataReader_read_next_instance ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_InstanceHandle_t  previous_handle,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)
related

This operation accesses a collection of data values (with associated DDS_SampleInfo), instance by instance, within the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_read()
DDS_ReturnCode_t DDS_DataReader_read_next_instance_w_condition ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_InstanceHandle_t  previous_handle,
DDS_ReadCondition  a_condition 
)
related

This operation accesses a collection of data values (with associated DDS_SampleInfo), instance by instance subject to a filter, within the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_read()
DDS_ReturnCode_t DDS_DataReader_read_next_sample ( DDS_DataReader  dr,
void *  received_data,
DDS_SampleInfo sample_info 
)
related

This operation accesses a data value (with associated DDS_SampleInfo) within the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_read()
DDS_ReturnCode_t DDS_DataReader_read_w_condition ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_ReadCondition  a_condition 
)
related

This operation accesses a collection of data values (with associated DDS_SampleInfo), subject to a filter, within the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_read()
DDS_ReturnCode_t DDS_DataReader_return_loan ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos 
)
related

Returns data and sample_info values to a DataReader.

When an application calls DataReader read() or take() operations, these routines may 'loan' data and DDS_SampleInfo values to the application. [This is an optimization that avoids extra copies of data.] The appliction must return this 'loaned' data to the DataReader. The return_loan() routine indicates to the DataReader that the application no longer requires access to the data and sample_infos.

A call to return_loan() operation must be called only if previous read() or take() calls 'loaned' data to the application. See DDS_DataReader_read() for a discussion of when data is 'loaned'.

If the received_data or sample_infos parameters provided do not identify data obtained from DataReader dr, then the error DDS_RETCODE_PRECONDITION_NOT_MET will be returned.

Note

A DataReader cannot be deleted if any 'loans' are outstanding.

DDS_ReturnCode_t DDS_DataReader_set_listener ( DDS_DataReader  dr,
DDS_DataReaderListener a_listener,
DDS_StatusMask  mask 
)
related

Installs a DDS_DataReaderListener on DataReader dr.

Only one listener may be attached to a DataReader at a time. A call to set_listener() will replace any current listener with a_listener.

a_listener can be NULL, which indicates a listener that does nothing.

The infrastructure will make an internal copy of the listener structure so that it need not be persisted by the application.

DDS_ReturnCode_t DDS_DataReader_set_listener_cd ( DDS_DataReader  dr,
DDS_DataReaderListener_cd a_listener,
DDS_StatusMask  mask,
void *  callback_data 
)
related

Installs a DDS_DataReaderListener_cd on DataReader dr.

Only one listener may be attached to a DataReader at a time. A call to set_listener_cd() will replace any current listener with a_listener.

a_listener can be NULL, which indicates a listener that does nothing.

The infrastructure will not hold a pointer to the listener structure which means that it must be persisted by the application.

DDS_ReturnCode_t DDS_DataReader_set_qos ( DDS_DataReader  dr,
const DDS_DataReaderQos qos 
)
related

Sets the DDS_DataReaderQos values.

These QoS values affect the behavior of the DDS_DataReader.

DDS_ReturnCode_t DDS_DataReader_take ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)
related

This operation takes a collection of data values (with associated DDS_SampleInfo) from the DataReader.

This routine, and the related read(), provide the interface for an application to access published data. There are several varieties of read() and take(), to facilitate different access patterns or approaches.

The primary difference between read() and take() is that take() removes all returned data samples from the DataReader while read() does not. Sequential read() calls will return the same data samples each time (if nothing else changes); while sequential take() calls will return data samples for only the first call. Subsequent take() calls will return an empty collection (if no new data arrives).

The specific behavior of take() depends on several things: input paramters, the QoS settings of the DataReader, and the state of recieved data. First, the received_data and sample_infos arguments affect the following:

  • how many samples are returned, and
  • whether the returned data should be 'loaned' or copied.

The argument max_samples is used to further limit the number of samples returned.

The sample_states, view_states, and instance_states arguments are used to selectively add data samples to the returned collections. These arguments indicate the desired 'states' for data samples and instances. These state arguments are bit masks; they can be the bit-wise OR of several individual state flags or they may use the special 'ANY' constants (e.g.: DDS_ANY_SAMPLE_STATE). Only samples that have a matching state for all three categories are added to the returned collection.

The order of samples in the returned collections is determined by the PRESENTATION and DESTINATION_ORDER QoS policies.

The returned collection is held in recieved_data and samples_infos. These two sequences operate together to represent a sequence of pairs (data, SampleInfo). Each data item in received_data has a corresponding entry in sample_infos that provides associated 'meta-data'. See DDS_SampleInfo for a description of this meta-data.

In CoreDX DDS, the returned sequences contain 'loaned' data. This provides zero-copy access to the data, and provides a very efficient data access mechanism. Becuase the data is 'loaned' to the application, the application is required to indicate when it is finished accessing the data. This is accomplished by calling DDS_DataReader_return_loan().

The take() operation will set the DDS_SampleInfo::sample_state to DDS_READ_SAMPLE_STATE.

The take() operation may set the DDS_SampleInfo::view_state to DDS_NOT_NEW_VIEW_STATE, if a sample of the most recent generation of the instance is taken.

If there is no data found, then the take() will return DDS_RETCODE_NO_DATA.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
DDS_ReturnCode_t DDS_DataReader_take_instance ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_InstanceHandle_t  a_handle,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)
related

This operation takes a collection of data values (with associated DDS_SampleInfo), belonging to a particular instance, from the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_take()
DDS_ReturnCode_t DDS_DataReader_take_next_instance ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_InstanceHandle_t  previous_handle,
DDS_SampleStateMask  sample_states,
DDS_ViewStateMask  view_states,
DDS_InstanceStateMask  instance_states 
)
related

This operation takes a collection of data values (with associated DDS_SampleInfo), instance by instance, from the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_take()
DDS_ReturnCode_t DDS_DataReader_take_next_instance_w_condition ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_InstanceHandle_t  previous_handle,
DDS_ReadCondition  a_condition 
)
related

This operation takes a collection of data values (with associated DDS_SampleInfo), instance by instance subject to a filter, from the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_take()
DDS_ReturnCode_t DDS_DataReader_take_next_sample ( DDS_DataReader  dr,
void *  received_data,
DDS_SampleInfo sample_info 
)
related

This operation takes a data value (with associated DDS_SampleInfo) from the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_take()
DDS_ReturnCode_t DDS_DataReader_take_w_condition ( DDS_DataReader  dr,
DDS_PointerSeq *  received_data,
DDS_SampleInfoSeq *  sample_infos,
int32_t  max_samples,
DDS_ReadCondition  a_condition 
)
related

This operation takes a collection of data values (with associated DDS_SampleInfo), subject to a filter, from the DataReader.

Note
This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.
See also
DDS_DataReader_take()

© 2009-2017 Twin Oaks Computing, Inc
Castle Rock, CO 80108
All rights reserved.