You are here: Part 2: Core Concepts > Topics > Topic QosPolicies > TOPIC_DATA QosPolicy

TOPIC_DATA QosPolicy

This QosPolicy provides an area where your application can store additional information related to the Topic. This information is passed between applications during discovery (see Discovery) using builtin-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 TOPIC_DATA except to pass it to other applications. Use cases are usually application-to-application identification, authentication, authorization, and encryption purposes.

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

The structure for the TOPIC_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).

DDS_TopicDataQosPolicy

Type

Field Name

Description

DDS_OctetSeq

value

default: empty

This policy is similar to the GROUP_DATA (GROUP_DATA QosPolicy) and USER_DATA (USER_DATA QosPolicy) policies that apply to other types of Entities.

Example

One possible use of TOPIC_DATA is to send an associated XML schema that can be used to process the data stored in the associated user data structure of the Topic. The schema, which can be passed as a long sequence of characters, could be used by an XML parser to take DDS samples of the data received for a Topic and convert them for updating some graphical user interface, web application or database.

Properties

This QosPolicy can be modified at any time. A change in the QosPolicy will cause Connext DDS to send packets containing the new TOPIC_DATA to all of the other applications in the DDS domain.

Because Topics are created independently by the applications that use the Topic, there may be different instances of the same Topic (same topic name and DDS data type) in different applications. The TOPIC_DATA for different instances of the same Topic may be set differently by different applications.

Related QosPolicies

Applicable DDS Entities

System Resource Considerations

As mentioned earlier, the maximum size of the TOPIC_DATA is set in the topic_data_max_length field 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 TOPIC_DATA, then you can set this value to 0 to save memory. Setting the value of the TOPIC_DATA QosPolicy to hold data longer than the value set in the topic_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 TOPIC_DATA, you must make certain that all applications in the DDS domain have changed the value of topic_data_max_length to be the same. If two applications have different limits on the size of TOPIC_DATA, and one application sets the TOPIC_DATA QosPolicy to hold data that is greater than the maximum size set by another application, then the DataWriters and DataReaders of that Topic between the two applications will not connect. This is also true for the GROUP_DATA (GROUP_DATA QosPolicy) and USER_DATA (USER_DATA QosPolicy) QosPolicies.

© 2016 RTI