Creating DataReaders

You are here:

Creating DataReaders

Before you can create a DataReader, you need a DomainParticipant and a Topic.

DataReaders are created by calling create_datareader() or create_datareader_with_profile()—these operations exist for DomainParticipants and Subscribers. If you use the DomainParticipant to create a DataReader, it will belong to the implicit Subscriber described in Creating Subscribers Explicitly vs. Implicitly. If you use a Subscriber’s operations to create a DataReader, it will belong to that Subscriber.

A QoS profile is way to use QoS settings from an XML file or string. With this approach, you can change QoS settings without recompiling the application. For details, see Configuring QoS with XML.

Note: In the Modern C++ API, DataReaders provide constructors whose first argument is a Subscriber. The only required arguments are the subscriber and the topic.

DDSDataReader* create_datareader(
    DDSTopicDescription *topic, 
    const DDS_DataReaderQos &qos, 
    DDSDataReaderListener *listener, 
    DDS_StatusMask mask);

DDSDataReader * create_datareader_with_profile (
    DDSTopicDescription * topic, 
    const char * library_name,

    const char * profile_name, 
    DDSDataReaderListener * listener, 
    DDS_StatusMask mask)

Where:

topic	The Topic to which the DataReader is subscribing. This must have been previously created by the same DomainParticipant.
qos	If you want the default QoS settings (described in the API Reference HTML documentation), use DDS_DATAREADER_QOS_DEFAULT for this parameter (see Figure: Creating a DataReader with Default QosPolicies ). If you want to customize any of the QosPolicies, supply a QoS structure (see Setting DataReader QosPolicies). Note: If you use DDS_DATAREADER_QOS_DEFAULT for the qos parameter, it is not safe to create the DataReader while another thread may be simultaneously calling the Subscriber’s set_default_datareader_qos() operation.
listener	A DataReader’sListener is where you define the callback routine that will be notified when new DDS data samples arrive. Connext DDS also uses this Listener to notify your application of specific events (status changes) that may occur with respect to the DataReader. For more information, see Setting Up DataReaderListeners and Statuses for DataReaders. The listener parameter is optional; you may use NULL instead. In that case, the Subscriber’s Listener (or if that is NULL, the DomainParticipant’s Listener) will receive the notifications instead. See Setting Up DataReaderListeners for more on DataReaderListeners.
mask	This bit mask indicates which status changes will cause the Listener to be invoked. The bits set in the mask must have corresponding callbacks implemented in the Listener. If you use NULL for the Listener, use DDS_STATUS_MASK_NONE for this parameter. If the Listener implements all callbacks, use DDS_STATUS_MASK_ALL. For information on statuses, see Listeners.
library_name	A QoS Library is a named set of QoS profiles. See URL Groups.
profile_name	A QoS profile groups a set of related QoS, usually one per entity. See URL Groups.

After you create a DataReader, you can use it to retrieve received data. See Using DataReaders to Access Data (Read & Take).

Note: When a DataReader is created, only those transports already registered are available to the DataReader. The built-in transports are implicitly registered when (a) the DomainParticipant is enabled, (b) the first DataReader is created, or (c) you lookup a built-in DataReader, whichever happens first.

Figure: Creating a DataReader with Default QosPolicies shows an example of how to create a DataReader with default QosPolicies.

Figure: Creating a DataReader with Default QosPolicies

// MyReaderListener is user defined, extends DDSDataReaderListener
DDSDataReaderListener *reader_listener = new MyReaderListener();
DataReader* reader = subscriber->create_datareader(topic,
	DDS_DATAREADER_QOS_DEFAULT,
	reader_listener, DDS_STATUS_MASK_ALL);
if (reader == NULL) {
	// ... error
}
// narrow it into your specific data type
FooDataReader* foo_reader = FooDataReader::narrow(reader);

For more examples on how to create a DataWriter, see Setting DataReader QosPolicies