Creating Subscribers

You are here:

Creating Subscribers

Before you can explicitly create a Subscriber, you need a DomainParticipant (DomainParticipants). To create a Subscriber, use the DomainParticipant’s create_subscriber() or create_subscriber_with_profile() operation.

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: the Modern C++ API provides Subscriber constructors whose first, and only required argument is the DomainParticipant.

DDSSubscriber* create_subscriber( 
    const DDS_SubscriberQos &qos,
    DDSSubscriberListener * listener,
    DDS_StatusMask mask)
DDSSubscriber* create_subscriber_with_profile ( 
    const char * library_name,
    const char * profile_name,
    DDSSubscriberListener * listener,
    DDS_StatusMask  mask )

Where:

qos	If you want the default QoS settings (described in the API Reference HTML documentation), use DDS_SUBSCRIBER_QOS_DEFAULT for this parameter (see Figure: Creating a Subscriber with Default QosPolicies ). If you want to customize any of the QosPolicies, supply a QoS structure (see Figure: Creating a Subscriber with Non-Default QosPolicies (not from a profile) ). The QoS structure for a Subscriber is described in Subscriber QosPolicies. Note: If you use DDS_SUBSCRIBER_QOS_DEFAULT, it is not safe to create the Subscriber while another thread may be simultaneously calling set_default_subscriber_qos().
listener	Listeners are callback routines. Connext DDS uses them to notify your application when specific events (new DDS data samples arrive and status changes) occur with respect to the Subscriber or the DataReaders created by the Subscriber. The listener parameter may be set to NULL if you do not want to install a Listener. If you use NULL, the Listener of the DomainParticipant to which the Subscriber belongs will be used instead (if it is set). For more information on SubscriberListeners, see Setting Up SubscriberListeners.
mask	This bit-mask indicates which status changes will cause the Subscriber’s 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 Status, see Listeners. This bit-mask indicates which status changes will cause the Subscriber’s 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 Status, 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.

Figure: Creating a Subscriber with Default QosPolicies

// create the subscriber
DDSSubscriber* subscriber =
    participant->create_subscriber(
        DDS_SUBSCRIBER_QOS_DEFAULT,
        NULL, DDS_STATUS_MASK_NONE);
if (subscriber == NULL) {
// handle error
}

For more examples, see Configuring QoS Settings when the Subscriber is Created.

After you create a Subscriber, the next step is to use the Subscriber to create a DataReader for each Topic, see Creating DataReaders. For a list of operations you can perform with a Subscriber, see Subscriber Operations.