This QosPolicy provides an area where your application can store additional information related to a DomainParticipant, DataWriter, or DataReader. 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 USER_DATA except to pass it to other applications.
Use cases are usually for application-to-application identification, authentication, authorization, and encryption purposes. For example, applications can use Group or User Data to send security certificates to each other for RSA-type security.
The value of the USER_DATA QosPolicy is sent to remote applications when they are first discovered, as well as when the DomainParticipant, DataWriter or DataReader’s set_qos() methods are called after changing the value of the USER_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 USER_DATA that was set for the associated Entity.
Currently, USER_DATA of the associated Entity is only propagated with the information that declares a DomainParticipant, DataWriter or DataReader. Thus, you will need to access the value of USER_DATA through DDS_ParticipantBuiltinTopicData, DDS_PublicationBuiltinTopicData or DDS_SubscriptionBuiltinTopicData (see Built-In Topics).
The structure for the USER_DATA QosPolicy includes just one field, as seen in . 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).
Type |
Field Name |
Description |
DDS_OctetSeq |
value |
Default: empty |
This policy is similar to the GROUP_DATA QosPolicy and TOPIC_DATA QosPolicy that apply to other types of Entities.
One possible use of USER_DATA is to pass some credential or certificate that your subscriber application can use to accept or reject communication with the DataWriters (or vice versa, where the publisher application can validate the permission of DataReaders to receive its data). Using the same method, an application (DomainParticipant) can accept or reject all connections from another application. The value of the USER_DATA of the DomainParticipant is propagated in the ‘user_data’ field of the DDS_ParticipantBuiltinTopicData that is sent with the declaration of each DomainParticipant. Similarly, the value of the USER_DATA of the DataWriter is propagated in the ‘user_data’ field of the DDS_PublicationBuiltinTopicData that is sent with the declaration of each DataWriter, and the value of the USER_DATA of the DataReader is propagated in the ‘user_data’ field of the DDS_SubscriptionBuiltinTopicData that is sent with the declaration of each DataReader.
When Connext DDS discovers a DomainParticipant/DataWriter/DataReader, the application can be notified of the discovery of the new entity and retrieve information about the Entity’s QoS by reading the DCPSParticipant, DCPSPublication or DCPSSubscription built-in topics (see Built-In Topics). The user application can then examine the USER_DATA field in the built-in Topic and decide whether or not the remote Entity should be allowed to communicate with the local Entity. If communication is not allowed, the application can use the DomainParticipant’s ignore_participant(), 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 Built-in DataReaders for an example of how to do this.
This QosPolicy can be modified at any time. A change in the QosPolicy will cause Connext DDS to send packets containing the new USER_DATA to all of the other applications in the DDS domain.
It can be set differently on the publishing and subscribing sides.
The maximum size of the USER_DATA is set in the participant_user_data_max_length, writer_user_data_max_length, and reader_user_data_max_length fields of the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension). Because Connext DDS will allocated memory based on this value, you should only increase this value if you need to. If your system does not use USER_DATA, then you can set this value to 0 to save memory. Setting the value of the USER_DATA QosPolicy to hold data longer than the value set in the [participant,writer,reader]_user_data_max_length field will result in failure and an INCONSISTENT_QOS_POLICY return code.
However, should you decide to change the maximum size of USER_DATA, you must make certain that all applications in the DDS domain have changed the value of [participant,writer,reader]_user_data_max_length to be the same. If two applications have different limits on the size of USER_DATA, and one application sets the USER_DATA QosPolicy to hold data that is greater than the maximum size set by another application, then the DataWriters and DataReaders between the two applications will not connect. The DomainParticipants may also reject connections from each other entirely. This is also true for the GROUP_DATA (GROUP_DATA QosPolicy) and TOPIC_DATA (TOPIC_DATA QosPolicy) QosPolicies.
© 2016 RTI