<<extension>> Stores (name, value) pairs that can be used to configure certain parameters of RTI Connext that are not exposed through formal QoS policies. Can also be used to store and propagate application-specific name/value pairs that can be retrieved by user code during discovery. More...

Classes
struct	DDS_Property_t
	Properties are name/value pairs objects. More...

struct	DDS_PropertySeq
	Declares IDL `sequence` < DDS_Property_t > More...

struct	DDS_PropertyQosPolicy
	Stores name/value(string) pairs that can be used to configure certain parameters of RTI Connext that are not exposed through formal QoS policies. Can also be used to store and propagate application-specific name/value pairs that can be retrieved by user code during discovery. More...

class	DDSPropertyQosPolicyHelper
	Policy helpers that facilitate management of the properties in the input policy. More...

Typedefs
typedef struct DDS_PropertyQosPolicy	DDS_PropertyQosPolicy
	Stores name/value(string) pairs that can be used to configure certain parameters of RTI Connext that are not exposed through formal QoS policies. Can also be used to store and propagate application-specific name/value pairs that can be retrieved by user code during discovery. More...

typedef enum DDS_PropertyQosPolicyMutability	DDS_PropertyQosPolicyMutability
	Determines if, and when, the value of a property can change. More...

Enumerations
enum	DDS_PropertyQosPolicyMutability { DDS_PROPERTY_QOS_MUTABLE , DDS_PROPERTY_QOS_MUTABLE_UNTIL_ENABLE , DDS_PROPERTY_QOS_IMMUTABLE }
	Determines if, and when, the value of a property can change. More...

Functions
DDS_PropertyQosPolicyMutability	DDS_PropertyQosPolicyHelper_get_property_mutability (const char name, const struct DDS_PropertyQosPolicy policy)
	Returns the mutability type of a property. More...

static DDS_Long	DDSPropertyQosPolicyHelper::get_number_of_properties (DDS_PropertyQosPolicy &policy)
	Gets the number of properties in the input policy. More...

static DDS_ReturnCode_t	DDSPropertyQosPolicyHelper::assert_property (DDS_PropertyQosPolicy &policy, const char name, const char value, DDS_Boolean propagate)
	Asserts the property identified by name in the input policy. More...

static DDS_ReturnCode_t	DDSPropertyQosPolicyHelper::add_property (DDS_PropertyQosPolicy &policy, const char name, const char value, DDS_Boolean propagate)
	Adds a new property to the input policy. More...

static DDS_ReturnCode_t	DDSPropertyQosPolicyHelper::assert_pointer_property (DDS_PropertyQosPolicy &policy, const char name, const void pointer)
	Asserts the property identified by name in the input policy. Used when the property to store is a pointer. More...

static DDS_ReturnCode_t	DDSPropertyQosPolicyHelper::add_pointer_property (DDS_PropertyQosPolicy &policy, const char name, const void pointer)
	Adds a new property to the input policy. Used when the property to store is a pointer. More...

static struct DDS_Property_t *	DDSPropertyQosPolicyHelper::lookup_property (DDS_PropertyQosPolicy &policy, const char *name)
	Searches for a property in the input policy given its name. More...

static DDS_ReturnCode_t	DDSPropertyQosPolicyHelper::remove_property (DDS_PropertyQosPolicy &policy, const char *name)
	Removes a property from the input policy. More...

static DDS_ReturnCode_t	DDSPropertyQosPolicyHelper::get_properties (DDS_PropertyQosPolicy &policy, struct DDS_PropertySeq &properties, const char *name_prefix)
	Retrieves a list of properties whose names match the input prefix. More...

Variables
const char *const	DDS_PROPERTY_QOS_POLICY_NAME
	Stringified human-readable name for DDS_PropertyQosPolicy. More...

Detailed Description

<<extension>> Stores (name, value) pairs that can be used to configure certain parameters of RTI Connext that are not exposed through formal QoS policies. Can also be used to store and propagate application-specific name/value pairs that can be retrieved by user code during discovery.

RTI Connext will automatically set some system properties in the DDS_PropertyQosPolicy associated with a DDS_DomainParticipantQos. See System Properties for additional details.

Typedef Documentation

◆ DDS_PropertyQosPolicy

typedef struct DDS_PropertyQosPolicy DDS_PropertyQosPolicy

Stores name/value(string) pairs that can be used to configure certain parameters of RTI Connext that are not exposed through formal QoS policies. Can also be used to store and propagate application-specific name/value pairs that can be retrieved by user code during discovery.

Entity:: DDSDomainParticipant DDSDataReader DDSDataWriter

Properties:: RxO = N/A;
Changeable = YES

See also: DDSDomainParticipant::get_builtin_subscriber

Usage

The PROPERTY QoS policy can be used to associate a set of properties in the form of (name, value) pairs with a DDSDataReader, DDSDataWriter, or DDSDomainParticipant. This is similar to the DDS_UserDataQosPolicy, except this policy uses (name, value) pairs, and you can select whether or not a particular pair should be propagated (included in the builtin topic).

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

This QoS policy may be used to configure:

Durable Writer History, see Configuring Durable Writer History

Durable Reader State, see Configuring Durable Reader State

Builtin Transport Plugins, see UDPv4 Transport Property Names in Property QoS Policy of Domain Participant, UDPv6 Transport Property Names in Property QoS Policy of Domain Participant, and Shared Memory Transport Property Names in Property QoS Policy of Domain Participant
Extension Transport Plugins, see Loading Transport Plugins through Property QoS Policy of Domain Participant

Clock Selection

In addition, you may add your own name/value pairs to the Property QoS policy of an Entity. Via this QoS policy, you can direct RTI 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 DDS_UserDataQosPolicy or DDS_GroupDataQosPolicy).

Reasons for Using the PropertyQosPolicy

Supports dynamic loading of extension transports

Supports multiple instances of the builtin transports

Allows full pluggable transport configuration for non-C/C++ language bindings (Java, .NET, etc.)

Avoids the process of creating entities disabled, changing their QoS settings, then enabling them

Allows selection of clock

Some of the RTI Connext capabilities configurable via the Property QoS policy can also be configured in code via APIs. However, the Property QoS policy allows you to configure those parameters via XML files. In addition, some of the configuration APIs will only work if the Entity was created in a disabled state and then enabled after the configuration change was applied. By configuring those parameters using the Property QoS policy during entity creation, you avoid the additional work of first creating a disabled entity and then enabling it afterwards.

There are helper functions to facilitate working with properties, see the PROPERTY page.

◆ DDS_PropertyQosPolicyMutability

typedef enum DDS_PropertyQosPolicyMutability DDS_PropertyQosPolicyMutability

Determines if, and when, the value of a property can change.

Enumeration Type Documentation

◆ DDS_PropertyQosPolicyMutability

enum DDS_PropertyQosPolicyMutability

Determines if, and when, the value of a property can change.

Enumerator
DDS_PROPERTY_QOS_MUTABLE	The property is mutable: it can be changed at any time.
DDS_PROPERTY_QOS_MUTABLE_UNTIL_ENABLE	The property can only be changed before enabling the entity.
DDS_PROPERTY_QOS_IMMUTABLE	The property is immutable: it can only be specified when creating the entity.

Function Documentation

◆ DDS_PropertyQosPolicyHelper_get_property_mutability()

DDS_PropertyQosPolicyMutability DDS_PropertyQosPolicyHelper_get_property_mutability	(	const char *	name,
		const struct DDS_PropertyQosPolicy *	policy
	)

Returns the mutability type of a property.

If the property does not exist, DDS_PROPERTY_QOS_MUTABLE is returned. Otherwise, it returns the mutability type of the specified property. See DDS_PropertyQosPolicyMutability for more information of the different mutability types.

Parameters

name	<<in>>. The name of the property for which we want to know the mutability type.
policy	<<in>>. These are the properties in which we are going to look for the property with the provided name.

Returns: The mutability type of the input property.

◆ get_number_of_properties()

static DDS_Long DDSPropertyQosPolicyHelper::get_number_of_properties ( DDS_PropertyQosPolicy & policy )

static

Gets the number of properties in the input policy.

Precondition: policy cannot be NULL.

Parameters

policy <<in>> Input policy.

Returns: Number of properties.

◆ assert_property()

static DDS_ReturnCode_t DDSPropertyQosPolicyHelper::assert_property	(	DDS_PropertyQosPolicy &	policy,
		const char *	name,
		const char *	value,
		DDS_Boolean	propagate
	)

static

Asserts the property identified by name in the input policy.

If the property already exists, this function replaces its current value with the new one.

If the property identified by name does not exist, this function adds it to the property set.

This function increases the maximum number of elements of the policy sequence when this number is not enough to store the new property.

Precondition: policy, name and value cannot be NULL.

Parameters

policy	<<in>> Input policy.
name	<<in>> Property name.
value	<<in>> Property value.
propagate	<<in>> Indicates if the property will be propagated on discovery.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES

◆ add_property()

static DDS_ReturnCode_t DDSPropertyQosPolicyHelper::add_property	(	DDS_PropertyQosPolicy &	policy,
		const char *	name,
		const char *	value,
		DDS_Boolean	propagate
	)

static

Adds a new property to the input policy.

This function will allocate memory to store the (name, value) pair. The memory allocated is owned by RTI Connext.

If the maximum number of elements of the policy sequence is not enough to store the new property, this function will increase it.

If the property already exists the function fails with DDS_RETCODE_PRECONDITION_NOT_MET.

Precondition: policy, name and value cannot be NULL.; The property is not in the policy.

Parameters

policy	<<in>> Input policy.
name	<<in>> Property name.
value	<<in>> Property value.
propagate	<<in>> Indicates if the property will be propagated on discovery.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_OUT_OF_RESOURCES

◆ assert_pointer_property()

static DDS_ReturnCode_t DDSPropertyQosPolicyHelper::assert_pointer_property	(	DDS_PropertyQosPolicy &	policy,
		const char *	name,
		const void *	pointer
	)

static

Asserts the property identified by name in the input policy. Used when the property to store is a pointer.

This is a function similar to DDSPropertyQosPolicyHelper::assert_property. However, instead of passing a stringified version of the pointer, this function receives a pointer as the value.

If the property already exists, this function replaces its current value with the new one.

If the property identified by name does not exist, this function adds it to the property set.

This function increases the maximum number of elements of the policy sequence when this number is not enough to store the new property.

The properties asserted by this function will not be propagated on discovery.

Precondition: policy and name cannot be NULL.

Parameters

policy	<<in>> Input policy.
name	<<in>> Property name.
pointer	<<in>> The pointer to store in the property.

Returns: One of the Standard Return Codes or DDS_RETCODE_OUT_OF_RESOURCES.

◆ add_pointer_property()

static DDS_ReturnCode_t DDSPropertyQosPolicyHelper::add_pointer_property	(	DDS_PropertyQosPolicy &	policy,
		const char *	name,
		const void *	pointer
	)

static

Adds a new property to the input policy. Used when the property to store is a pointer.

This is a function similar to DDSPropertyQosPolicyHelper::add_property. However, instead of passing a stringified version of the pointer, this function receives a pointer as the value.

This function will allocate memory to store the (name, value) pair. The memory allocated is owned by RTI Connext.

If the maximum number of elements of the policy sequence is not enough to store the new property, this function will increase it.

If the property already exists the function fails with DDS_RETCODE_PRECONDITION_NOT_MET.

The properties added by this function will not be propagated on discovery.

Precondition: policy and name cannot be NULL.; The property is not in the policy.

Parameters

policy	<<in>> Input policy.
name	<<in>> Property name.
pointer	<<in>> The pointer to store in the property.

Returns: One of the Standard Return Codes or DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET

◆ lookup_property()

static struct DDS_Property_t * DDSPropertyQosPolicyHelper::lookup_property	(	DDS_PropertyQosPolicy &	policy,
		const char *	name
	)

static

Searches for a property in the input policy given its name.

Precondition: policy, name and value cannot be NULL.

Parameters

policy	<<in>> Input policy.
name	<<in>> Property name.

Returns: The function returns the first property with the given name. If such a property does not exist, the function returns NULL.

◆ remove_property()

static DDS_ReturnCode_t DDSPropertyQosPolicyHelper::remove_property	(	DDS_PropertyQosPolicy &	policy,
		const char *	name
	)

static

Removes a property from the input policy.

If the property does not exist, the function fails with DDS_RETCODE_PRECONDITION_NOT_MET.

Precondition: policy and name cannot be NULL.; The property is in the policy.

Parameters

policy	<<in>> Input policy.
name	<<in>> Property name.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET

◆ get_properties()

static DDS_ReturnCode_t DDSPropertyQosPolicyHelper::get_properties	(	DDS_PropertyQosPolicy &	policy,
		struct DDS_PropertySeq &	properties,
		const char *	name_prefix
	)

static

Retrieves a list of properties whose names match the input prefix.

If the properties sequence doesn't own its buffer, and its maximum is less than the total number of properties matching the input prefix, it will be filled up to its maximum and fail with an error of DDS_RETCODE_OUT_OF_RESOURCES.

Precondition: policy, properties and name_prefix cannot be NULL.

Parameters

policy	<<in>> Input policy.
properties	<<inout>> A DDS_PropertySeq object where the set or list of properties will be returned.
name_prefix	Name prefix.

Exceptions

One	of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET

Variable Documentation

◆ DDS_PROPERTY_QOS_POLICY_NAME

const char* const DDS_PROPERTY_QOS_POLICY_NAME

extern

Stringified human-readable name for DDS_PropertyQosPolicy.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ DDS_PropertyQosPolicy

Usage

Reasons for Using the PropertyQosPolicy

◆ DDS_PropertyQosPolicyMutability

Enumeration Type Documentation

◆ DDS_PropertyQosPolicyMutability

Function Documentation

◆ DDS_PropertyQosPolicyHelper_get_property_mutability()

◆ get_number_of_properties()

◆ assert_property()

◆ add_property()

◆ assert_pointer_property()

◆ add_pointer_property()

◆ lookup_property()

◆ remove_property()

◆ get_properties()

Variable Documentation

◆ DDS_PROPERTY_QOS_POLICY_NAME