DataReader Class Reference

Inheritance diagram for DataReader:

Public Member Functions
new ReturnCode_t	enable ()
override InstanceHandle_t	get_instance_handle ()
ReadCondition	create_readcondition (uint sample_states, uint view_states, uint instance_states)
QueryCondition	create_querycondition (uint sample_states, uint view_states, uint instance_states, String query_expression, List< String > query_parameters)
ReturnCode_t	delete_readcondition (ReadCondition rc)
ReturnCode_t	delete_contained_entities ()
ReturnCode_t	set_qos (DataReaderQos qos)
ReturnCode_t	get_qos (DataReaderQos qos)
ReturnCode_t	set_listener (DataReaderListener new_listener, uint mask)
DataReaderListener	get_listener ()
TopicDescription	get_topicdescription ()
Subscriber	get_subscriber ()
ReturnCode_t	get_sample_rejected_status (out SampleRejectedStatus status)
ReturnCode_t	get_liveliness_changed_status (out LivelinessChangedStatus status)
ReturnCode_t	get_requested_deadline_missed_status (out RequestedDeadlineMissedStatus status)
ReturnCode_t	get_requested_incompatible_qos_status (out RequestedIncompatibleQosStatus status)
ReturnCode_t	get_subscription_matched_status (out SubscriptionMatchedStatus status)
ReturnCode_t	get_sample_lost_status (out SampleLostStatus status)
ReturnCode_t	wait_for_historical_data (Duration_t max_wait)
ReturnCode_t	get_matched_publications (List< InstanceHandle_t > publication_handles)
ReturnCode_t	get_matched_publication_data (PublicationBuiltinTopicData publication_data, InstanceHandle_t publication_handle)
ReturnCode_t	get_guid (GUID_t g)
Public Member Functions inherited from Entity
virtual StatusCondition	get_statuscondition ()
virtual uint	get_status_changes ()

Detailed Description

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

The DataReader 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).

Member Function Documentation

QueryCondition create_querycondition ( uint  sample_states, uint  view_states, uint  instance_states, String  query_expression, List< String >  query_parameters  )

inline

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

FooDataReader::read_w_condition().

FooDataReader::take_w_condition().

Not Yet Supported:

QueryConditions are not yet supported as triggers for a WaitSet.

ReadCondition create_readcondition ( uint  sample_states, uint  view_states, uint  instance_states  )

inline

Creates a ReadCondition that is associated with this DataReader. The returned condition can be added to a WaitSet or used in a call to the specialized read() or take() operations. For example see FooDataReader.read_w_condition()

ReturnCode_t delete_contained_entities ( )

inline

This operation deletes all the ReadCondition and QueryCondition objects previously created by means of the DataReader.create_readcondition() and DataReader.create_querycondition() operations.

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

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

ReturnCode_t delete_readcondition ( ReadCondition  rc )

inline

Destroys a ReadCondition (or QueryCondition). The provided a_condition must have been previously created via a call to DataReader.create_readcondition() or 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.

new ReturnCode_t enable ( )

inlinevirtual

Enables the DataReader. A DataReader is created either enabled or not based on the 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.RETCODE_NOT_ENABLED error. DataReader_enable() may be called on an already enabled DataReader [it will have no effect].

Reimplemented from Entity.

ReturnCode_t get_guid ( GUID_t  g )

inline

Access the GUID which uniquely identifies this reader.

override InstanceHandle_t get_instance_handle ( )

inlinevirtual

Gets the handle that locally identifies this Entity.

Reimplemented from Entity.

DataReaderListener get_listener ( )

inline

This operation returns the currently installed DataReaderListener.

ReturnCode_t get_liveliness_changed_status ( out LivelinessChangedStatus  status )

inline

Provides access to the current LivelinessChangedStatus of the DataReader. As a side-effect, this routine will reset the total_count_change status field to zero.

ReturnCode_t get_matched_publication_data ( PublicationBuiltinTopicData  publication_data, InstanceHandle_t  publication_handle  )

inline

This operation returns data that describes a particular matched DataWriter identified by publication_handle. An appropriate handle can be obtained through a call to DataReader.get_matched_publications().

If publication_handle does not identify a currently matched DataWriter, this routine will return DDS.RETCODE_PRECONDITION_NOT_MET.

ReturnCode_t get_matched_publications ( List< InstanceHandle_t >  publication_handles )

inline

This operation retrieves the list of DataWriters currently matched with this 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 DomainParticipant.ignore_publication(), then it will not appear in the list.

Parameters

publication_handles

A vector that will be populated with InstanceHandle_t(s).

ReturnCode_t get_qos ( DataReaderQos  qos )

inline

Returns the current DataReaderQos settings held in the DataReader dr. This routines copies data from the DataReader QoS properties into qos.

ReturnCode_t get_requested_deadline_missed_status ( out RequestedDeadlineMissedStatus  status )

inline

Provides access to the current RequestedDeadlineMissedStatus of the DataReader. As a side-effect, this routine will reset the total_count_change status field to zero.

ReturnCode_t get_requested_incompatible_qos_status ( out RequestedIncompatibleQosStatus  status )

inline

Provides access to the current RequestedIncompatibleQosStatus of the DataReader. As a side-effect, this routine will reset the total_count_change status field to zero.

ReturnCode_t get_sample_lost_status ( out SampleLostStatus  status )

inline

Provides access to the current SampleLostStatus of the DataReader. As a side-effect, this routine will reset the total_count_change status field to zero.

ReturnCode_t get_sample_rejected_status ( out SampleRejectedStatus  status )

inline

Provides access to the current SampleRejectedStatus of the DataReader. As a side-effect, this routine will reset the total_count_change status field to zero.

Subscriber get_subscriber ( )

inline

Returns the Subscribier that contains DataReader dr.

ReturnCode_t get_subscription_matched_status ( out SubscriptionMatchedStatus  status )

inline

Provides access to the current SubscriptionMatchedStatus of the DataReader. As a side-effect, this routine will reset the total_count_change status field to zero.

TopicDescription get_topicdescription ( )

inline

Returns the TopicDescription associated with DataReader dr.

ReturnCode_t set_listener ( DataReaderListener  new_listener, uint  mask  )

inline

Installs a 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.

ReturnCode_t set_qos ( DataReaderQos  qos )

inline

Sets the DataReaderQos values. These QoS values affect the behavior of the DataReader. This routine may fail if the provided qos argument is not internally consistent. In this case, DDS.RETCODE_INCONSISTENT_POLICY will be returned, and no changes will be made to the DataReader QoS.

ReturnCode_t wait_for_historical_data ( Duration_t  max_wait )

inline

This routine blocks until all 'historical' data is received.

Parameters

max_wait

The maximum amount of time to block while waiting. Can be set to { DDS.DURATION_INFINITE_SEC, DDS.DURATION_INFINITE_NSEC }