5.8. User Discovery Data¶

5.8.1. Introduction¶

User Discovery Data is a feature of Connext Micro that provides areas where your application can store additional information related to DDS Entities. How this information is used will be up to user code; Connext Micro distributes this information to other applications as part of the discovery process, but Connext Micro does not interpret the information. Use cases are usually application-to-application identification, authentication, authorization, and encryption.

There are three User Discovery Data QoS policies:

USER_DATA: associated with DomainParticipants, DataWriters, and DataReaders.
TOPIC_DATA: associated with a Topic.
GROUP_DATA: associated with a Publisher or Subscriber.

Warning

These QoS policies must be specified when an entity is created and cannot be modified at runtime.

5.8.2. Resource Limits¶

Before these QoS policies can be used, the DomainParticipantResourceLimitsQosPolicy must be configured to set the maximum length of each kind of data which will be used. These settings are listed below:

participant_user_data_max_length
topic_data_max_length
publisher_group_data_max_length
subscriber_group_data_max_length
writer_user_data_max_length
reader_user_data_max_length

These policy settings limit the length of the data field, and must be configured to the same values for all DomainParticipants in the same DDS domain. Attempting to create an entity with user discovery data larger than the corresponding QoS setting will cause creation of that entity to fail. Similarly, discovering remote entities will fail if those entities have user discovery data larger than the QoS policy setting.

Memory usage by the discovery data will be directly affected by the maximum length of each type of data because Connext Micro will pre-allocate all of the memory necessary to store received data. Setting the maximum length appropriately will limit the memory usage of this feature.

Connext Micro also adds settings to further optimize memory usage via the max_count resource limit options, listed below:

participant_user_data_max_count
topic_data_max_count
publisher_group_data_max_count
subscriber_group_data_max_count
writer_user_data_max_count
reader_user_data_max_count

These options limit the number of unique data of a given type. Data from local and discovered entities both contribute toward this limit.

These maximums will default to DDS_SIZE_AUTO, in which case Connext Micro will generate an appropriate value based on other QoSes to ensure that discovery will always succeed. However, if you know the maximum number of unique data that will exist in the domain, setting these options accordingly can reduce the total amount of memory allocated.

Warning

Once the max_count limit of unique data has been reached for a given entity type, discovery of entities with additional unique data will fail.

5.8.3. Propagating User Discovery Data¶

When using Dynamic Discovery Plugin (DPDE), the information associated with all entities is automatically passed between applications during discovery using builtin topics. When using Static Discovery Plugin (DPSE), only the USER_DATA associated with a participant will be automatically passed between applications; for remote DataReaders and DataWriters, the associated USER_DATA, TOPIC_DATA, or GROUP_DATA must be asserted with remote publications and subscriptions. (See Accessing User Discovery Data below.)

For example, to assert USER_DATA associated with a remote subscription in DPSE:

struct DDS_SubscriptionBuiltinTopicData rem_subscription_data =
   DDS_SubscriptionBuiltinTopicData_INITIALIZER;

/* Set Reader's protocol.rtps_object_id */
rem_subscription_data.key.value[DDS_BUILTIN_TOPIC_KEY_OBJECT_ID] = 200;

rem_subscription_data.topic_name = DDS_String_dup("Example HelloWorld");
rem_subscription_data.type_name = DDS_String_dup("HelloWorld");

rem_subscription_data.reliability.kind = DDS_RELIABLE_RELIABILITY_QOS;

/* Set USER_DATA */
DDS_OctetSeq_set_maximum(&rem_subscription_data.user_data.value, 2);
DDS_OctetSeq_set_length(&rem_subscription_data.user_data.value, 2);
*DDS_OctetSeq_get_reference(&rem_subscription_data.user_data.value, 0) = 0xAA;
*DDS_OctetSeq_get_reference(&rem_subscription_data.user_data.value, 1) = 0xBB;

retcode = DPSE_RemoteSubscription_assert(participant,
                                       "Participant_2",
                                       &rem_subscription_data,
                                       HelloWorld_get_key_kind(HelloWorldTypePlugin_get(),
                                       NULL));
if (retcode != DDS_RETCODE_OK)
{
   /* failure */
}

5.8.4. Accessing User Discovery Data¶

Whether using DPDE or DPSE, the USER_DATA, TOPIC_DATA, and GROUP_DATA is propagated with the information about remote DomainParticipants, DataWriters, and DataReaders. For DomainParticipants, the associated USER_DATA can be accessed through ParticipantBuiltinTopicData. For DataWriters and DataReaders, the associated USER_DATA, TOPIC_DATA, and GROUP_DATA can be accessed through the PublicationBuiltinTopicData and SubscriptionBuiltinTopicData respectively.

For DomainParticipants, the discovery information for discovered participants can be accessed through the get_discovered APIs:

For DataReaders and DataWriters, the information on matched entities can be retrieved through the get_matched APIs:

Note that these APIs will perform a copy into the provided data sample. If the provided sample does not have enough memory to store the data, additional memory will be allocated to fit it. This memory can instead be pre-allocated with the corresponding initialize_from_qos function. If a sample is pre-allocated based on the configured QoS, then no additional memory will need to be allocated to perform the copy.

For example, to retrieve information on discovered participants:

struct DDS_InstanceHandleSeq handles = DDS_SEQUENCE_INITIALIZER;
struct DDS_InstanceHandle handle;
struct DDS_DomainParticipantQos dp_qos =
            DDS_DomainParticipantQos_INITIALIZER;
struct DDS_ParticipantBuiltinTopicData dp_data =
            DDS_ParticipantBuiltinTopicData_INITIALIZER;

/* Pre-allocate memory for discovery data based on participant's QoS */
retcode = DDS_DomainParticipant_get_qos(participant, &dp_qos);
if (retcode != DDS_RETCODE_OK)
{
   /* failure */
}
if (!DDS_ParticipantBuiltinTopicData_initialize_from_qos(&dp_data, &dp_qos))
{
   /* failure */
}

/* Get instance handles of discovered participants */
retcode = DDS_DomainParticipant_get_discovered_participants(participant, &handles);
if (retcode != DDS_RETCODE_OK)
{
   /* failure */
}

/* For each handle, get the discovery data */
for (DDS_Long j = 0; j < DDS_InstanceHandleSeq_get_length(&handles); ++j)
{
   handle = DDS_InstanceHandleSeq_get_reference(&handles, j);
   if (handle == NULL)
   {
      /* failure */
   }

   retcode = DDS_DomainParticipant_get_discovered_participant_data(participant,
                                                                  &dp_data,
                                                                  handle);
   if (retcode != DDS_RETCODE_OK)
   {
      /* failure */
   }
   else
   {
      /* Discovered participant USER_DATA can be accessed in dp_data.user_data */
   }
}

5.8.5. QoS Policies¶

5.8.5.1. USER_DATA¶

This Qos Policy provides an area where your application can store additional information related to a DomainParticipant, DataWriter, or DataReader.

You will need to access the value of USER_DATA through ParticipantBuiltinTopicData, PublicationBuiltinTopicData or SubscriptionBuiltinTopicData. (See Accessing User Discovery Data.)

The structure for the USER_DATA QosPolicy includes just one field, as seen in Table 5.1. The field is a sequence of octets that translates to a contiguous buffer of bytes whose contents and length are set by the user. The maximum size for the data is set in the DomainParticipantResourceLimitsQosPolicy. (See Resource Limits.)

Table 5.1 DDS_UserDataQosPolicy¶
Type	Field Name	Description
DDS_OctetSeq	value	Empty by default

5.8.5.2. TOPIC_DATA¶

This QoS Policy provides an area where your application can store additional information related to the Topic.

Currently, TOPIC_DATA of the associated Topic is only propagated with the information that declares a DataWriter or DataReader. Thus, you will need to access the value of TOPIC_DATA through PublicationBuiltinTopicData or SubscriptionBuiltinTopicData. (See Accessing User Discovery Data)

The structure for the TOPIC_DATA QosPolicy includes just one field, as seen in Table 5.2. The field is a sequence of octets that translates to a contiguous buffer of bytes whose contents and length are set by the user. The maximum size for the data is set in the DomainParticipantResourceLimitsQosPolicy. (See Resource Limits)

Table 5.2 DDS_TopicDataQosPolicy¶
Type	Field Name	Description
DDS_OctetSeq	value	Empty by default

5.8.5.3. GROUP_DATA¶

This Qos Policy provides an area where your application can store additional information related to the Publisher and Subscriber.

Currently, GROUP_DATA of the associated Publisher or Subscriber is only propagated with the information that declares a DataWriter or DataReader. Thus, you will need to access the value of GROUP_DATA through PublicationBuiltinTopicData or SubscriptionBuiltinTopicData. (See Accessing User Discovery Data)

The structure for the TOPIC_DATA QosPolicy includes just one field, as seen in Table 5.3. The field is a sequence of octets that translates to a contiguous buffer of bytes whose contents and length are set by the user. The maximum size for the data is set in the DomainParticipantResourceLimitsQosPolicy. (See Resource Limits)

Table 5.3 DDS_GroupDataQosPolicy¶
Type	Field Name	Description
DDS_OctetSeq	value	Empty by default