Subscribers

You are here: Part 2: Core Concepts > Receiving Data > Subscribers

Subscribers

An application that intends to subscribe to information needs the following Entities: DomainParticipant, Topic, Subscriber, and DataReader. All Entities have a corresponding specialized Listener and a set of QosPolicies. The Listener is how Connext DDS notifies your application of status changes relevant to the Entity. The QosPolicies allow your application to configure the behavior and resources of the Entity.

The DomainParticipant defines the DDS domain on which the information will be available.
The Topic defines the name of the data to be subscribed, as well as the type (format) of the data itself.
The DataReader is the Entity used by the application to subscribe to updated values of the data. The DataReader is bound at creation time to a Topic, thus specifying the named and typed data stream to which it is subscribed. The application uses the DataWriter’s read() or take() operation to access DDS data samples received for the Topic.
The Subscriber manages the activities of several DataReader entities. The application receives data using a DataReader that belongs to a Subscriber. However, the Subscriber will determine when the data received from applications is actually available for access through the DataReader. Depending on the settings of various QosPolicies of the Subscriber and DataReader, data may be buffered until DDS data samples for associated DataReaders are also received. By default, the data is available to the application as soon as it is received.

For more information, see Creating Subscribers Explicitly vs. Implicitly.

The UML diagram in Subscription Module shows how these Entities are related as well as the methods defined for each Entity.

Subscribers are used to perform the operations listed in . For details such as formal parameters and return codes, please see the API Reference HTML documentation. Otherwise, you can find more information about the operations by looking in the section listed under the Reference column.

Figure 1 Subscription Module

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks.

Subscriber Operations
Working with ...	Operation	Description	Reference
DataReaders	begin_access	Indicates that the application is about to access the DDS data samples in the DataReaders of the Subscriber.	Beginning and Ending Group-Ordered Access
	create_datareader	Creates a DataReader.	Creating DataReaders
	create_datareader_ with_profile	Creates a DataReader with QoS from a specified QoS profile.	Creating DataReaders
	copy_from_topic_qos	Copies relevant QosPolicies from a Topic into a DataReaderQoS structure.	Subscriber QoS-Related Operations
DataReaders cont'd	delete_contained_ entities	Deletes all the DataReaders that were created by the Subscriber. Also deletes the corresponding ReadConditions created by the contained DataReaders.	Deleting Contained DataReaders
	delete_datareader	Deletes a specific DataReader.	Deleting DataReaders
	end_access	Indicates that the application is done accessing the DDS data samples in the DataReaders of the Subscriber.	Beginning and Ending Group-Ordered Access
	get_all_datareaders	Retrieves all the DataReaders created from this Subscriber.	Getting All DataReaders
	get_datareaders	Returns a list of DataReaders that contain DDS samples with the specified sample_states, view_states and instance_states.	Getting DataReaders with Specific DDS Samples
	get_default_datareader_qos	Copies the Subscriber’s default DataReaderQos values into a DataReaderQos structure.	Setting Subscriber QosPolicies
DataReaders cont'd	get_status_changes	Gets all status changes.	Getting Status and Status Changes
	lookup_datareader	Retrieves a DataReader previously created for a specific Topic.	Finding a Subscriber’s Related Entities
	notify_datareaders	Invokes the on_data_available() operation for attached Listeners of DataReaders that have new DDS data samples.	Setting Up SubscriberListeners
	set_default_datareader_qos	Sets or changes the Subscriber’s default DataReaderQoS values.	Setting Subscriber QosPolicies
Libraries and Profiles	get_default_library	Gets the Subscriber’s default QoS profile library.	Getting and Settings Subscriber’s Default QoS Profile and Library
	get_default_profile	Gets the Subscriber’s default QoS profile.
	get_default_profile_ library	Gets the library that contains the Subscriber’s default QoS profile.
	set_default_library	Sets the default library for a Subscriber.
	set_default_profile	Sets the default profile for a Subscriber.
Participants	get_participant	Gets the Subscriber’s DomainParticipant.	Finding a Subscriber’s Related Entities


Subscribers	enable	Enables the Subscriber.	Enabling DDS Entities
	equals	Compares two Subscriber’s QoS structures for equality.	Comparing QoS Values
	get_listener	Gets the currently installed Listener.	Setting Up SubscriberListeners
	get_qos	Gets the Subscriber’s current QosPolicy settings. This is most often used in preparation for calling set_qos.	Changing QoS Settings After Subscriber Has Been Created
	set_listener	Sets the Subscriber’s Listener. If you created the Subscriber without a Listener, you can use this operation to add one later.	Setting Up SubscriberListeners
	set_qos	Sets the Subscriber’s QoS. You can use this operation to change the values for the Subscriber’s QosPolicies. Note, however, that not all QosPolicies can be changed after the Subscriber has been created.	Changing QoS Settings After Subscriber Has Been Created
	set_qos_with_profile	Sets the Subscriber’s QoS based on a QoS profile.	Changing QoS Settings After Subscriber Has Been Created