RTI Connext C API Version 7.1.0

<<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...

Data Structures

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...
 

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...
 

Functions

DDS_Long DDS_PropertyQosPolicyHelper_get_number_of_properties (const struct DDS_PropertyQosPolicy *policy)
 Gets the number of properties in the input policy. More...
 
DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_assert_property (struct DDS_PropertyQosPolicy *policy, const char *name, const char *value, DDS_Boolean propagate)
 Asserts the property identified by name in the input policy. More...
 
DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_add_property (struct DDS_PropertyQosPolicy *policy, const char *name, const char *value, DDS_Boolean propagate)
 Adds a new property to the input policy. More...
 
DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_assert_pointer_property (struct 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...
 
DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_add_pointer_property (struct 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...
 
struct DDS_Property_tDDS_PropertyQosPolicyHelper_lookup_property (const struct DDS_PropertyQosPolicy *policy, const char *name)
 Searches for a property in the input policy given its name. More...
 
struct DDS_Property_tDDS_PropertyQosPolicyHelper_lookup_property_with_prefix (const struct DDS_PropertyQosPolicy *policy, const char *prefix, const char *name)
 Searches for a property in the input policy given its prefix and name. More...
 
DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_remove_property (struct DDS_PropertyQosPolicy *policy, const char *name)
 Removes a property from the input policy. More...
 
DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_get_properties (const struct DDS_PropertyQosPolicy *policy, struct DDS_PropertySeq *properties, const char *name_prefix)
 Retrieves a list of properties whose names match the input prefix. More...
 
DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_get_properties_into_policy (const struct DDS_PropertyQosPolicy *policy, struct DDS_PropertyQosPolicy *outPolicy, const char *name_prefix)
 This function gets the properties from a policy with a given prefix and sets them into the properties of the output policy. 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

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:
DDS_DomainParticipant DDS_DataReader DDS_DataWriter
Properties:
RxO = N/A;
Changeable = YES
See also
DDS_DomainParticipant_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 DDS_DataReader, DDS_DataWriter, or DDS_DomainParticipant. 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).

This QoS policy may be used to configure:

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.

Function Documentation

◆ DDS_PropertyQosPolicyHelper_get_number_of_properties()

DDS_Long DDS_PropertyQosPolicyHelper_get_number_of_properties ( const struct DDS_PropertyQosPolicy policy)

Gets the number of properties in the input policy.

Precondition
policy cannot be NULL.
Parameters
policy<<in>> Input policy.
Returns
Number of properties.

◆ DDS_PropertyQosPolicyHelper_assert_property()

DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_assert_property ( struct DDS_PropertyQosPolicy policy,
const char *  name,
const char *  value,
DDS_Boolean  propagate 
)

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.
Returns
One of the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES

◆ DDS_PropertyQosPolicyHelper_add_property()

DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_add_property ( struct DDS_PropertyQosPolicy policy,
const char *  name,
const char *  value,
DDS_Boolean  propagate 
)

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.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_OUT_OF_RESOURCES

◆ DDS_PropertyQosPolicyHelper_assert_pointer_property()

DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_assert_pointer_property ( struct 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.

This is a function similar to DDS_PropertyQosPolicyHelper_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.

◆ DDS_PropertyQosPolicyHelper_add_pointer_property()

DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_add_pointer_property ( struct 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.

This is a function similar to DDS_PropertyQosPolicyHelper_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

◆ DDS_PropertyQosPolicyHelper_lookup_property()

struct DDS_Property_t * DDS_PropertyQosPolicyHelper_lookup_property ( const struct DDS_PropertyQosPolicy policy,
const char *  name 
)

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.

◆ DDS_PropertyQosPolicyHelper_lookup_property_with_prefix()

struct DDS_Property_t * DDS_PropertyQosPolicyHelper_lookup_property_with_prefix ( const struct DDS_PropertyQosPolicy policy,
const char *  prefix,
const char *  name 
)

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

Precondition
policy, name and value cannot be NULL.
Parameters
policy<<in>> Input policy.
prefix<<in>> Property name prefix.
name<<in>> Property name.
Returns
The function returns the first property with the given prefix and name. If such a property does not exist, the function returns NULL.

◆ DDS_PropertyQosPolicyHelper_remove_property()

DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_remove_property ( struct DDS_PropertyQosPolicy policy,
const char *  name 
)

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.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET

◆ DDS_PropertyQosPolicyHelper_get_properties()

DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_get_properties ( const struct DDS_PropertyQosPolicy policy,
struct DDS_PropertySeq properties,
const char *  name_prefix 
)

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_prefixName prefix.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET

◆ DDS_PropertyQosPolicyHelper_get_properties_into_policy()

DDS_ReturnCode_t DDS_PropertyQosPolicyHelper_get_properties_into_policy ( const struct DDS_PropertyQosPolicy policy,
struct DDS_PropertyQosPolicy outPolicy,
const char *  name_prefix 
)

This function gets the properties from a policy with a given prefix and sets them into the properties of the output policy.

Precondition
inProperties, outProperties and name_prefix cannot be NULL.
Parameters
policy<<in>> Input policy.
outPolicy<<out>> Output policy where the properties with the given prefix will be stored. The structure must be initialized.
name_prefix<<in>> Name prefix.
Returns
DDS_RETCODE_OK if success, DDS_RETCODE_ERROR otherwise.

Variable Documentation

◆ DDS_PROPERTY_QOS_POLICY_NAME

const char* const DDS_PROPERTY_QOS_POLICY_NAME
extern

Stringified human-readable name for DDS_PropertyQosPolicy.