PROPERTY QosPolicy (DDS Extension)

47.19 PROPERTY QosPolicy (DDS Extension)

The PROPERTY QosPolicy stores name/value (string) pairs that can be used to configure certain parameters of Connext that are not exposed through formal QoS policies.

It can also be used to store and propagate application-specific name/value pairs that can be retrieved by user code during discovery. This is similar to the USER_DATA QosPolicy, except this policy uses (name, value) pairs, and you can select whether or not a particular pair should be propagated (included in the built-in topic). By default, properties are not propagated during discovery.

It includes the member in Table 47.34 DDS_PropertyQosPolicy.

Table 47.34 DDS_PropertyQosPolicy
Type	Field Name	Description
DDS_PropertySeq	value	A sequence of: (name, value) pairs and booleans that indicate whether the pair should be propagated (included in the entity’s built-in topic upon discovery).

The Property QoS stores name/value pairs for an Entity. Both the name and value are strings. Certain configurable parameters for Entities that do not have a formal DDS QoS definition may be configured via this QoS by using a predefined name and the desired setting in string form.

You can find a complete list of predefined properties in the Property Reference Guide.

You can manipulate the sequence of properties (name, value pairs) with the standard methods available for sequences. You can also use the helper class, DDSPropertyQosPolicyHelper, which provides another way to work with a PropertyQosPolicy object.

The PropertyQosPolicy may be used to configure:

Durable writer history (see 21.3.2 How To Configure Durable Writer History)
Durable reader state (see 21.4.4 How To Configure a DataReader for Durable Reader State)
Built-in and extension Transport Plugins (see 51.6 Setting Builtin Transport Properties with the PropertyQosPolicy, 53.2 Configuring the TCP Transport).
Automatic registration of built-in types (see 17.2.1 Registering Built-in Types)
16.3.15 Configuring the Clock per DomainParticipant
31.18 Turbo Mode and Automatic Throttling for DataWriter Performance—Experimental Features
Location or content of your license from RTI (see License Management, in the RTI Connext Installation Guide)

In addition, you can add your own name/value pairs to the Property QoS of an Entity. Start them with a prefix other than dds., com.rti., or rti., so that they do not fail validation. (See 47.19.1 Property Validation.) You may also use this QosPolicy to direct Connext to propagate these name/value pairs with the discovery information for the Entity. Applications that discover the Entity can then access the user-specific name/value pairs in the discovery information of the remote Entity. This allows you to add meta-information about an Entity for application-specific use, for example, authentication/authorization certificates (which can also be done using the User or Group Data QoS).

Reasons for using the PropertyQosPolicy include:

Some features can only be configured through the PropertyQosPolicy, not through other QoS or APIs (for example, Durable Reader State, Durable Writer History, Built-in Types, Monotonic Clock).
Alternative way to configure built-in transports settings. For example, to use non-default values for the built-in transports without using the PropertyQosPolicy, you would have to create a DomainParticipant disabled, change the built-in transport property settings, then enable the DomainParticipant. Using the PropertyQosPolicy to configure built-in transport settings will save you the work of enabling and disabling the DomainParticipant.

Note: Starting with Connext 6.0.0, you can also configure the built-in transport settings using the following XML tags under <transport_builtin>: <udpv4>, <udpv6>, <shmem>, <udpv4_wan>. This is recommended over using the PropertyQosPolicy. See 50.4.6 Transport Properties.

When using non-C/C++ and Java APIs, the transport configuration must take place through the PropertyQosPolicy (not through the transport property structures) or the <transport_builtin> XML tags (for Connext 6.0.0 and higher).

Alternative way to support multiple instances of built-in transports (without using Transport API).
Alternative way to dynamically load and configure extension transports (such as RTI TCP Transport1) in C/C++ language bindings. If the extension plugin is installed using the register_transport() API instead, the library of the extension transport will need to be linked into your application and may require recompilation.
Alternative way to provide a license for platforms that do not support a file system, or if a default license location is not feasible and environment variables are not supported.

The PropertyQosPolicyHelper operations are described in Table 47.35 PropertyQoSPolicyHelper Operations. For more information, see the API Reference HTML documentation.

Table 47.35 PropertyQoSPolicyHelper Operations
Operation	Description
get_number_of_properties	Gets the number of properties in the input policy.
assert_property	Asserts the property identified by name in the input policy. (Either adds it, or replaces an existing one.)
add_property	Adds a new property to the input policy.
assert_pointer_property	Asserts the property identified by name in the input policy. Used when the property to store is a pointer.
add_pointer_property	Adds a new property to the input policy. Used when the property to store is a pointer.
lookup_property	Searches for a property in the input policy given its name.
remove_property	Removes a property from the input policy.
get_properties	Retrieves a list of properties whose names match the input prefix.

47.19.1 Property Validation

All the properties that Connext provides (which begin with dds., com.rti., or rti.) are validated when the entity or the plugin is created. This validation is done to avoid using an unknown or incorrect property name (for example, due to a typo). Without this validation, Connext ignores the unknown property name, and you might not know why the property's configuration isn't being applied.

By default, at the creation of an entity or a plugin, if you specify an incorrect property name, Connext logs an exception similar to the following:

Entity:

DDS_PropertyQosPolicy_validatePropertyNames:Unexpected property: dds.type_consistnecy.ignore_sequence_bounds. Closest valid property: dds.type_consistency.ignore_sequence_bounds

DDS_DataReaderQos_is_consistentI:inconsistent QoS property

DDS_Subscriber_create_datareader_disabledI:ERROR: Inconsistent QoS

Plugin, such as TCPv4:

DDS_PropertyQosPolicy_validate_plugin_property_suffixes:Unexpected property: dds.transport.TCPv4.tcp1.invalidPropertyTest. Closest valid property: dds.transport.TCPv4.tcp1.aliases

NDDS_Transport_TCPv4_Property_parseDDSProperties:Inconsistent QoS property: dds.transport.TCPv4.

NDDS_Transport_TCPv4_create:!get transport TCPv4 plugin property from DDS Property

You can configure the behavior of this validation by setting a property at the DomainParticipant level. The DomainParticipant's DataWriters and DataReaders use the participant's setting. Or you can set the property at the plugin level.

At the entity-level setting, you can set the property dds.participant.property_validation_action to any of the following options:

(default) VALIDATION_ACTION_EXCEPTION: validate properties. Upon failure, log errors and fail.
VALIDATION_ACTION_SKIP: skip validation.
VALIDATION_ACTION_WARNING: validate properties. Upon failure, log warnings and do not fail.

At the plugin level setting, you can set the property <plugin_name>.property_validation_action:

Options:

VALIDATION_ACTION_EXCEPTION: validate properties. Upon failure, log errors and fail.
VALIDATION_ACTION_SKIP: skip validation.
VALIDATION_ACTION_WARNING: validate properties. Upon failure, log warnings and do not fail.

If the property is not set, the plugin property validation behavior will be the same as that of the DomainParticipant, which by default is VALIDATION_ACTION_EXCEPTION.
For example, to set the property_validation_action for the dds.transport.TCPv4.tcp1 transport plugin via XML:

<domain_participant_qos>

    <property>

        <value>

            <element>

                <name>dds.transport.load_plugins</name>

                <value>dds.transport.TCPv4.tcp1</value>

            </element>

            <element>

                <name>dds.transport.TCPv4.tcp1.property_validation_action</name>

                <value>VALIDATION_ACTION_WARNING</value>

            </element>

        </value>

    </property>

</domain_participant_qos>

In general, it is recommended that you use dds.participant.property_validation_action to control the validation of the properties for both the Connext core libraries and any plugins you might use. However, there are cases where you might want to configure different behaviors for the core libraries and the plugins. For example, if you are running a customized version of the plugins that supports a new, experimental property, you will need to disable the DomainParticipant validation via dds.participant.property_validation_action, but still keep the plugin validation (for example, dds.transport.TCPv4.tcp1.property_validation_action). Here's an example of disabling the DomainParticipant level validation and enabling a plugin level validation:

<domain_participant_qos>

    <property>

        <value>

            <element>

                <name>dds.participant.property_validation_action</name>

                <value>VALIDATION_ACTION_SKIP</value>

            </element>

            <element>

                <name>dds.transport.TCPv4.tcp1.property_validation_action</name>

                <value>VALIDATION_ACTION_EXCEPTION</value>

            </element>

        </value>

    </property>

</domain_participant_qos>

Note that the validation is sequential: first the property is validated when the DomainParticipant is created, then it is validated when the plugin is created. For example, consider that the DomainParticipant sets the property dds.participant.property_validation_action to VALIDATION_ACTION_EXCEPTION, but the plugin is configured to skip the unknown property. In this case, DomainParticipant creation will fail, and the plugin will never get created. As described above, if you are customizing the plugin, set the validation to VALIDATION_ACTION_SKIP at the DomainParticipant level, then set the plugin property validation to VALIDATION_ACTION_EXCEPTION. By doing that, the properties will be validated just at the plugin level.

You can find a complete list of the Connext predefined properties in the Property Reference Guide.

47.19.2 Properties

This QosPolicy can be changed at any time.

There is no requirement that the publishing and subscribing sides use compatible values.

47.19.3 Related QosPolicies

44.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension)

47.19.4 Applicable Entities

47.19.5 System Resource Considerations

The 44.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) contains several fields for configuring the resources associated with the properties stored in this QosPolicy.