31.16 Navigating Relationships Among DDS Entities

31.16.1 Finding Matching Subscriptions

The following DataWriter operations can be used to get information on the DataReaders that are currently associated with the DataWriter (that is, the DataReaders to which Connext will send the data written by the DataWriter). A subscription consists of information about the DataReader and its associated Subscriber and Topic.

  • get_matched_subscriptions()
  • get_matched_subscription_data()
  • get_matched_subscription_locators()

get_matched_subscriptions() will return a sequence of handles to matched DataReaders. You can use these handles in the get_matched_subscription_data() method to get information about the DataReader such as the values of its QosPolicies, as well as information about its Subscriber and Topic.

get_matched_subscription_locators() retrieves a list of locators for subscriptions currently "associated" with the DataWriter. Matched subscription locators include locators for all those subscriptions in the same DDS domain that have a matching Topic, compatible QoS, and a common partition that the DomainParticipant has not indicated should be "ignored." These are the locators that Connext uses to communicate with matching DataReaders. (See 24.1.1 Locator Format.)

Note: In the Modern C++ API, these operations are freestanding functions in the dds::pub or rti::pub namespaces.

You can also get the DATA_WRITER_PROTOCOL_STATUS for matching subscriptions with these operations (see 31.6.3 DATA_WRITER_PROTOCOL_STATUS):

  • get_matched_subscription_datawriter_protocol_status()
  • get_matched_subscription_datawriter_protocol_status_by_locator()

Notes:

  • The get_matched_subscriptions() function includes the return of handles of matched DataReaders that are no longer active. All of the handles returned by this function are valid inputs to the get_matched_subscription_data() function.
  • Status/data for a matched subscription is kept even if the matched DataReader is not active. Status/data for a matched subscription will be removed only if the DataReader is gone: that is, the DataReader is destroyed and this change is propagated through a discovery update, or the DataReader's DomainParticipant is gone (either gracefully or its liveliness expired and Connext is configured to purge not-alive participants). Once a matched DataReader is gone, its status is deleted. If you try to get the status/data for a matched DataReader that is gone, the 'get status' or ' get data' call will return an error.
  • If you want to know which matched DataReaders are not active, use is_matched_subscription_active(). See Table 31.1 DataWriter Operations.
  • DataReaders that have been ignored using the DomainParticipant’s ignore_subscription() operation are not considered to be matched even if the DataReader has the same Topic and compatible QosPolicies. Thus, they will not be included in the list of DataReaders returned by get_matched_subscriptions() or get_matched_subscription_locators(). See 27.2 Ignoring Publications and Subscriptions for more on ignore_subscription().
  • The get_matched_subscription_data() operation does not retrieve the type_code information from built-in-topic data structures. This information is available through the on_data_available() callback (if a DataReaderListener is installed on the SubscriptionBuiltinTopicDataDataReader).

See also: 31.16.2 Finding the Matching Subscription’s ParticipantBuiltinTopicData

31.16.2 Finding the Matching Subscription’s ParticipantBuiltinTopicData

get_matched_subscription_participant_data() allows you to get the DDS_ParticipantBuiltinTopicData (see Table 28.1 Participant Built-in Topic’s Data Type (DDS_ParticipantBuiltinTopicData)) of a matched subscription using a subscription handle.

This operation retrieves the information on a discovered DomainParticipant associated with the subscription that is currently matching with the DataWriter.The subscription handle passed into this operation must correspond to a subscription currently associated with the DataWriter. Otherwise, the operation will fail with RETCODE_BAD_PARAMETER. The operation may also fail with RETCODE_PRECONDITION_NOT_MET if the subscription corresponds to the same DomainParticipant to which the DataWriter belongs.

Use get_matched_subscriptions() (see 31.16.1 Finding Matching Subscriptions) to find the subscriptions that are currently matched with the DataWriter.

31.16.3 Finding Related DDS Entities

These operations are useful for obtaining a handle to various related Entities:

  • get_publisher()
  • get_topic()

get_publisher() returns the Publisher that created the DataWriter. get_topic() returns the Topic with which the DataWriter is associated.