You are here: Part 2: Core Concepts > Sending Data > Publisher/Subscriber QosPolicies > GROUP_DATA QosPolicy

GROUP_DATA QosPolicy

This QosPolicy provides an area where your application can store additional information related to the Publisher and Subscriber. This information is passed between applications during discovery (see Discovery) using built-in-topics (see Built-In Topics). How this information is used will be up to user code. Connext DDS does not do anything with the information stored as GROUP_DATA except to pass it to other applications.

Use cases are often application-to-application identification, authentication, authorization, and encryption purposes. For example, applications can use this QosPolicy to send security certificates to each other for RSA-type security.

The value of the GROUP_DATA QosPolicy is sent to remote applications when they are first discovered, as well as when the Publisher or Subscriber’s set_qos() method is called after changing the value of the GROUP_DATA. User code can set listeners on the built-in DataReaders of the built-in Topics used by Connext DDS to propagate discovery information. Methods in the built-in topic listeners will be called whenever new DomainParticipants, DataReaders, and DataWriters are found. Within the user callback, you will have access to the GROUP_DATA that was set for the associated Publisher or 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 DDS_PublicationBuiltinTopicData or DDS_SubscriptionBuiltinTopicData (see Built-In Topics).

The structure for the GROUP_DATA QosPolicy includes just one field, as seen in DDS_GroupDataQosPolicy. The field is a sequence of octets that translates to a contiguous buffer of bytes whose contents and length is set by the user. The maximum size for the data are set in the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension).

DDS_GroupDataQosPolicy

Type

Field Name

Description

DDS_OctetSeq

value

Empty by default

This policy is similar to the USER_DATA QosPolicy and TOPIC_DATA QosPolicy that apply to other types of Entities.

Example

One possible use of GROUP_DATA is to pass some credential or certificate that your subscriber application can use to accept or reject communication with the DataWriters that belong to the Publisher (or vice versa, where the publisher application can validate the permission of DataReaders of a Subscriber to receive its data). The value of the GROUP_DATA of the Publisher is propagated in the ‘group_data’ field of the DDS_PublicationBuiltinTopicData that is sent with the declaration of each DataWriter. Similarly, the value of the GROUP_DATA of the Subscriber is propagated in the ‘group_data’ field of the DDS_SubscriptionBuiltinTopicData that is sent with the declaration of each DataReader.

When Connext DDS discovers a DataWriter/DataReader, the application can be notified of the discovery of the new entity and retrieve information about the DataWriter/DataReader QoS by reading the DCPSPublication or DCPSSubscription built-in topics (see Built-In Topics). Your application can then examine the GROUP_DATA field in the built-in Topic and decide whether or not the DataWriter/DataReader should be allowed to communicate with local DataReaders/DataWriters. If communication is not allowed, the application can use the DomainParticipant’s ignore_publication() or ignore_subscription() operation to reject the newly discovered remote entity as one with which the application allows Connext DDS to communicate. See Figure 16.2, “Ignoring Publications,” on page 16-12 for an example of how to do this.

The code in Figure 27 illustrates how to change the GROUP_DATA policy.

Figure 27 Creating a Publisher with GROUP_DATA

DDS_PublisherQos publisher_qos;1Note in C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C on page 1.
int i = 0;
// Bytes that will be used for the group data. In this case, 8 bytes
// of some information that is meaningful to the user application
char myGroupData[GROUP_DATA_SIZE] =
    { 0x34, 0xaa, 0xfe, 0x31, 0x7a, 0xf2, 0x34, 0xaa};
// assume domainparticipant and publisher_listener already created
if (participant->get_default_publisher_qos(publisher_qos) !=
    DDS_RETCODE_OK) {
    // handle error
}
// Must set the size of the sequence first
publisher_qos.group_data.value.maximum(GROUP_DATA_SIZE);
publisher_qos.group_data.value.length(GROUP_DATA_SIZE);
for (i = 0; i < GROUP_DATA_SIZE; i++) {
    publisher_qos.group_data.value[i] = myGroupData[i]
}
DDSPublisher* publisher = participant->create_publisher( publisher_qos,
    publisher_listener, DDS_STATUS_MASK_ALL);

Properties

This QosPolicy can be modified at any time.

It can be set differently on the publishing and subscribing sides.

Related QosPolicies

Applicable DDS Entities

System Resource Considerations

The maximum size of the GROUP_DATA is set in the publisher_group_data_max_length and subscriber_group_data_max_lengthfields of the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension). Because Connext DDS will allocate memory based on this value, you should only increase this value if you need to. If your system does not use GROUP_DATA, then you can set this value to zero to save memory. Setting the value of the GROUP_DATA QosPolicy to hold data longer than the value set in the [publisher/subscriber]_group_data_max_length fields will result in failure and an INCONSISTENT_QOS_POLICY return code.

However, should you decide to change the maximum size of GROUP_DATA, you must make certain that all applications in the DDS domain have changed the value of [publisher/subscriber]_group_data_max_length to be the same. If two applications have different limits on the size of GROUP DATA, and one application sets the GROUP_DATA QosPolicy to hold data that is greater than the maximum size set by another application, then the matching DataWriters and DataReaders of the Publisher and Subscriber between the two applications will not connect. This is also true for the TOPIC_DATA (TOPIC_DATA QosPolicy) and USER_DATA (USER_DATA QosPolicy) QosPolicies.

© 2017 RTI