RTI Connext C API Version 7.3.0

DDS_DomainParticipant entity and associated elements More...

Data Structures

struct  DDS_InvalidLocalIdentityAdvanceNoticeStatus
 DDS_INVALID_LOCAL_IDENTITY_ADVANCE_NOTICE_STATUS More...
 
struct  DDS_DomainParticipantListener
 <<interface>> Listener for participant status. More...
 
struct  DDS_DomainParticipantQos
 QoS policies supported by a DDS_DomainParticipant entity. More...
 
struct  DDS_DomainParticipantProtocolStatus
 <<extension>> The status of a participant's protocol related metrics, like the number of corrupted messages, change in corrupted messages and timestamp of the last corrupted message. More...
 
struct  DDS_DomainParticipantSeq
 Declares IDL sequence < DDS_DomainParticipant > . More...
 

Macros

#define DDS_InvalidLocalIdentityAdvanceNoticeStatus_INITIALIZER
 Initializer for new DDS_InvalidLocalIdentityAdvanceNoticeStatus. More...
 
#define DDS_DomainParticipantListener_INITIALIZER
 Initializer for new DDS_DomainParticipantListener. More...
 
#define DDS_DomainParticipantQos_INITIALIZER
 Initializer for new QoS instances. More...
 
#define DDS_DomainParticipantProtocolStatus_INITIALIZER
 Initializer for new status instances. More...
 

Typedefs

typedef DDS_DOMAINID_TYPE_NATIVE DDS_DomainId_t
 An integer that indicates in which domain a DDS_DomainParticipant communicates. More...
 
typedef void(* DDS_DomainParticipantListener_InvalidLocalIdentityAdvanceNoticeStatusCallback) (void *listener_data, DDS_DomainParticipant *participant, const struct DDS_InvalidLocalIdentityAdvanceNoticeStatus *invalid_local_identity_advance_notice_status)
 Notifies the user that the identity of the DDS_DomainParticipant is about to expire. More...
 
typedef struct DDS_DomainParticipantImpl DDS_DomainParticipant
 <<interface>> Container for all DDS_DomainEntity objects. More...
 

Functions

DDS_Boolean DDS_InvalidLocalIdentityAdvanceNoticeStatus_equals (const struct DDS_InvalidLocalIdentityAdvanceNoticeStatus *left, const struct DDS_InvalidLocalIdentityAdvanceNoticeStatus *right)
 Compares two DDS_InvalidLocalIdentityAdvanceNoticeStatus for equality. More...
 
DDS_Boolean DDS_DomainParticipantQos_equals (const struct DDS_DomainParticipantQos *self, const struct DDS_DomainParticipantQos *other)
 Compares two DDS_DomainParticipantQos for equality. More...
 
DDS_ReturnCode_t DDS_DomainParticipantQos_print (const struct DDS_DomainParticipantQos *self)
 Prints this DDS_DomainParticipantQos to stdout. More...
 
DDS_ReturnCode_t DDS_DomainParticipantQos_to_string (const struct DDS_DomainParticipantQos *self, char *string, DDS_UnsignedLong *string_size)
 Obtains a string representation of this DDS_DomainParticipantQos. More...
 
DDS_ReturnCode_t DDS_DomainParticipantQos_to_string_w_params (const struct DDS_DomainParticipantQos *self, char *string, DDS_UnsignedLong *string_size, const struct DDS_DomainParticipantQos *base, const struct DDS_QosPrintFormat *format)
 Obtains a string representation of this DDS_DomainParticipantQos. More...
 
DDS_ReturnCode_t DDS_DomainParticipantQos_initialize (struct DDS_DomainParticipantQos *self)
 Initializer for new QoS instances. More...
 
DDS_ReturnCode_t DDS_DomainParticipantQos_finalize (struct DDS_DomainParticipantQos *self)
 Free any dynamic memory allocated by the policies in this DDS_DomainParticipantQos. More...
 
DDS_ReturnCode_t DDS_DomainParticipantQos_copy (struct DDS_DomainParticipantQos *self, const struct DDS_DomainParticipantQos *source)
 Copy the contents of the given QoS into this QoS. More...
 
DDS_EntityDDS_DomainParticipant_as_entity (DDS_DomainParticipant *domain)
 Access a DDS_DomainParticipant's supertype instance. More...
 
DDS_ReturnCode_t DDS_DomainParticipantProtocolStatus_initialize (struct DDS_DomainParticipantProtocolStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_DomainParticipantProtocolStatus_copy (struct DDS_DomainParticipantProtocolStatus *self, const struct DDS_DomainParticipantProtocolStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_DomainParticipantProtocolStatus_finalize (struct DDS_DomainParticipantProtocolStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_DomainParticipantProtocolStatus_equals (const struct DDS_DomainParticipantProtocolStatus *left, const struct DDS_DomainParticipantProtocolStatus *right)
 Compares two DDS_DomainParticipantProtocolStatus for equality. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_default_topic_qos (DDS_DomainParticipant *self, struct DDS_TopicQos *qos)
 Copies the default DDS_TopicQos values for this domain participant into the given DDS_TopicQos instance. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_topic_qos (DDS_DomainParticipant *self, const struct DDS_TopicQos *qos)
 Set the default DDS_TopicQos values for this domain participant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_topic_qos_with_profile (DDS_DomainParticipant *self, const char *library_name, const char *profile_name)
 <<extension>> Set the default DDS_TopicQos values for this domain participant based on the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_default_publisher_qos (DDS_DomainParticipant *self, struct DDS_PublisherQos *qos)
 Copy the default DDS_PublisherQos values into the provided DDS_PublisherQos instance. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_publisher_qos (DDS_DomainParticipant *self, const struct DDS_PublisherQos *qos)
 Set the default DDS_PublisherQos values for this DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_publisher_qos_with_profile (DDS_DomainParticipant *self, const char *library_name, const char *profile_name)
 <<extension>> Set the default DDS_PublisherQos values for this DomainParticipant based on the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_default_datawriter_qos (DDS_DomainParticipant *self, struct DDS_DataWriterQos *qos)
 <<extension>> Copy the default DDS_DataWriterQos values into the provided DDS_DataWriterQos instance. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_datawriter_qos (DDS_DomainParticipant *self, const struct DDS_DataWriterQos *qos)
 <<extension>> Set the default DataWriterQos values for this DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_datawriter_qos_with_profile (DDS_DomainParticipant *self, const char *library_name, const char *profile_name)
 <<extension>> Set the default DDS_DataWriterQos values for this domain participant based on the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_default_subscriber_qos (DDS_DomainParticipant *self, struct DDS_SubscriberQos *qos)
 Copy the default DDS_SubscriberQos values into the provided DDS_SubscriberQos instance. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_subscriber_qos (DDS_DomainParticipant *self, const struct DDS_SubscriberQos *qos)
 Set the default DDS_SubscriberQos values for this DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_subscriber_qos_with_profile (DDS_DomainParticipant *self, const char *library_name, const char *profile_name)
 <<extension>> Set the default DDS_SubscriberQos values for this DomainParticipant based on the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_default_datareader_qos (DDS_DomainParticipant *self, struct DDS_DataReaderQos *qos)
 <<extension>> Copy the default DDS_DataReaderQos values into the provided DDS_DataReaderQos instance. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_datareader_qos (DDS_DomainParticipant *self, const struct DDS_DataReaderQos *qos)
 <<extension>> Set the default DDS_DataReaderQos values for this domain participant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_datareader_qos_with_profile (DDS_DomainParticipant *self, const char *library_name, const char *profile_name)
 <<extension>> Set the default DDS_DataReaderQos values for this DomainParticipant based on the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_default_flowcontroller_property (DDS_DomainParticipant *self, struct DDS_FlowControllerProperty_t *prop)
 <<extension>> Copies the default DDS_FlowControllerProperty_t values for this domain participant into the given DDS_FlowControllerProperty_t instance. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_flowcontroller_property (DDS_DomainParticipant *self, const struct DDS_FlowControllerProperty_t *prop)
 <<extension>> Set the default DDS_FlowControllerProperty_t values for this domain participant. More...
 
const char * DDS_DomainParticipant_get_default_library (DDS_DomainParticipant *self)
 <<extension>> Gets the default XML library associated with a DDS_DomainParticipant. More...
 
const char * DDS_DomainParticipant_get_default_profile (DDS_DomainParticipant *self)
 <<extension>> Gets the default XML profile associated with a DDS_DomainParticipant. More...
 
const char * DDS_DomainParticipant_get_default_profile_library (DDS_DomainParticipant *self)
 <<extension>> Gets the library where the default XML QoS profile is contained for a DDS_DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_library (DDS_DomainParticipant *self, const char *library_name)
 <<extension>> Sets the default XML library for a DDS_DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_default_profile (DDS_DomainParticipant *self, const char *library_name, const char *profile_name)
 <<extension>> Sets the default XML profile for a DDS_DomainParticipant. More...
 
DDS_PublisherDDS_DomainParticipant_create_publisher (DDS_DomainParticipant *self, const struct DDS_PublisherQos *qos, const struct DDS_PublisherListener *listener, DDS_StatusMask mask)
 Creates a DDS_Publisher with the desired QoS policies and attaches to it the specified DDS_PublisherListener. More...
 
DDS_PublisherDDS_DomainParticipant_create_publisher_with_profile (DDS_DomainParticipant *self, const char *library_name, const char *profile_name, const struct DDS_PublisherListener *listener, DDS_StatusMask mask)
 <<extension>> Creates a new DDS_Publisher object using the DDS_PublisherQos associated with the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_publisher (DDS_DomainParticipant *self, DDS_Publisher *p)
 Deletes an existing DDS_Publisher. More...
 
DDS_SubscriberDDS_DomainParticipant_create_subscriber (DDS_DomainParticipant *self, const struct DDS_SubscriberQos *qos, const struct DDS_SubscriberListener *listener, DDS_StatusMask mask)
 Creates a DDS_Subscriber with the desired QoS policies and attaches to it the specified DDS_SubscriberListener. More...
 
DDS_SubscriberDDS_DomainParticipant_create_subscriber_with_profile (DDS_DomainParticipant *self, const char *library_name, const char *profile_name, const struct DDS_SubscriberListener *listener, DDS_StatusMask mask)
 <<extension>> Creates a new DDS_Subscriber object using the DDS_PublisherQos associated with the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_subscriber (DDS_DomainParticipant *self, DDS_Subscriber *s)
 Deletes an existing DDS_Subscriber. More...
 
DDS_DataWriterDDS_DomainParticipant_create_datawriter (DDS_DomainParticipant *self, DDS_Topic *topic, const struct DDS_DataWriterQos *qos, const struct DDS_DataWriterListener *listener, DDS_StatusMask mask)
 <<extension>> Creates a DDS_DataWriter that will be attached and belong to the implicit DDS_Publisher. More...
 
DDS_DataWriterDDS_DomainParticipant_create_datawriter_with_profile (DDS_DomainParticipant *self, DDS_Topic *topic, const char *library_name, const char *profile_name, const struct DDS_DataWriterListener *listener, DDS_StatusMask mask)
 <<extension>> Creates a DDS_DataWriter using a XML QoS profile that will be attached and belong to the implicit DDS_Publisher. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_datawriter (DDS_DomainParticipant *self, DDS_DataWriter *a_datawriter)
 <<extension>> Deletes a DDS_DataWriter that belongs to the implicit DDS_Publisher. More...
 
DDS_DataReaderDDS_DomainParticipant_create_datareader (DDS_DomainParticipant *self, DDS_TopicDescription *topic, const struct DDS_DataReaderQos *qos, const struct DDS_DataReaderListener *listener, DDS_StatusMask mask)
 <<extension>> Creates a DDS_DataReader that will be attached and belong to the implicit DDS_Subscriber. More...
 
DDS_DataReaderDDS_DomainParticipant_create_datareader_with_profile (DDS_DomainParticipant *self, DDS_TopicDescription *topic, const char *library_name, const char *profile_name, const struct DDS_DataReaderListener *listener, DDS_StatusMask mask)
 <<extension>> Creates a DDS_DataReader using a XML QoS profile that will be attached and belong to the implicit DDS_Subscriber. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_datareader (DDS_DomainParticipant *self, DDS_DataReader *a_datareader)
 <<extension>> Deletes a DDS_DataReader that belongs to the implicit DDS_Subscriber. More...
 
DDS_TopicDDS_DomainParticipant_create_topic (DDS_DomainParticipant *self, const char *topic_name, const char *type_name, const struct DDS_TopicQos *qos, const struct DDS_TopicListener *listener, DDS_StatusMask mask)
 Creates a DDS_Topic with the desired QoS policies and attaches to it the specified DDS_TopicListener. More...
 
DDS_TopicDDS_DomainParticipant_create_topic_with_profile (DDS_DomainParticipant *self, const char *topic_name, const char *type_name, const char *library_name, const char *profile_name, const struct DDS_TopicListener *listener, DDS_StatusMask mask)
 <<extension>> Creates a new DDS_Topic object using the DDS_PublisherQos associated with the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_topic (DDS_DomainParticipant *self, DDS_Topic *topic)
 Deletes a DDS_Topic. More...
 
DDS_ContentFilteredTopicDDS_DomainParticipant_create_contentfilteredtopic (DDS_DomainParticipant *self, const char *name, DDS_Topic *related_topic, const char *filter_expression, const struct DDS_StringSeq *expression_parameters)
 Creates a DDS_ContentFilteredTopic, that can be used to do content-based subscriptions. More...
 
DDS_ContentFilteredTopicDDS_DomainParticipant_create_contentfilteredtopic_with_filter (DDS_DomainParticipant *self, const char *name, const DDS_Topic *related_topic, const char *filter_expression, const struct DDS_StringSeq *expression_parameters, const char *filter_name)
 <<extension>> Creates a DDS_ContentFilteredTopic using the specified filter to do content-based subscriptions. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_contentfilteredtopic (DDS_DomainParticipant *self, DDS_ContentFilteredTopic *a_contentfilteredtopic)
 Deletes a DDS_ContentFilteredTopic. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_register_contentfilter (DDS_DomainParticipant *self, const char *filter_name, const struct DDS_ContentFilter *contentfilter)
 <<extension>> Register a content filter which can be used to create a DDS_ContentFilteredTopic. More...
 
void * DDS_DomainParticipant_lookup_contentfilter (DDS_DomainParticipant *self, const char *filter_name)
 <<extension>> Lookup a content filter previously registered with DDS_DomainParticipant_register_contentfilter. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_unregister_contentfilter (DDS_DomainParticipant *self, const char *filter_name)
 <<extension>> Unregister a content filter previously registered with DDS_DomainParticipant_register_contentfilter. More...
 
DDS_MultiTopicDDS_DomainParticipant_create_multitopic (DDS_DomainParticipant *self, const char *name, const char *type_name, const char *subscription_expression, const struct DDS_StringSeq *expression_parameters)
 [Not supported (optional)] Creates a MultiTopic that can be used to subscribe to multiple topics and combine/filter the received data into a resulting type. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_multitopic (DDS_DomainParticipant *self, DDS_MultiTopic *a_multitopic)
 [Not supported (optional)] Deletes a DDS_MultiTopic. More...
 
DDS_FlowControllerDDS_DomainParticipant_create_flowcontroller (DDS_DomainParticipant *self, const char *name, const struct DDS_FlowControllerProperty_t *prop)
 <<extension>> Creates a DDS_FlowController with the desired property. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_flowcontroller (DDS_DomainParticipant *self, DDS_FlowController *fc)
 <<extension>> Deletes an existing DDS_FlowController. More...
 
const DDS_TypeCodeDDS_DomainParticipant_get_typecode (DDS_DomainParticipant *self, const char *type_name)
 <<extension>> Retrieves the DDS_TypeCode of a type registered with the DDS_DomainParticipant based on the registration name. More...
 
DDS_TopicDDS_DomainParticipant_find_topic (DDS_DomainParticipant *self, const char *topic_name, const struct DDS_Duration_t *timeout)
 Finds an existing (or ready to exist) DDS_Topic, based on its name. More...
 
DDS_TopicDescriptionDDS_DomainParticipant_lookup_topicdescription (DDS_DomainParticipant *self, const char *topic_name)
 Looks up an existing, locally created DDS_TopicDescription, based on its name. More...
 
DDS_FlowControllerDDS_DomainParticipant_lookup_flowcontroller (DDS_DomainParticipant *self, const char *name)
 <<extension>> Looks up an existing locally-created DDS_FlowController, based on its name. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_participant_protocol_status (DDS_DomainParticipant *self, struct DDS_DomainParticipantProtocolStatus *status)
 <<extension>> Get the domain participant protocol status for this participant. More...
 
DDS_SubscriberDDS_DomainParticipant_get_builtin_subscriber (DDS_DomainParticipant *self)
 Accesses the built-in DDS_Subscriber. More...
 
DDS_PublisherDDS_DomainParticipant_get_implicit_publisher (DDS_DomainParticipant *self)
 <<extension>> Returns the implicit DDS_Publisher. If an implicit Publisher does not already exist, this creates one. More...
 
DDS_SubscriberDDS_DomainParticipant_get_implicit_subscriber (DDS_DomainParticipant *self)
 <<extension>> Returns the implicit DDS_Subscriber. If an implicit Subscriber does not already exist, this creates one. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_ignore_participant (DDS_DomainParticipant *self, const DDS_InstanceHandle_t *handle)
 Instructs RTI Connext to locally ignore a remote DDS_DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_ignore_topic (DDS_DomainParticipant *self, const DDS_InstanceHandle_t *handle)
 Instructs RTI Connext to locally ignore a DDS_Topic. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_ignore_publication (DDS_DomainParticipant *self, const DDS_InstanceHandle_t *handle)
 Instructs RTI Connext to locally ignore a publication. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_ignore_subscription (DDS_DomainParticipant *self, const DDS_InstanceHandle_t *handle)
 Instructs RTI Connext to locally ignore a subscription. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_banish_ignored_participants (DDS_DomainParticipant *self)
 <<extension>> Prevents ignored remote DomainParticipants from receiving traffic from the local DDS_DomainParticipant. More...
 
DDS_DomainId_t DDS_DomainParticipant_get_domain_id (DDS_DomainParticipant *self)
 Get the unique domain identifier. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_contained_entities (DDS_DomainParticipant *self)
 Delete all the entities that were created by means of the "create" operations on the DDS_DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_assert_liveliness (DDS_DomainParticipant *self)
 Manually asserts the liveliness of this DDS_DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_publishers (DDS_DomainParticipant *self, struct DDS_PublisherSeq *publishers)
 <<extension>> Allows the application to access all the publishers the participant has. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_subscribers (DDS_DomainParticipant *self, struct DDS_SubscriberSeq *subscribers)
 <<extension>> Allows the application to access all the subscribers the participant has. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_current_time (DDS_DomainParticipant *self, struct DDS_Time_t *current_time)
 Returns the current value of the time. More...
 
DDS_Boolean DDS_DomainParticipant_contains_entity (DDS_DomainParticipant *self, const DDS_InstanceHandle_t *a_handle)
 Completes successfully with DDS_BOOLEAN_TRUE if the referenced DDS_Entity is contained by the DDS_DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_register_durable_subscription (DDS_DomainParticipant *self, const struct DDS_EndpointGroup_t *group, const char *topic_name)
 <<extension>> Registers a Durable Subscription on the specified DDS_Topic on all Persistence Services. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_delete_durable_subscription (DDS_DomainParticipant *self, const struct DDS_EndpointGroup_t *group)
 <<extension>> Deletes an existing Durable Subscription on all Persistence Services. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_resume_endpoint_discovery (DDS_DomainParticipant *self, const DDS_InstanceHandle_t *remote_participant_handle)
 <<extension>> Initiates endpoint discovery with the specified remote DDS_DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_dns_tracker_polling_period (DDS_DomainParticipant *self, const struct DDS_Duration_t *polling_period)
 <<extension>> Configures the frequency in which the DNS tracker queries the DNS service. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_dns_tracker_polling_period (DDS_DomainParticipant *self, struct DDS_Duration_t *polling_period)
 <<extension>> Retrieves the frequency used by the DNS tracker thread to query the DNS service. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participants (DDS_DomainParticipant *self, struct DDS_InstanceHandleSeq *participant_handles)
 Returns a list of discovered DDS_DomainParticipant entities. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participants_from_subject_name (DDS_DomainParticipant *self, struct DDS_InstanceHandleSeq *participant_handles, const char *subject_name)
 <<extension>> Returns a list of discovered DDS_DomainParticipant entities that have the given DDS_EntityNameQosPolicy::name. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participant_data (DDS_DomainParticipant *self, struct DDS_ParticipantBuiltinTopicData *participant_data, const DDS_InstanceHandle_t *participant_handle)
 Returns DDS_ParticipantBuiltinTopicData for the specified DDS_DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participant_subject_name (DDS_DomainParticipant *self, char *subject_name, DDS_UnsignedLong *subject_name_size, const DDS_InstanceHandle_t *participant_handle)
 <<extension>> Returns DDS_EntityNameQosPolicy::name for the specified DDS_DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_topics (DDS_DomainParticipant *self, struct DDS_InstanceHandleSeq *topic_handles)
 Returns list of discovered DDS_Topic objects. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_topic_data (DDS_DomainParticipant *self, struct DDS_TopicBuiltinTopicData *topic_data, const DDS_InstanceHandle_t *topic_handle)
 Returns DDS_TopicBuiltinTopicData for the specified DDS_Topic. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_take_discovery_snapshot (DDS_DomainParticipant *self, const char *file_name)
 Take a snapshot of the remote participants discovered by a local one. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_add_peer (DDS_DomainParticipant *self, const char *peer_desc_string)
 <<extension>> Attempt to contact one or more additional peer participants. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_remove_peer (DDS_DomainParticipant *self, const char *peer_desc_string)
 <<extension>> Remove one or more peer participants from the list of peers with which this DDS_DomainParticipant will try to communicate. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_qos (DDS_DomainParticipant *self, const struct DDS_DomainParticipantQos *qos)
 Change the QoS of this DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_qos_with_profile (DDS_DomainParticipant *self, const char *library_name, const char *profile_name)
 <<extension>> Change the QoS of this domain participant using the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_qos (DDS_DomainParticipant *self, struct DDS_DomainParticipantQos *qos)
 Get the participant QoS. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_property (DDS_DomainParticipant *self, const char *property_name, const char *value, DDS_Boolean propagate)
 Set the value for a property that applies to a DomainParticipant. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_set_listener (DDS_DomainParticipant *self, const struct DDS_DomainParticipantListener *l, DDS_StatusMask mask)
 Sets the participant listener. More...
 
struct DDS_DomainParticipantListener DDS_DomainParticipant_get_listener (DDS_DomainParticipant *self)
 Get the participant listener. More...
 
DDS_ReturnCode_t DDS_DomainParticipant_get_listenerX (DDS_DomainParticipant *self, struct DDS_DomainParticipantListener *listener)
 <<extension>> Get the participant listener. More...
 
DDS_PublisherDDS_DomainParticipant_lookup_publisher_by_name (DDS_DomainParticipant *self, const char *publisher_name)
 <<extension>> Looks up a DDS_Publisher by its entity name within this DDS_DomainParticipant. More...
 
DDS_SubscriberDDS_DomainParticipant_lookup_subscriber_by_name (DDS_DomainParticipant *self, const char *subscriber_name)
 <<extension>> Retrieves a DDS_Subscriber by its entity name within this DDS_DomainParticipant. More...
 
DDS_DataWriterDDS_DomainParticipant_lookup_datawriter_by_name (DDS_DomainParticipant *self, const char *datawriter_full_name)
 <<extension>> Looks up a DDS_DataWriter by its entity name within this DDS_DomainParticipant. More...
 
DDS_DataReaderDDS_DomainParticipant_lookup_datareader_by_name (DDS_DomainParticipant *self, const char *datareader_full_name)
 <<extension>> Retrieves up a DDS_DataReader by its entity name in this DDS_DomainParticipant. More...
 

Variables

const struct DDS_DomainParticipantFactoryQosDDS_DOMAINPARTICIPANTFACTORY_QOS_PRINT_ALL
 Special value which can be supplied to DDS_DomainParticipantFactoryQos_to_string_w_params indicating that all of the QoS should be printed. More...
 
const struct DDS_DomainParticipantQosDDS_DOMAINPARTICIPANT_QOS_PRINT_ALL
 Special value which can be supplied to DDS_DomainParticipantQos_to_string_w_params indicating that all of the QoS should be printed. More...
 
const struct DDS_TopicQos DDS_TOPIC_QOS_DEFAULT
 Special value for creating a DDS_Topic with default QoS. More...
 
const struct DDS_PublisherQos DDS_PUBLISHER_QOS_DEFAULT
 Special value for creating a DDS_Publisher with default QoS. More...
 
const struct DDS_SubscriberQos DDS_SUBSCRIBER_QOS_DEFAULT
 Special value for creating a DDS_Subscriber with default QoS. More...
 
const struct DDS_FlowControllerProperty_t DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT
 <<extension>> Special value for creating a DDS_FlowController with default property. More...
 
const struct DDS_PublisherQosDDS_PUBLISHER_QOS_PRINT_ALL
 Special value which can be supplied to DDS_PublisherQos_to_string_w_params indicating that all of the QoS should be printed. More...
 
const char *const DDS_SQLFILTER_NAME
 <<extension>> The name of the built-in SQL filter that can be used with ContentFilteredTopics and MultiChannel DataWriters. More...
 
const char *const DDS_STRINGMATCHFILTER_NAME
 <<extension>> The name of the built-in StringMatch filter that can be used with ContentFilteredTopics and MultiChannel DataWriters. More...
 
const struct DDS_SubscriberQosDDS_SUBSCRIBER_QOS_PRINT_ALL
 Special value which can be supplied to DDS_SubscriberQos_to_string_w_params indicating that all of the QoS should be printed. More...
 
const struct DDS_TopicQosDDS_TOPIC_QOS_PRINT_ALL
 Special value which can be supplied to DDS_TopicQos_to_string_w_params indicating that all of the QoS should be printed. More...
 

Detailed Description

DDS_DomainParticipant entity and associated elements

Macro Definition Documentation

◆ DDS_InvalidLocalIdentityAdvanceNoticeStatus_INITIALIZER

#define DDS_InvalidLocalIdentityAdvanceNoticeStatus_INITIALIZER

◆ DDS_DomainParticipantListener_INITIALIZER

#define DDS_DomainParticipantListener_INITIALIZER

Initializer for new DDS_DomainParticipantListener.

No memory is allocated. New DDS_DomainParticipantListener instances stored in the stack should be initialized with this value before they are passed to any functions.

/* initialize listener functions */
DDS_DomainParticipant_set_listener(myParticipant, &listener, mask);
#define DDS_DomainParticipantListener_INITIALIZER
Initializer for new DDS_DomainParticipantListener.
Definition: domain.ifc:452
DDS_ReturnCode_t DDS_DomainParticipant_set_listener(DDS_DomainParticipant *self, const struct DDS_DomainParticipantListener *l, DDS_StatusMask mask)
Sets the participant listener.
DDS_DataReaderListener_DataAvailableCallback on_data_available
Handle the DDS_DATA_AVAILABLE_STATUS communication status.
Definition: subscription.ifc:2228
<<interface>> Listener for participant status.
Definition: domain.ifc:426
struct DDS_SubscriberListener as_subscriberlistener
A superclass instance of this DDS_DomainParticipantListener.
Definition: domain.ifc:441
struct DDS_DataReaderListener as_datareaderlistener
The superclass instance of this DDS_SubscriberListener.
Definition: subscription.ifc:2348
See also
DDS_DomainParticipant_set_listener
DDS_DomainParticipantListener

◆ DDS_DomainParticipantQos_INITIALIZER

#define DDS_DomainParticipantQos_INITIALIZER

Initializer for new QoS instances.

New DDS_DomainParticipantQos instances stored on the stack should be initialized with this value before they are passed to any functions. This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a new QoS structure is to initialize it on the stack at the time of its creation:

#define DDS_DomainParticipantQos_INITIALIZER
Initializer for new QoS instances.
Definition: domain.ifc:1587
QoS policies supported by a DDS_DomainParticipant entity.
Definition: domain.ifc:1378

Note that the above assignment is not a substitute for calling DDS_DomainParticipant_get_qos or DDS_DomainParticipantFactory_get_default_participant_qos; one of those functions should be called subsequently to setting the QoS of any new or existing entity. DDS_DomainParticipantQos_finalize should be called to free the contained QoS policies that use dynamic memory:

DDS_DomainParticipant_set_qos(myParticipant, &myQos);
DDS_ReturnCode_t DDS_DomainParticipantFactory_get_default_participant_qos(DDS_DomainParticipantFactory *self, struct DDS_DomainParticipantQos *qos)
Initializes the DDS_DomainParticipantQos instance with default values.
DDS_ReturnCode_t DDS_DomainParticipant_set_qos(DDS_DomainParticipant *self, const struct DDS_DomainParticipantQos *qos)
Change the QoS of this DomainParticipant.
DDS_ReturnCode_t DDS_DomainParticipantQos_finalize(struct DDS_DomainParticipantQos *self)
Free any dynamic memory allocated by the policies in this DDS_DomainParticipantQos.
See also
DDS_DomainParticipantFactory_get_default_participant_qos
DDS_DomainParticipantQos_finalize

◆ DDS_DomainParticipantProtocolStatus_INITIALIZER

#define DDS_DomainParticipantProtocolStatus_INITIALIZER

Initializer for new status instances.

New DDS_DomainParticipantProtocolStatus instances stored on the stack should be initialized with this value before they are passed to any function. This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a status structure is to initialize it on the stack at the time of its creation. DDS_DomainParticipantProtocolStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_ReturnCode_t DDS_DomainParticipant_get_participant_protocol_status(DDS_DomainParticipant *self, struct DDS_DomainParticipantProtocolStatus *status)
<<extension>> Get the domain participant protocol status for this participant.
#define DDS_DomainParticipantProtocolStatus_INITIALIZER
Initializer for new status instances.
Definition: domain.ifc:1927
DDS_ReturnCode_t DDS_DomainParticipantProtocolStatus_finalize(struct DDS_DomainParticipantProtocolStatus *self)
Free any dynamic memory allocated by status instances.
<<extension>> The status of a participant's protocol related metrics, like the number of corrupted me...
Definition: domain.ifc:1912
See also
DDS_DomainParticipant_get_participant_protocol_status
DDS_DomainParticipantProtocolStatus_finalize

Typedef Documentation

◆ DDS_DomainId_t

typedef DDS_DOMAINID_TYPE_NATIVE DDS_DomainId_t

An integer that indicates in which domain a DDS_DomainParticipant communicates.

Participants with the same DDS_DomainId_t are said to be in the same domain, and can thus communicate with one another.

The lower limit for a domain ID is 0. The upper limit for a domain ID is determined by the guidelines stated in DDS_RtpsWellKnownPorts_t (specifically DDS_RtpsWellKnownPorts_t::domain_id_gain)

◆ DDS_DomainParticipantListener_InvalidLocalIdentityAdvanceNoticeStatusCallback

typedef void(* DDS_DomainParticipantListener_InvalidLocalIdentityAdvanceNoticeStatusCallback) (void *listener_data, DDS_DomainParticipant *participant, const struct DDS_InvalidLocalIdentityAdvanceNoticeStatus *invalid_local_identity_advance_notice_status)

Notifies the user that the identity of the DDS_DomainParticipant is about to expire.

◆ DDS_DomainParticipant

typedef struct DDS_DomainParticipantImpl DDS_DomainParticipant

<<interface>> Container for all DDS_DomainEntity objects.

The DomainParticipant object plays several roles:

  • It acts as a container for all other DDS_Entity objects.
  • It represents the participation of the application on a communication plane that isolates applications running on the same set of physical computers from each other. A domain establishes a virtual network linking all applications that share the same domainId and isolating them from applications running on different domains. In this way, several independent distributed applications can coexist in the same physical network without interfering, or even being aware of each other.

The following operations may be called even if the DDS_DomainParticipant is not enabled. Operations NOT in this list will fail with DDS_RETCODE_NOT_ENABLED \ if called on a disabled DomainParticipant.

QoS:
DDS_DomainParticipantQos
Status:
Status Kinds
Listener:
DDS_DomainParticipantListener
See also
Operations Allowed in Listener Callbacks

Function Documentation

◆ DDS_InvalidLocalIdentityAdvanceNoticeStatus_equals()

DDS_Boolean DDS_InvalidLocalIdentityAdvanceNoticeStatus_equals ( const struct DDS_InvalidLocalIdentityAdvanceNoticeStatus left,
const struct DDS_InvalidLocalIdentityAdvanceNoticeStatus right 
)

Compares two DDS_InvalidLocalIdentityAdvanceNoticeStatus for equality.

Parameters
left<<in>> This InvalidLocalIdentityAdvanceNoticeStatus. Can be NULL.
right<<in>> The other InvalidLocalIdentityAdvanceNoticeStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two InvalidLocalIdentityAdvanceNoticeStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_DomainParticipantQos_equals()

DDS_Boolean DDS_DomainParticipantQos_equals ( const struct DDS_DomainParticipantQos self,
const struct DDS_DomainParticipantQos other 
)

Compares two DDS_DomainParticipantQos for equality.

Parameters
self<<in>> This DomainParticipantQos.
other<<in>> The other DomainParticipantQos to be compared with this DomainParticipantQos.
Returns
DDS_BOOLEAN_TRUE if the two Qos objects are equal or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_DomainParticipantQos_print()

DDS_ReturnCode_t DDS_DomainParticipantQos_print ( const struct DDS_DomainParticipantQos self)

Prints this DDS_DomainParticipantQos to stdout.

Only the differences between this DDS_DomainParticipantQos and the documented default are printed. If you wish to print everything regardless, see DDS_DomainParticipantQos_to_string_w_params. The output is formatted according to the default values for DDS_QosPrintFormat.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_RETCODE_OK if no error was encountered.

◆ DDS_DomainParticipantQos_to_string()

DDS_ReturnCode_t DDS_DomainParticipantQos_to_string ( const struct DDS_DomainParticipantQos self,
char *  string,
DDS_UnsignedLong string_size 
)

Obtains a string representation of this DDS_DomainParticipantQos.

Only the differences between this DDS_DomainParticipantQos and the documented default are printed. If you wish to print everything regardless, see DDS_DomainParticipantQos_to_string_w_params. The output is formatted according to the default values for DDS_QosPrintFormat.

If the supplied buffer is NULL, the required length of the string is returned via the string_size parameter.

If the supplied buffer is not NULL, the string representation of the DDS_DomainParticipantQos is written to the buffer.

Parameters
self<<in>> Cannot be NULL.
string<<out>> The char buffer that will be used to store the string representation of this DDS_DomainParticipantQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
Returns
DDS_RETCODE_OK if no error was encountered.
See also
DDS_DomainParticipantQos_to_string_w_params

◆ DDS_DomainParticipantQos_to_string_w_params()

DDS_ReturnCode_t DDS_DomainParticipantQos_to_string_w_params ( const struct DDS_DomainParticipantQos self,
char *  string,
DDS_UnsignedLong string_size,
const struct DDS_DomainParticipantQos base,
const struct DDS_QosPrintFormat format 
)

Obtains a string representation of this DDS_DomainParticipantQos.

Only the differences between this DDS_DomainParticipantQos and the DDS_DomainParticipantQos supplied as the base are printed to the string.

It is possible to supply the sentinel value DDS_DOMAINPARTICIPANT_QOS_PRINT_ALL as the base to print everything within the QoS.

If the supplied buffer is NULL, the required length of the string is returned via the string_size parameter.

If the supplied buffer is not NULL, the string representation of the DDS_DomainParticipantQos is written to the buffer.

Parameters
self<<in>> Cannot be NULL.
string<<out>> The char buffer that will be used to store the string representation of this DDS_DomainParticipantQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
base<<in>> The DDS_DomainParticipantQos to be used as the base QoS profile. Only the differences with respect to this base profile will be included in the output string.
format<<in>> The DDS_QosPrintFormat to be used to format the output string.
Returns
DDS_RETCODE_OK if no error was encountered.

◆ DDS_DomainParticipantQos_initialize()

DDS_ReturnCode_t DDS_DomainParticipantQos_initialize ( struct DDS_DomainParticipantQos self)

Initializer for new QoS instances.

New DDS_DomainParticipantQos instances on heap should be initialized with this function before they are passed to any functions. This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This function does not allocate memory.

Calling this function is not a substitute for calling DDS_DomainParticipant_get_qos or DDS_DomainParticipantFactory_get_default_participant_qos; one of those functions should be called subsequently to setting the QoS of any new or existing entity. DDS_DomainParticipantQos_finalize should be called to free the contained QoS policies that use dynamic memory:

DDS_DomainParticipantQos *myQos = malloc(sizeof(struct DDS_DomainParticipantQos));
DDS_DomainParticipant_set_qos(myParticipant, myQos);
free(myQos);
DDS_ReturnCode_t DDS_DomainParticipantQos_initialize(struct DDS_DomainParticipantQos *self)
Initializer for new QoS instances.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipantFactory_get_default_participant_qos
DDS_DomainParticipantQos_finalize

◆ DDS_DomainParticipantQos_finalize()

DDS_ReturnCode_t DDS_DomainParticipantQos_finalize ( struct DDS_DomainParticipantQos self)

Free any dynamic memory allocated by the policies in this DDS_DomainParticipantQos.

Some QoS policies may use dynamic memory (regardless of whether the QoS itself is in dynamic memory). This function frees that memory but otherwise leaves this QoS unchanged. It should be called on all instances before they are freed (or, in the case of stack-based instances, before they go out of scope).

This function does not leave this object in an invalid state. It is permissable to finalize a QoS and then subsequently allocate new dynamic memory in one or more of its QoS policies.

Note that if this QoS instance is stored in heap memory, calling this function will not call free() on it; the user is responsible for explicitly freeing any heap-based QoS instance after calling this function.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipantQos_INITIALIZER
DDS_DomainParticipantQos_initialize

◆ DDS_DomainParticipantQos_copy()

DDS_ReturnCode_t DDS_DomainParticipantQos_copy ( struct DDS_DomainParticipantQos self,
const struct DDS_DomainParticipantQos source 
)

Copy the contents of the given QoS into this QoS.

DDS_DomainParticipantQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. QoS to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipantQos_INITIALIZER
DDS_DomainParticipantQos_initialize
DDS_DomainParticipantQos_finalize

◆ DDS_DomainParticipant_as_entity()

DDS_Entity * DDS_DomainParticipant_as_entity ( DDS_DomainParticipant domain)

Access a DDS_DomainParticipant's supertype instance.

Parameters
domain<<in>> Cannot be NULL.
Returns
DDS_DomainParticipant's supertype DDS_Entity instance

◆ DDS_DomainParticipantProtocolStatus_initialize()

DDS_ReturnCode_t DDS_DomainParticipantProtocolStatus_initialize ( struct DDS_DomainParticipantProtocolStatus self)

Initializer for new status instances.

New DDS_DomainParticipantProtocolStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_DomainParticipantProtocolStatus_finalize should be called to free the contained fields that use dynamic memory:

free(myStatus);
DDS_ReturnCode_t DDS_DomainParticipantProtocolStatus_initialize(struct DDS_DomainParticipantProtocolStatus *self)
Initializer for new status instances.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipant_get_participant_protocol_status
DDS_DomainParticipantProtocolStatus_finalize

◆ DDS_DomainParticipantProtocolStatus_copy()

DDS_ReturnCode_t DDS_DomainParticipantProtocolStatus_copy ( struct DDS_DomainParticipantProtocolStatus self,
const struct DDS_DomainParticipantProtocolStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipantProtocolStatus_INITIALIZER
DDS_DomainParticipantProtocolStatus_initialize
DDS_DomainParticipantProtocolStatus_finalize

◆ DDS_DomainParticipantProtocolStatus_finalize()

DDS_ReturnCode_t DDS_DomainParticipantProtocolStatus_finalize ( struct DDS_DomainParticipantProtocolStatus self)

Free any dynamic memory allocated by status instances.

Some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status unchanged. It should be called on all instances before they are freed (or, in the case of stack-based instances, before they go out of scope).

Note that if this status instance is stored in heap memory, calling this function will not call free() on it; the user is responsible for explicitly freeing any heap-based status instance after calling this function.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipantProtocolStatus_INITIALIZER
DDS_DomainParticipantProtocolStatus_initialize

◆ DDS_DomainParticipantProtocolStatus_equals()

DDS_Boolean DDS_DomainParticipantProtocolStatus_equals ( const struct DDS_DomainParticipantProtocolStatus left,
const struct DDS_DomainParticipantProtocolStatus right 
)

Compares two DDS_DomainParticipantProtocolStatus for equality.

Parameters
left<<in>> This DomainParticipantProtocolStatus. Can be NULL.
right<<in>> The other DomainParticipantProtocolStatus to be compared with this status instance. Can be NULL.
Returns
DDS_BOOLEAN_TRUE if the two DomainParticipantProtocolStatus have equal values, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_DomainParticipant_get_default_topic_qos()

DDS_ReturnCode_t DDS_DomainParticipant_get_default_topic_qos ( DDS_DomainParticipant self,
struct DDS_TopicQos qos 
)

Copies the default DDS_TopicQos values for this domain participant into the given DDS_TopicQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDS_DomainParticipant_set_default_topic_qos, or DDS_DomainParticipant_set_default_topic_qos_with_profile or else, if the call was never made, the default values listed in DDS_TopicQos.

This function may potentially allocate memory depending on the sequences contained in some QoS policies.

MT Safety:
UNSAFE. It is not safe to retrieve the default Topic QoS from a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_topic_qos
Parameters
self<<in>> Cannot be NULL.
qos<<in>> Default qos to be retrieved. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_TOPIC_QOS_DEFAULT
DDS_DomainParticipant_create_topic

◆ DDS_DomainParticipant_set_default_topic_qos()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_topic_qos ( DDS_DomainParticipant self,
const struct DDS_TopicQos qos 
)

Set the default DDS_TopicQos values for this domain participant.

This default value will be used for newly created DDS_Topic if DDS_TOPIC_QOS_DEFAULT is specified as the qos parameter when DDS_DomainParticipant_create_topic is called.

Precondition
The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default topic QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_topic_qos, DDS_DomainParticipant_get_default_topic_qos or calling DDS_DomainParticipant_create_topic with DDS_TOPIC_QOS_DEFAULT as the qos parameter.
Parameters
self<<in>> Cannot be NULL.
qos<<in>> Default qos to be set. The special value DDS_TOPIC_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDS_DomainParticipant_set_default_topic_qos had never been called. Cannot be NULL.
Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_TOPIC_QOS_DEFAULT
DDS_DomainParticipant_create_topic

◆ DDS_DomainParticipant_set_default_topic_qos_with_profile()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_topic_qos_with_profile ( DDS_DomainParticipant self,
const char *  library_name,
const char *  profile_name 
)

<<extension>> Set the default DDS_TopicQos values for this domain participant based on the input XML QoS profile.

This default value will be used for newly created DDS_Topic if DDS_TOPIC_QOS_DEFAULT is specified as the qos parameter when DDS_DomainParticipant_create_topic is called.

Precondition
The DDS_TopicQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default topic QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_topic_qos, DDS_DomainParticipant_get_default_topic_qos or calling DDS_DomainParticipant_create_topic with DDS_TOPIC_QOS_DEFAULT as the qos parameter.
Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).

If the input profile cannot be found the function fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_TOPIC_QOS_DEFAULT
DDS_DomainParticipant_create_topic_with_profile

◆ DDS_DomainParticipant_get_default_publisher_qos()

DDS_ReturnCode_t DDS_DomainParticipant_get_default_publisher_qos ( DDS_DomainParticipant self,
struct DDS_PublisherQos qos 
)

Copy the default DDS_PublisherQos values into the provided DDS_PublisherQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDS_DomainParticipant_set_default_publisher_qos, or DDS_DomainParticipant_set_default_publisher_qos_with_profile, or else, if the call was never made, the default values listed in DDS_PublisherQos.

This function may potentially allocate memory depending on the sequences contained in some QoS policies.

If DDS_PUBLISHER_QOS_DEFAULT is specified as the qos parameter when DDS_DomainParticipant_create_topic is called, the default value of the QoS set in the factory, equivalent to the value obtained by calling DDS_DomainParticipant_get_default_publisher_qos, will be used to create the DDS_Publisher.

MT Safety:
UNSAFE. It is not safe to retrieve the default publisher QoS from a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_publisher_qos
Parameters
self<<in>> Cannot be NULL.
qos<<inout>> Qos to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_PUBLISHER_QOS_DEFAULT
DDS_DomainParticipant_create_publisher

◆ DDS_DomainParticipant_set_default_publisher_qos()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_publisher_qos ( DDS_DomainParticipant self,
const struct DDS_PublisherQos qos 
)

Set the default DDS_PublisherQos values for this DomainParticipant.

This set of default values will be used for a newly created DDS_Publisher if DDS_PUBLISHER_QOS_DEFAULT is specified as the qos parameter when DDS_DomainParticipant_create_publisher is called.

Precondition
The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default publisher QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_publisher_qos, DDS_DomainParticipant_get_default_publisher_qos or calling DDS_DomainParticipant_create_publisher with DDS_PUBLISHER_QOS_DEFAULT as the qos parameter.
Parameters
self<<in>> Cannot be NULL.
qos<<in>> Default qos to be set. The special value DDS_PUBLISHER_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDS_DomainParticipant_set_default_publisher_qos had never been called. Cannot be NULL.
Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_PUBLISHER_QOS_DEFAULT
DDS_DomainParticipant_create_publisher

◆ DDS_DomainParticipant_set_default_publisher_qos_with_profile()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_publisher_qos_with_profile ( DDS_DomainParticipant self,
const char *  library_name,
const char *  profile_name 
)

<<extension>> Set the default DDS_PublisherQos values for this DomainParticipant based on the input XML QoS profile.

This set of default values will be used for a newly created DDS_Publisher if DDS_PUBLISHER_QOS_DEFAULT is specified as the qos parameter when DDS_DomainParticipant_create_publisher is called.

Precondition
The DDS_PublisherQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default publisher QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_publisher_qos, DDS_DomainParticipant_get_default_publisher_qos or calling DDS_DomainParticipant_create_publisher with DDS_PUBLISHER_QOS_DEFAULT as the qos parameter.
Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).

If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_PUBLISHER_QOS_DEFAULT
DDS_DomainParticipant_create_publisher_with_profile

◆ DDS_DomainParticipant_get_default_datawriter_qos()

DDS_ReturnCode_t DDS_DomainParticipant_get_default_datawriter_qos ( DDS_DomainParticipant self,
struct DDS_DataWriterQos qos 
)

<<extension>> Copy the default DDS_DataWriterQos values into the provided DDS_DataWriterQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDS_DomainParticipant_set_default_datawriter_qos, or DDS_DomainParticipant_set_default_datawriter_qos_with_profile, or else, if the call was never made, the default values listed in DDS_DataWriterQos.

This function may potentially allocate memory depending on the sequences contained in some QoS policies.

MT Safety:
UNSAFE. It is not safe to retrieve the default DataWriterQoS from a DomainPartipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_datawriter_qos.
Parameters
self<<in>> Cannot be NULL.
qos<<inout>> Qos to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DomainParticipant_set_default_datawriter_qos()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_datawriter_qos ( DDS_DomainParticipant self,
const struct DDS_DataWriterQos qos 
)

<<extension>> Set the default DataWriterQos values for this DomainParticipant.

This set of default values will be inherited for a newly created DDS_Publisher.

Precondition
The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default DataWriter QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_datawriter_qos or DDS_DomainParticipant_get_default_datawriter_qos or calling DDS_DomainParticipant_create_datawriter with DDS_DATAWRITER_QOS_DEFAULT as the qos parameter.
Parameters
self<<in>> Cannot be NULL.
qos<<in>> Default qos to be set. The special value DDS_DATAWRITER_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDS_DomainParticipant_set_default_datawriter_qos had never been called. Cannot be NULL.
Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ DDS_DomainParticipant_set_default_datawriter_qos_with_profile()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_datawriter_qos_with_profile ( DDS_DomainParticipant self,
const char *  library_name,
const char *  profile_name 
)

<<extension>> Set the default DDS_DataWriterQos values for this domain participant based on the input XML QoS profile.

This set of default values will be inherited for a newly created DDS_Publisher.

Precondition
The DDS_DataWriterQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default DataWriter QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_datawriter_qos or DDS_DomainParticipant_get_default_datawriter_qos
Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).

If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ DDS_DomainParticipant_get_default_subscriber_qos()

DDS_ReturnCode_t DDS_DomainParticipant_get_default_subscriber_qos ( DDS_DomainParticipant self,
struct DDS_SubscriberQos qos 
)

Copy the default DDS_SubscriberQos values into the provided DDS_SubscriberQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDS_DomainParticipant_set_default_subscriber_qos, or DDS_DomainParticipant_set_default_subscriber_qos_with_profile, or else, if the call was never made, the default values listed in DDS_SubscriberQos.

This function may potentially allocate memory depending on the sequences contained in some QoS policies.

If DDS_SUBSCRIBER_QOS_DEFAULT is specified as the qos parameter when DDS_DomainParticipant_create_subscriber is called, the default value of the QoS set in the factory, equivalent to the value obtained by calling DDS_DomainParticipant_get_default_subscriber_qos, will be used to create the DDS_Subscriber.

MT Safety:
UNSAFE. It is not safe to retrieve the default Subscriber QoS from a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_subscriber_qos.
Parameters
self<<in>> Cannot be NULL.
qos<<inout>> Qos to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_SUBSCRIBER_QOS_DEFAULT
DDS_DomainParticipant_create_subscriber

◆ DDS_DomainParticipant_set_default_subscriber_qos()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_subscriber_qos ( DDS_DomainParticipant self,
const struct DDS_SubscriberQos qos 
)

Set the default DDS_SubscriberQos values for this DomainParticipant.

This set of default values will be used for a newly created DDS_Subscriber if DDS_SUBSCRIBER_QOS_DEFAULT is specified as the qos parameter when DDS_DomainParticipant_create_subscriber is called.

Precondition
The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default Subscriber QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_subscriber_qos, DDS_DomainParticipant_get_default_subscriber_qos or calling DDS_DomainParticipant_create_subscriber with DDS_SUBSCRIBER_QOS_DEFAULT as the qos parameter.
Parameters
self<<in>> Cannot be NULL.
qos<<in>> Default qos to be set. The special value DDS_SUBSCRIBER_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDS_DomainParticipant_set_default_subscriber_qos had never been called. Cannot be NULL.
Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ DDS_DomainParticipant_set_default_subscriber_qos_with_profile()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_subscriber_qos_with_profile ( DDS_DomainParticipant self,
const char *  library_name,
const char *  profile_name 
)

<<extension>> Set the default DDS_SubscriberQos values for this DomainParticipant based on the input XML QoS profile.

This set of default values will be used for a newly created DDS_Subscriber if DDS_SUBSCRIBER_QOS_DEFAULT is specified as the qos parameter when DDS_DomainParticipant_create_subscriber is called.

Precondition
The DDS_SubscriberQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default Subscriber QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_subscriber_qos, DDS_DomainParticipant_get_default_subscriber_qos or calling DDS_DomainParticipant_create_subscriber with DDS_SUBSCRIBER_QOS_DEFAULT as the qos parameter.
Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).

If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_SUBSCRIBER_QOS_DEFAULT
DDS_DomainParticipant_create_subscriber_with_profile

◆ DDS_DomainParticipant_get_default_datareader_qos()

DDS_ReturnCode_t DDS_DomainParticipant_get_default_datareader_qos ( DDS_DomainParticipant self,
struct DDS_DataReaderQos qos 
)

<<extension>> Copy the default DDS_DataReaderQos values into the provided DDS_DataReaderQos instance.

The retrieved qos will match the set of values specified on the last successful call to DDS_DomainParticipant_set_default_datareader_qos, or DDS_DomainParticipant_set_default_datareader_qos_with_profile, or else, if the call was never made, the default values listed in DDS_DataReaderQos.

This function may potentially allocate memory depending on the sequences contained in some QoS policies.

MT Safety:
UNSAFE. It is not safe to retrieve the default DataReader QoS from a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_datareader_qos.
Parameters
self<<in>> Cannot be NULL.
qos<<inout>> Qos to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DomainParticipant_set_default_datareader_qos()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_datareader_qos ( DDS_DomainParticipant self,
const struct DDS_DataReaderQos qos 
)

<<extension>> Set the default DDS_DataReaderQos values for this domain participant.

This set of default values will be inherited for a newly created DDS_Subscriber.

Precondition
The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default DataReader QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_datareader_qos or DDS_DomainParticipant_get_default_datareader_qos.
Parameters
self<<in>> Cannot be NULL.
qos<<in>> Default qos to be set. The special value DDS_DATAREADER_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDS_DomainParticipant_set_default_datareader_qos had never been called. Cannot be NULL.
Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ DDS_DomainParticipant_set_default_datareader_qos_with_profile()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_datareader_qos_with_profile ( DDS_DomainParticipant self,
const char *  library_name,
const char *  profile_name 
)

<<extension>> Set the default DDS_DataReaderQos values for this DomainParticipant based on the input XML QoS profile.

This set of default values will be inherited for a newly created DDS_Subscriber.

Precondition
The DDS_DataReaderQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default DataReader QoS for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_datareader_qos or DDS_DomainParticipant_get_default_datareader_qos.
Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).

If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.

Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

◆ DDS_DomainParticipant_get_default_flowcontroller_property()

DDS_ReturnCode_t DDS_DomainParticipant_get_default_flowcontroller_property ( DDS_DomainParticipant self,
struct DDS_FlowControllerProperty_t prop 
)

<<extension>> Copies the default DDS_FlowControllerProperty_t values for this domain participant into the given DDS_FlowControllerProperty_t instance.

The retrieved property will match the set of values specified on the last successful call to DDS_DomainParticipant_set_default_flowcontroller_property, or else, if the call was never made, the default values listed in DDS_FlowControllerProperty_t.

MT Safety:
UNSAFE. It is not safe to retrieve the default flow controller properties from a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_flowcontroller_property
Parameters
self<<in>> Cannot be NULL.
prop<<in>> Default property to be retrieved. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT
DDS_DomainParticipant_create_flowcontroller

◆ DDS_DomainParticipant_set_default_flowcontroller_property()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_flowcontroller_property ( DDS_DomainParticipant self,
const struct DDS_FlowControllerProperty_t prop 
)

<<extension>> Set the default DDS_FlowControllerProperty_t values for this domain participant.

This default value will be used for newly created DDS_FlowController if DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT is specified as the property parameter when DDS_DomainParticipant_create_flowcontroller is called.

Precondition
The specified property values must be consistent, or else the operation will have no effect and fail with DDS_RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to set the default flow controller properties for a DomainParticipant while another thread may be simultaneously calling DDS_DomainParticipant_set_default_flowcontroller_property , DDS_DomainParticipant_get_default_flowcontroller_property or calling DDS_DomainParticipant_create_flowcontroller with DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT as the qos parameter.
Parameters
self<<in>> Cannot be NULL.
prop<<in>> Default property to be set. The special value DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT may be passed as property to indicate that the default property should be reset to the default values the factory would use if DDS_DomainParticipant_set_default_flowcontroller_property had never been called. Cannot be NULL.
Returns
One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY
See also
DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT
DDS_DomainParticipant_create_flowcontroller

◆ DDS_DomainParticipant_get_default_library()

const char * DDS_DomainParticipant_get_default_library ( DDS_DomainParticipant self)

<<extension>> Gets the default XML library associated with a DDS_DomainParticipant.

Parameters
self<<in>> Cannot be NULL.
Returns
The default library or null if the default library was not set.
See also
DDS_DomainParticipant_set_default_library

◆ DDS_DomainParticipant_get_default_profile()

const char * DDS_DomainParticipant_get_default_profile ( DDS_DomainParticipant self)

<<extension>> Gets the default XML profile associated with a DDS_DomainParticipant.

Parameters
self<<in>> Cannot be NULL.
Returns
The default profile or null if the default profile was not set.
See also
DDS_DomainParticipant_set_default_profile

◆ DDS_DomainParticipant_get_default_profile_library()

const char * DDS_DomainParticipant_get_default_profile_library ( DDS_DomainParticipant self)

<<extension>> Gets the library where the default XML QoS profile is contained for a DDS_DomainParticipant.

The default profile library is automatically set when DDS_DomainParticipant_set_default_profile is called.

This library can be different than the DDS_DomainParticipant default library (see DDS_DomainParticipant_get_default_library).

Parameters
self<<in>> Cannot be NULL.
Returns
The default profile library or null if the default profile was not set.
See also
DDS_DomainParticipant_set_default_profile

◆ DDS_DomainParticipant_set_default_library()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_library ( DDS_DomainParticipant self,
const char *  library_name 
)

<<extension>> Sets the default XML library for a DDS_DomainParticipant.

This function specifies the library that will be used as the default the next time a default library is needed during a call to one of this DomainParticipant's operations.

Any API requiring a library_name as a parameter can use null to refer to the default library.

If the default library is not set, the DDS_DomainParticipant inherits the default from the DDS_DomainParticipantFactory (see DDS_DomainParticipantFactory_set_default_library).

Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name. If library_name is null any previous default is unset.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipant_get_default_library

◆ DDS_DomainParticipant_set_default_profile()

DDS_ReturnCode_t DDS_DomainParticipant_set_default_profile ( DDS_DomainParticipant self,
const char *  library_name,
const char *  profile_name 
)

<<extension>> Sets the default XML profile for a DDS_DomainParticipant.

This function specifies the profile that will be used as the default the next time a default DomainParticipant profile is needed during a call to one of this DomainParticipant's operations. When calling a DDS_DomainParticipant function that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

If the default profile is not set, the DDS_DomainParticipant inherits the default from the DDS_DomainParticipantFactory (see DDS_DomainParticipantFactory_set_default_profile).

This function does not set the default QoS for entities created by the DDS_DomainParticipant; for this functionality, use the functions set_default_<entity>_qos_with_profile (you may pass in NULL after having called set_default_profile()).

This function does not set the default QoS for newly created DomainParticipants; for this functionality, use DDS_DomainParticipantFactory_set_default_participant_qos_with_profile.

Parameters
self<<in>> Cannot be NULL.
library_name<<in>> The library name containing the profile.
profile_name<<in>> The profile name. If profile_name is null any previous default is unset.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipant_get_default_profile
DDS_DomainParticipant_get_default_profile_library

◆ DDS_DomainParticipant_create_publisher()

DDS_Publisher * DDS_DomainParticipant_create_publisher ( DDS_DomainParticipant self,
const struct DDS_PublisherQos qos,
const struct DDS_PublisherListener listener,
DDS_StatusMask  mask 
)

Creates a DDS_Publisher with the desired QoS policies and attaches to it the specified DDS_PublisherListener.

Precondition
The specified QoS policies must be consistent, or the operation will fail and no DDS_Publisher will be created.
if listener is specified, none of the listener callback functions can be NULL.
MT Safety:
UNSAFE. If DDS_PUBLISHER_QOS_DEFAULT is used for qos, it is not safe to create the publisher while another thread may be simultaneously calling DDS_DomainParticipant_set_default_publisher_qos.
Parameters
self<<in>> Cannot be NULL.
qos<<in>> QoS to be used for creating the new DDS_Publisher. The special value DDS_PUBLISHER_QOS_DEFAULT can be used to indicate that the DDS_Publisher should be created with the default DDS_PublisherQos set in the DDS_DomainParticipant. Cannot be NULL.
listener<<in>>. Listener to be attached to the newly created DDS_Publisher.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created publisher object or NULL on failure.
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_PublisherQos for rules on consistency among QoS
DDS_PUBLISHER_QOS_DEFAULT
DDS_DomainParticipant_create_publisher_with_profile
DDS_DomainParticipant_get_default_publisher_qos
DDS_Publisher_set_listener
Examples
HelloWorld_publisher.c.

◆ DDS_DomainParticipant_create_publisher_with_profile()

DDS_Publisher * DDS_DomainParticipant_create_publisher_with_profile ( DDS_DomainParticipant self,
const char *  library_name,
const char *  profile_name,
const struct DDS_PublisherListener listener,
DDS_StatusMask  mask 
)

<<extension>> Creates a new DDS_Publisher object using the DDS_PublisherQos associated with the input XML QoS profile.

Precondition
The DDS_PublisherQos in the input profile must be consistent, or the operation will fail and no DDS_Publisher will be created.
if listener is specified, none of the listener callback functions can be NULL.
Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).
listener<<in>>. Listener to be attached to the newly created DDS_Publisher.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created publisher object or NULL on failure.
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_PublisherQos for rules on consistency among QoS
DDS_DomainParticipant_create_publisher
DDS_DomainParticipant_get_default_publisher_qos
DDS_Publisher_set_listener

◆ DDS_DomainParticipant_delete_publisher()

DDS_ReturnCode_t DDS_DomainParticipant_delete_publisher ( DDS_DomainParticipant self,
DDS_Publisher p 
)

Deletes an existing DDS_Publisher.

Precondition
The DDS_Publisher must not have any attached DDS_DataWriter objects. If there are existing DDS_DataWriter objects, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
DDS_Publisher must have been created by this DDS_DomainParticipant, or else it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the DDS_Publisher will not be called after this function completes successfully.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
p<<in>> DDS_Publisher to be deleted.
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

◆ DDS_DomainParticipant_create_subscriber()

DDS_Subscriber * DDS_DomainParticipant_create_subscriber ( DDS_DomainParticipant self,
const struct DDS_SubscriberQos qos,
const struct DDS_SubscriberListener listener,
DDS_StatusMask  mask 
)

Creates a DDS_Subscriber with the desired QoS policies and attaches to it the specified DDS_SubscriberListener.

Precondition
The specified QoS policies must be consistent, or the operation will fail and no DDS_Subscriber will be created.
if listener is specified, none of the listener callback functions can be NULL.
MT Safety:
UNSAFE. If DDS_SUBSCRIBER_QOS_DEFAULT is used for qos, it is not safe to create the subscriber while another thread may be simultaneously calling DDS_DomainParticipant_set_default_subscriber_qos.
Parameters
self<<in>> Cannot be NULL.
qos<<in>> QoS to be used for creating the new DDS_Subscriber. The special value DDS_SUBSCRIBER_QOS_DEFAULT can be used to indicate that the DDS_Subscriber should be created with the default DDS_SubscriberQos set in the DDS_DomainParticipant. Cannot be NULL.
listener<<in>>. Listener to be attached to the newly created DDS_Subscriber.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created subscriber object or NULL on failure.
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_SubscriberQos for rules on consistency among QoS
DDS_SUBSCRIBER_QOS_DEFAULT
DDS_DomainParticipant_create_subscriber_with_profile
DDS_DomainParticipant_get_default_subscriber_qos
DDS_Subscriber_set_listener
Examples
HelloWorld_subscriber.c.

◆ DDS_DomainParticipant_create_subscriber_with_profile()

DDS_Subscriber * DDS_DomainParticipant_create_subscriber_with_profile ( DDS_DomainParticipant self,
const char *  library_name,
const char *  profile_name,
const struct DDS_SubscriberListener listener,
DDS_StatusMask  mask 
)

<<extension>> Creates a new DDS_Subscriber object using the DDS_PublisherQos associated with the input XML QoS profile.

Precondition
The DDS_SubscriberQos in the input profile must be consistent, or the operation will fail and no DDS_Subscriber will be created.
if listener is specified, none of the listener callback functions can be NULL.
Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).
listener<<in>>. Listener to be attached to the newly created DDS_Subscriber.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created subscriber object or NULL on failure.
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_SubscriberQos for rules on consistency among QoS
DDS_DomainParticipant_create_subscriber
DDS_DomainParticipant_get_default_subscriber_qos
DDS_Subscriber_set_listener

◆ DDS_DomainParticipant_delete_subscriber()

DDS_ReturnCode_t DDS_DomainParticipant_delete_subscriber ( DDS_DomainParticipant self,
DDS_Subscriber s 
)

Deletes an existing DDS_Subscriber.

Precondition
The DDS_Subscriber must not have any attached DDS_DataReader objects. If there are existing DDS_DataReader objects, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET
The DDS_Subscriber must have been created by this DDS_DomainParticipant, or else it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
A Listener installed on the DDS_Subscriber will not be called after this function completes successfully.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
s<<in>> DDS_Subscriber to be deleted.
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

◆ DDS_DomainParticipant_create_datawriter()

DDS_DataWriter * DDS_DomainParticipant_create_datawriter ( DDS_DomainParticipant self,
DDS_Topic topic,
const struct DDS_DataWriterQos qos,
const struct DDS_DataWriterListener listener,
DDS_StatusMask  mask 
)

<<extension>> Creates a DDS_DataWriter that will be attached and belong to the implicit DDS_Publisher.

Precondition
The given DDS_Topic must have been created from the same DomainParticipant as the implicit Publisher. If it was created from a different DomainParticipant, this function will fail.

The DDS_DataWriter created using this function will be associated with the implicit Publisher. This Publisher is automatically created (if it does not exist) using DDS_PUBLISHER_QOS_DEFAULT when the following functions are called: DDS_DomainParticipant_create_datawriter, DDS_DomainParticipant_create_datawriter_with_profile, or DDS_DomainParticipant_get_implicit_publisher.

MT Safety:
UNSAFE. If DDS_DATAWRITER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the DataWriter while another thread may be simultaneously calling DDS_DomainParticipant_set_default_datawriter_qos.
Parameters
self<<in>> Cannot be NULL.
topic<<in>> The DDS_Topic that the DDS_DataWriter will be associated with. Cannot be NULL.
qos<<in>> QoS to be used for creating the new DDS_DataWriter. The special value DDS_DATAWRITER_QOS_DEFAULT can be used to indicate that the DDS_DataWriter should be created with the default DDS_DataWriterQos set in the implicit DDS_Publisher. The special value DDS_DATAWRITER_QOS_USE_TOPIC_QOS can be used to indicate that the DDS_DataWriter should be created with the combination of the default DDS_DataWriterQos set on the DDS_Publisher and the DDS_TopicQos of the DDS_Topic. Cannot be NULL.
listener<<in>> The listener of the DDS_DataWriter.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDS_DataWriter of a derived class specific to the data type associated with the DDS_Topic or NULL if an error occurred.
See also
FooDataWriter
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataWriterQos for rules on consistency among QoS
DDS_DATAWRITER_QOS_DEFAULT
DDS_DATAWRITER_QOS_USE_TOPIC_QOS
DDS_DomainParticipant_create_datawriter_with_profile
DDS_DomainParticipant_get_default_datawriter_qos
DDS_DomainParticipant_get_implicit_publisher
DDS_Topic_set_qos
DDS_DataWriter_set_listener

◆ DDS_DomainParticipant_create_datawriter_with_profile()

DDS_DataWriter * DDS_DomainParticipant_create_datawriter_with_profile ( DDS_DomainParticipant self,
DDS_Topic topic,
const char *  library_name,
const char *  profile_name,
const struct DDS_DataWriterListener listener,
DDS_StatusMask  mask 
)

<<extension>> Creates a DDS_DataWriter using a XML QoS profile that will be attached and belong to the implicit DDS_Publisher.

Precondition
The given DDS_Topic must have been created from the same DomainParticipant as the implicit Publisher. If it was created from a different DomainParticipant, this function will return NULL.

The DDS_DataWriter created using this function will be associated with the implicit Publisher. This Publisher is automatically created (if it does not exist) using DDS_PUBLISHER_QOS_DEFAULT when the following functions are called: DDS_DomainParticipant_create_datawriter, DDS_DomainParticipant_create_datawriter_with_profile, or DDS_DomainParticipant_get_implicit_publisher

Parameters
self<<in>> Cannot be NULL.
topic<<in>> The DDS_Topic that the DDS_DataWriter will be associated with. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).
listener<<in>> The listener of the DDS_DataWriter.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDS_DataWriter of a derived class specific to the data type associated with the DDS_Topic or NULL if an error occurred.
See also
FooDataWriter
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataWriterQos for rules on consistency among QoS
DDS_DomainParticipant_create_datawriter
DDS_DomainParticipant_get_default_datawriter_qos
DDS_DomainParticipant_get_implicit_publisher
DDS_Topic_set_qos
DDS_DataWriter_set_listener

◆ DDS_DomainParticipant_delete_datawriter()

DDS_ReturnCode_t DDS_DomainParticipant_delete_datawriter ( DDS_DomainParticipant self,
DDS_DataWriter a_datawriter 
)

<<extension>> Deletes a DDS_DataWriter that belongs to the implicit DDS_Publisher.

The deletion of the DDS_DataWriter will automatically unregister all instances.

Precondition
If the DDS_DataWriter does not belong to the implicit DDS_Publisher, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the DDS_DataWriter will not be called after this function completes successfully.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
a_datawriter<<in>> The DDS_DataWriter to be deleted.
Returns
One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.
See also
DDS_DomainParticipant_get_implicit_publisher

◆ DDS_DomainParticipant_create_datareader()

DDS_DataReader * DDS_DomainParticipant_create_datareader ( DDS_DomainParticipant self,
DDS_TopicDescription topic,
const struct DDS_DataReaderQos qos,
const struct DDS_DataReaderListener listener,
DDS_StatusMask  mask 
)

<<extension>> Creates a DDS_DataReader that will be attached and belong to the implicit DDS_Subscriber.

Precondition
The given DDS_TopicDescription must have been created from the same DomainParticipant as the implicit Subscriber. If it was created from a different DomainParticipant, this function will return NULL.

The DDS_DataReader created using this function will be associated with the implicit Subscriber. This Subscriber is automatically created (if it does not exist) using DDS_SUBSCRIBER_QOS_DEFAULT when the following functions are called: DDS_DomainParticipant_create_datareader, DDS_DomainParticipant_create_datareader_with_profile, or DDS_DomainParticipant_get_implicit_subscriber.

MT Safety:
UNSAFE. If DDS_DATAREADER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datareader while another thread may be simultaneously calling DDS_DomainParticipant_set_default_datareader_qos.
Parameters
self<<in>> Cannot be NULL.
topic<<in>> The DDS_TopicDescription that the DDS_DataReader will be associated with. Cannot be NULL.
qos<<in>> The qos of the DDS_DataReader. The special value DDS_DATAREADER_QOS_DEFAULT can be used to indicate that the DDS_DataReader should be created with the default DDS_DataReaderQos set in the implicit DDS_Subscriber. If DDS_TopicDescription is of type DDS_Topic or DDS_ContentFilteredTopic, the special value DDS_DATAREADER_QOS_USE_TOPIC_QOS can be used to indicate that the DDS_DataReader should be created with the combination of the default DDS_DataReaderQos set on the implicit DDS_Subscriber and the DDS_TopicQos (in the case of a DDS_ContentFilteredTopic, the DDS_TopicQos of the related DDS_Topic). if DDS_DATAREADER_QOS_USE_TOPIC_QOS is used, topic cannot be a DDS_MultiTopic. Cannot be NULL.
listener<<in>> The listener of the DDS_DataReader.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDS_DataReader of a derived class specific to the data-type associated with the DDS_Topic or NULL if an error occurred.
See also
FooDataReader
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataReaderQos for rules on consistency among QoS
DDS_DomainParticipant_create_datareader_with_profile
DDS_DomainParticipant_get_default_datareader_qos
DDS_DomainParticipant_get_implicit_subscriber
DDS_Topic_set_qos
DDS_DataReader_set_listener

◆ DDS_DomainParticipant_create_datareader_with_profile()

DDS_DataReader * DDS_DomainParticipant_create_datareader_with_profile ( DDS_DomainParticipant self,
DDS_TopicDescription topic,
const char *  library_name,
const char *  profile_name,
const struct DDS_DataReaderListener listener,
DDS_StatusMask  mask 
)

<<extension>> Creates a DDS_DataReader using a XML QoS profile that will be attached and belong to the implicit DDS_Subscriber.

Precondition
The given DDS_TopicDescription must have been created from the same DomainParticipant as the implicit subscriber. If it was created from a different DomainParticipant, this function will return NULL.

The DDS_DataReader created using this function will be associated with the implicit Subscriber. This Subscriber is automatically created (if it does not exist) using DDS_SUBSCRIBER_QOS_DEFAULT when the following functions are called: DDS_DomainParticipant_create_datareader, DDS_DomainParticipant_create_datareader_with_profile, or DDS_DomainParticipant_get_implicit_subscriber

Parameters
self<<in>> Cannot be NULL.
topic<<in>> The DDS_TopicDescription that the DDS_DataReader will be associated with. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).
listener<<in>> The listener of the DDS_DataReader.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
A DDS_DataReader of a derived class specific to the data-type associated with the DDS_Topic or NULL if an error occurred.
See also
FooDataReader
Specifying QoS on entities for information on setting QoS before entity creation
DDS_DataReaderQos for rules on consistency among QoS
DDS_DomainParticipant_create_datareader
DDS_DomainParticipant_get_default_datareader_qos
DDS_DomainParticipant_get_implicit_subscriber
DDS_Topic_set_qos
DDS_DataReader_set_listener

◆ DDS_DomainParticipant_delete_datareader()

DDS_ReturnCode_t DDS_DomainParticipant_delete_datareader ( DDS_DomainParticipant self,
DDS_DataReader a_datareader 
)

<<extension>> Deletes a DDS_DataReader that belongs to the implicit DDS_Subscriber.

Precondition
If the DDS_DataReader does not belong to the implicit DDS_Subscriber, or if ther are any existing DDS_ReadCondition or DDS_QueryCondition objects that are attached to the DDS_DataReader, or if there are outstanding loans on samples (as a result of a call to read(), take(), or one of the variants thereof), the operation fails with the error DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the DDS_DataReader will not be called after this function completes successfully.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
a_datareader<<in>> The DDS_DataReader to be deleted.
Returns
One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.
See also
DDS_DomainParticipant_get_implicit_subscriber

◆ DDS_DomainParticipant_create_topic()

DDS_Topic * DDS_DomainParticipant_create_topic ( DDS_DomainParticipant self,
const char *  topic_name,
const char *  type_name,
const struct DDS_TopicQos qos,
const struct DDS_TopicListener listener,
DDS_StatusMask  mask 
)

Creates a DDS_Topic with the desired QoS policies and attaches to it the specified DDS_TopicListener.

Precondition
The application is not allowed to create two DDS_Topic objects with the same topic_name attached to the same DDS_DomainParticipant. If the application attempts this, this function will fail and return a NULL topic.
The specified QoS policies must be consistent, or the operation will fail and no DDS_Topic will be created.
Prior to creating a DDS_Topic, the type must have been registered with RTI Connext. This is done using the FooTypeSupport_register_type operation on a derived class of the DDS_TypeSupport interface.
MT Safety:
UNSAFE. It is not safe to create a topic while another thread is trying to lookup that topic description with DDS_DomainParticipant_lookup_topicdescription.
MT Safety:
UNSAFE. If DDS_TOPIC_QOS_DEFAULT is used for qos, it is not safe to create the topic while another thread may be simultaneously calling DDS_DomainParticipant_set_default_topic_qos.
Parameters
self<<in>> Cannot be NULL.
topic_name<<in>> Name for the new topic, must not exceed 255 characters. Cannot be NULL.
type_name<<in>> The type to which the new DDS_Topic will be bound. Cannot be NULL.
qos<<in>> QoS to be used for creating the new DDS_Topic. The special value DDS_TOPIC_QOS_DEFAULT can be used to indicate that the DDS_Topic should be created with the default DDS_TopicQos set in the DDS_DomainParticipant. Cannot be NULL.
listener<<in>>. Listener to be attached to the newly created DDS_Topic.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created topic, or NULL on failure
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_TopicQos for rules on consistency among QoS
DDS_TOPIC_QOS_DEFAULT
DDS_DomainParticipant_create_topic_with_profile
DDS_DomainParticipant_get_default_topic_qos
DDS_Topic_set_listener
Examples
HelloWorld_publisher.c, and HelloWorld_subscriber.c.

◆ DDS_DomainParticipant_create_topic_with_profile()

DDS_Topic * DDS_DomainParticipant_create_topic_with_profile ( DDS_DomainParticipant self,
const char *  topic_name,
const char *  type_name,
const char *  library_name,
const char *  profile_name,
const struct DDS_TopicListener listener,
DDS_StatusMask  mask 
)

<<extension>> Creates a new DDS_Topic object using the DDS_PublisherQos associated with the input XML QoS profile.

Precondition
The application is not allowed to create two DDS_TopicDescription objects with the same topic_name attached to the same DDS_DomainParticipant. If the application attempts this, this function will fail and return a NULL topic.
The DDS_TopicQos in the input profile must be consistent, or the operation will fail and no DDS_Topic will be created.
Prior to creating a DDS_Topic, the type must have been registered with RTI Connext. This is done using the FooTypeSupport_register_type operation on a derived class of the DDS_TypeSupport interface.
MT Safety:
UNSAFE. It is not safe to create a topic while another thread is trying to lookup that topic description with DDS_DomainParticipant_lookup_topicdescription.
Parameters
self<<in>> Cannot be NULL.
topic_name<<in>> Name for the new topic, must not exceed 255 characters. Cannot be NULL.
type_name<<in>> The type to which the new DDS_Topic will be bound. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipant_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipant_set_default_profile).
listener<<in>>. Listener to be attached to the newly created DDS_Topic.
mask<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.
Returns
newly created topic, or NULL on failure
See also
Specifying QoS on entities for information on setting QoS before entity creation
DDS_TopicQos for rules on consistency among QoS
DDS_DomainParticipant_create_topic
DDS_DomainParticipant_get_default_topic_qos
DDS_Topic_set_listener

◆ DDS_DomainParticipant_delete_topic()

DDS_ReturnCode_t DDS_DomainParticipant_delete_topic ( DDS_DomainParticipant self,
DDS_Topic topic 
)

Deletes a DDS_Topic.

Precondition
If the DDS_Topic does not belong to the application's DDS_DomainParticipant, this operation fails with DDS_RETCODE_PRECONDITION_NOT_MET.
Make sure no objects are using the topic. More specifically, there must be no existing DDS_DataReader, DDS_DataWriter, DDS_ContentFilteredTopic, or DDS_MultiTopic objects belonging to the same DDS_DomainParticipant that are using the DDS_Topic. If delete_topic is called on a DDS_Topic with any of these existing objects attached to it, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the DDS_Topic will not be called after this function completes successfully.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
topic<<in>> DDS_Topic to be deleted.
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

◆ DDS_DomainParticipant_create_contentfilteredtopic()

DDS_ContentFilteredTopic * DDS_DomainParticipant_create_contentfilteredtopic ( DDS_DomainParticipant self,
const char *  name,
DDS_Topic related_topic,
const char *  filter_expression,
const struct DDS_StringSeq expression_parameters 
)

Creates a DDS_ContentFilteredTopic, that can be used to do content-based subscriptions.

The DDS_ContentFilteredTopic only relates to samples published under that DDS_Topic, filtered according to their content. The filtering is done by means of evaluating a logical expression that involves the values of some of the data-fields in the sample. The logical expression derived from the filter_expression and expression_parameters arguments.

Queries and Filters Syntax describes the syntax of filter_expression and expression_parameters.

Precondition
The application is not allowed to create two DDS_ContentFilteredTopic objects with the same topic_name attached to the same DDS_DomainParticipant. If the application attempts this, this function will fail and returns NULL.
If related_topic does not belong to this DDS_DomainParticipant, this operation returns NULL.
This function will create a content filter using the builtin SQL filter which implements a superset of the DDS specification. This filter requires that all IDL types have been compiled with typecodes. If this precondition is not met, this operation returns NULL.
Parameters
self<<in>> Cannot be NULL.
name<<in>> Name for the new content filtered topic, must not exceed 255 characters. Cannot be NULL.
related_topic<<in>> DDS_Topic to be filtered. Cannot be NULL.
filter_expression<<in>> Cannot be NULL
expression_parameters<<in>> Cannot be NULL. An empty sequence must be used if the filter expression does not contain any parameters. Length of sequence cannot be greater than 100.
Returns
newly created DDS_ContentFilteredTopic, or NULL on failure

◆ DDS_DomainParticipant_create_contentfilteredtopic_with_filter()

DDS_ContentFilteredTopic * DDS_DomainParticipant_create_contentfilteredtopic_with_filter ( DDS_DomainParticipant self,
const char *  name,
const DDS_Topic related_topic,
const char *  filter_expression,
const struct DDS_StringSeq expression_parameters,
const char *  filter_name 
)

<<extension>> Creates a DDS_ContentFilteredTopic using the specified filter to do content-based subscriptions.

Parameters
self<<in>> Cannot be NULL.
name<<in>> Name for the new content filtered topic. Cannot exceed 255 characters. Cannot be NULL.
related_topic<<in>> DDS_Topic to be filtered. Cannot be NULL.
filter_expression<<in>> Cannot be NULL.
expression_parameters<<in>> Cannot be NULL. . An empty sequence must be used if the filter expression does not contain any parameters. Length of the sequence cannot be greater than 100.
filter_name<<in>> Name of content filter to use. Must previously have been registered with DDS_DomainParticipant_register_contentfilter on the same DDS_DomainParticipant. Cannot be NULL. Builtin filter names are DDS_SQLFILTER_NAME and DDS_STRINGMATCHFILTER_NAME
Returns
newly created DDS_ContentFilteredTopic, or NULL on failure

◆ DDS_DomainParticipant_delete_contentfilteredtopic()

DDS_ReturnCode_t DDS_DomainParticipant_delete_contentfilteredtopic ( DDS_DomainParticipant self,
DDS_ContentFilteredTopic a_contentfilteredtopic 
)

Deletes a DDS_ContentFilteredTopic.

Precondition
The deletion of a DDS_ContentFilteredTopic is not allowed if there are any existing DDS_DataReader objects that are using the DDS_ContentFilteredTopic. If the operation is called on a DDS_ContentFilteredTopic with existing DDS_DataReader objects attached to it, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
The DDS_ContentFilteredTopic must be created by this DDS_DomainParticipant, or else this operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
a_contentfilteredtopic<<in>>
Returns
One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET

◆ DDS_DomainParticipant_register_contentfilter()

DDS_ReturnCode_t DDS_DomainParticipant_register_contentfilter ( DDS_DomainParticipant self,
const char *  filter_name,
const struct DDS_ContentFilter contentfilter 
)

<<extension>> Register a content filter which can be used to create a DDS_ContentFilteredTopic.

DDS specifies a SQL-like content filter for use by content filtered topics. If this filter does not meet your filtering requirements, you can register a custom filter.

To use a custom filter, it must be registered in the following places:

  • In any application that uses the custom filter to create a DDS_ContentFilteredTopic and the corresponding DDS_DataReader.
  • In each application that writes the data to the applications mentioned above.

For example, suppose Application A on the subscription side creates a Topic named X and a ContentFilteredTopic named filteredX (and a corresponding DataReader), using a previously registered content filter, myFilter. With only that, you will have filtering at the subscription side. If you also want to perform filtering in any application that publishes Topic X, then you also need to register the same definition of the ContentFilter myFilter in that application.

Each filter_name can only be used to registered a content filter once with a DDS_DomainParticipant.

Parameters
self<<in>> Cannot be NULL.
filter_name<<in>> Name of the filter. The name must be unique within the DDS_DomainParticipant and must not exceed 255 characters. Cannot be NULL.
contentfilter<<in>> Content filter to be registered. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipant_unregister_contentfilter

◆ DDS_DomainParticipant_lookup_contentfilter()

void * DDS_DomainParticipant_lookup_contentfilter ( DDS_DomainParticipant self,
const char *  filter_name 
)

<<extension>> Lookup a content filter previously registered with DDS_DomainParticipant_register_contentfilter.

Parameters
self<<in>> Cannot be NULL.
filter_name<<in>> Name of the filter. Cannot be NULL.
Returns
NULL if the given filter_name has not been previously registered to the DDS_DomainParticipant with DDS_DomainParticipant_register_contentfilter. Otherwise, return the filter_data that has been previously registered with the given filter_name.
See also
DDS_DomainParticipant_register_contentfilter

◆ DDS_DomainParticipant_unregister_contentfilter()

DDS_ReturnCode_t DDS_DomainParticipant_unregister_contentfilter ( DDS_DomainParticipant self,
const char *  filter_name 
)

<<extension>> Unregister a content filter previously registered with DDS_DomainParticipant_register_contentfilter.

A filter_name can be unregistered only if it has been previously registered to the DDS_DomainParticipant with DDS_DomainParticipant_register_contentfilter.

The unregistration of filter is not allowed if there are any existing DDS_ContentFilteredTopic objects that are using the filter. If the operation is called on a filter with existing DDS_ContentFilteredTopic objects attached to it, this operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

If there are still existing discovered DDS_DataReader s with the same filter_name and the filter's compile method of the filter have previously been called on the discovered DDS_DataReader s, finalize method of the filter will be called on those discovered DDS_DataReader s before the content filter is unregistered. This means filtering will now be performed on the application that is creating the DDS_DataReader.

Parameters
self<<in>> Cannot be NULL.
filter_name<<in>> Name of the filter. Cannot be NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET
See also
DDS_DomainParticipant_register_contentfilter

◆ DDS_DomainParticipant_create_multitopic()

DDS_MultiTopic * DDS_DomainParticipant_create_multitopic ( DDS_DomainParticipant self,
const char *  name,
const char *  type_name,
const char *  subscription_expression,
const struct DDS_StringSeq expression_parameters 
)

[Not supported (optional)] Creates a MultiTopic that can be used to subscribe to multiple topics and combine/filter the received data into a resulting type.

The resulting type is specified by the type_name argument. The list of topics and the logic used to combine, filter, and rearrange the information from each DDS_Topic are specified using the subscription_expression and expression_parameters arguments.

Queries and Filters Syntax describes the syntax of subscription_expression and expression_parameters.

Precondition
The application is not allowed to create two DDS_TopicDescription objects with the same name attached to the same DDS_DomainParticipant. If the application attempts this, this function will fail and return NULL.
Prior to creating a DDS_MultiTopic, the type must have been registered with RTI Connext. This is done using the FooTypeSupport_register_type operation on a derived class of the DDS_TypeSupport interface. Otherwise, this function will return NULL.
Parameters
self<<in>> Cannot be NULL.
name<<in>> Name of the newly create DDS_MultiTopic. Cannot be NULL.
type_name<<in>> Cannot be NULL.
subscription_expression<<in>> Cannot be NULL.
expression_parameters<<in>> Cannot be NULL.
Returns
NULL

◆ DDS_DomainParticipant_delete_multitopic()

DDS_ReturnCode_t DDS_DomainParticipant_delete_multitopic ( DDS_DomainParticipant self,
DDS_MultiTopic a_multitopic 
)

[Not supported (optional)] Deletes a DDS_MultiTopic.

Precondition
The deletion of a DDS_MultiTopic is not allowed if there are any existing DDS_DataReader objects that are using the DDS_MultiTopic. If the delete_multitopic operation is called on a DDS_MultiTopic with existing DDS_DataReader objects attached to it, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
The DDS_MultiTopic must be created by this DDS_DomainParticipant, or else this operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
a_multitopic<<in>>

◆ DDS_DomainParticipant_create_flowcontroller()

DDS_FlowController * DDS_DomainParticipant_create_flowcontroller ( DDS_DomainParticipant self,
const char *  name,
const struct DDS_FlowControllerProperty_t prop 
)

<<extension>> Creates a DDS_FlowController with the desired property.

The created DDS_FlowController is associated with a DDS_DataWriter via DDS_PublishModeQosPolicy::flow_controller_name. A single FlowController may service multiple DataWriters instances, even if they belong to a different DDS_Publisher. The property determines how the FlowController shapes the network traffic.

Precondition
The specified property must be consistent, or the operation will fail and no DDS_FlowController will be created.
MT Safety:
UNSAFE. If DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT is used for property, it is not safe to create the flow controller while another thread may be simultaneously calling DDS_DomainParticipant_set_default_flowcontroller_property or trying to lookup that flow controller with DDS_DomainParticipant_lookup_flowcontroller.
Parameters
self<<in>> Cannot be NULL.
name<<in>> name of the DDS_FlowController to create. A DDS_DataWriter is associated with a DDS_FlowController by name. Limited to 255 characters.
prop<<in>> property to be used for creating the new DDS_FlowController. The special value DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT can be used to indicate that the DDS_FlowController should be created with the default DDS_FlowControllerProperty_t set in the DDS_DomainParticipant. Cannot be NULL.
Returns
Newly created flow controller object or NULL on failure.
See also
DDS_FlowControllerProperty_t for rules on consistency among property
DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT
DDS_DomainParticipant_get_default_flowcontroller_property

◆ DDS_DomainParticipant_delete_flowcontroller()

DDS_ReturnCode_t DDS_DomainParticipant_delete_flowcontroller ( DDS_DomainParticipant self,
DDS_FlowController fc 
)

<<extension>> Deletes an existing DDS_FlowController.

Precondition
The DDS_FlowController must not have any attached DDS_DataWriter objects. If there are any attached DDS_DataWriter objects, it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
The DDS_FlowController must have been created by this DDS_DomainParticipant, or else it will fail with DDS_RETCODE_PRECONDITION_NOT_MET.
Postcondition
The DDS_FlowController is deleted if this function completes successfully.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
fc<<in>> The DDS_FlowController to be deleted.
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

◆ DDS_DomainParticipant_get_typecode()

const DDS_TypeCode * DDS_DomainParticipant_get_typecode ( DDS_DomainParticipant self,
const char *  type_name 
)

<<extension>> Retrieves the DDS_TypeCode of a type registered with the DDS_DomainParticipant based on the registration name.

Every data type used in a DDS_DomainParticipant has a registered type name which is the name specified at the time the type is registered with the DDS_DomainParticipant.

This operation retrieves the DDS_TypeCode for the type given the registared type name. The type_name argument must correspond to a name used to register a type with the DDS_DomainParticipant. Otherwise, this method will return NULL.

Type registration in a DDS_DomainParticipant is performed by a call to the FooTypeSupport_register_type operation on a derived class of the DDS_TypeSupport interface.

Type registration might occur directly via an application call to the FooTypeSupport_register_type operation, or indirectly by the RTI Connext infrastructure as a result of parsing an XML configuration file that refers to that type.

If a type is registered by the RTI Connext infrastructure as a result of parsing an XML configuration file, the DDS_TypeSupport can be created either from a type description found in the XML files, or else by calling the FooTypeSupport_register_type operation on a DDS_TypeSupport that has been registered with DDS_DomainParticipantFactory. If a DDS_TypeSupport is registered with the DDS_DomainParticipantFactory this mechanism takes precedence over the creation of a DDS_TypeSupport from a type decription in the XML file.

To register a DDS_TypeSupport with the DDS_DomainParticipantFactory use the operation DDS_DomainParticipantFactory_register_type_support.

If the DDS_TypeSupport is created from a type description found in the XML files, the resulting type support will be a DDS_DynamicDataTypeSupport. In this case the DDS_DataWriter and DDS_DataReader uses to write and read data of that type will be the DDS_DynamicDataWriter and DDS_DynamicDataReader, respectively.

Parameters
self<<in>> Cannot be NULL.
type_name<<in>> Name of the type whose TypeCode is retrieved.
Returns
The TypeCode of a registered type with the DDS_DomainParticipant or NULL if no type was registered with the participant under that name.

◆ DDS_DomainParticipant_find_topic()

DDS_Topic * DDS_DomainParticipant_find_topic ( DDS_DomainParticipant self,
const char *  topic_name,
const struct DDS_Duration_t timeout 
)

Finds an existing (or ready to exist) DDS_Topic, based on its name.

This call can be used to block for a specified duration to wait for the DDS_Topic to be created.

If the requested DDS_Topic already exists, it is returned. Otherwise, find_topic() waits until another thread creates it or else returns when the specified timeout occurs.

find_topic() is useful when multiple threads are concurrently creating and looking up topics. In that case, one thread can call find_topic() and, if another thread has not yet created the topic being looked up, it can wait for some period of time for it to do so. In almost all other cases, it is more straightforward to call DDS_DomainParticipant_lookup_topicdescription.

The DDS_DomainParticipant must already be enabled.

Note: Each DDS_Topic obtained by DDS_DomainParticipant_find_topic must also be deleted by means of DDS_DomainParticipant_delete_topic. If DDS_Topic is obtained multiple times by means of DDS_DomainParticipant_find_topic or DDS_DomainParticipant_create_topic, it must also be deleted that same number of times using DDS_DomainParticipant_delete_topic.

Parameters
self<<in>> Cannot be NULL.
topic_name<<in>> Name of the DDS_Topic to search for. Cannot be NULL.
timeout<<in>> The time to wait if the DDS_Topic does not exist already. Cannot be NULL.
Returns
the topic, if it exists, or NULL

◆ DDS_DomainParticipant_lookup_topicdescription()

DDS_TopicDescription * DDS_DomainParticipant_lookup_topicdescription ( DDS_DomainParticipant self,
const char *  topic_name 
)

Looks up an existing, locally created DDS_TopicDescription, based on its name.

DDS_TopicDescription is the base class for DDS_Topic, DDS_MultiTopic and DDS_ContentFilteredTopic. So you can narrow the DDS_TopicDescription returned from this operation to a DDS_Topic or DDS_ContentFilteredTopic as appropriate.

Unlike DDS_DomainParticipant_find_topic, which logically returns a new DDS_Topic object that must be independently deleted, this operation returns a reference to the original local object.

The DDS_DomainParticipant does not have to be enabled when you call lookup_topicdescription().

The returned topic may be either enabled or disabled.

MT Safety:
UNSAFE. It is not safe to lookup a topic description while another thread is creating that topic.
Parameters
self<<in>> Cannot be NULL.
topic_name<<in>> Name of DDS_TopicDescription to search for. This string must be no more than 255 characters; it cannot be NULL.
Returns
The topic description, if it has already been created locally, otherwise it returns NULL.

◆ DDS_DomainParticipant_lookup_flowcontroller()

DDS_FlowController * DDS_DomainParticipant_lookup_flowcontroller ( DDS_DomainParticipant self,
const char *  name 
)

<<extension>> Looks up an existing locally-created DDS_FlowController, based on its name.

Looks up a previously created DDS_FlowController, including the built-in ones. Once a DDS_FlowController has been deleted, subsequent lookups will fail.

MT Safety:
UNSAFE. It is not safe to lookup a flow controller description while another thread is creating that flow controller.
Parameters
self<<in>> Cannot be NULL.
name<<in>> Name of DDS_FlowController to search for. Limited to 255 characters. Cannot be NULL.
Returns
The flow controller if it has already been created locally, or NULL otherwise.

◆ DDS_DomainParticipant_get_participant_protocol_status()

DDS_ReturnCode_t DDS_DomainParticipant_get_participant_protocol_status ( DDS_DomainParticipant self,
struct DDS_DomainParticipantProtocolStatus status 
)

<<extension>> Get the domain participant protocol status for this participant.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_DomainParticipantProtocolStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ DDS_DomainParticipant_get_builtin_subscriber()

DDS_Subscriber * DDS_DomainParticipant_get_builtin_subscriber ( DDS_DomainParticipant self)

Accesses the built-in DDS_Subscriber.

Each DDS_DomainParticipant contains several built-in DDS_Topic objects as well as corresponding DDS_DataReader objects to access them. All of these DDS_DataReader objects belong to a single built-in DDS_Subscriber.

The built-in Topics are used to communicate information about other DDS_DomainParticipant, DDS_Topic, DDS_DataReader, and DDS_DataWriter objects.

The built-in subscriber is created when this operation is called for the first time. The built-in subscriber is deleted automatically when the DDS_DomainParticipant is deleted.

Parameters
self<<in>> Cannot be NULL.
Returns
The built-in DDS_Subscriber singleton.
See also
DDS_SubscriptionBuiltinTopicData
DDS_PublicationBuiltinTopicData
DDS_ParticipantBuiltinTopicData
DDS_TopicBuiltinTopicData

◆ DDS_DomainParticipant_get_implicit_publisher()

DDS_Publisher * DDS_DomainParticipant_get_implicit_publisher ( DDS_DomainParticipant self)

<<extension>> Returns the implicit DDS_Publisher. If an implicit Publisher does not already exist, this creates one.

There can only be one implicit Publisher per DomainParticipant.

The implicit Publisher is created with DDS_PUBLISHER_QOS_DEFAULT and no Listener.

This implicit Publisher will be deleted automatically when the following functions are called: DDS_DomainParticipant_delete_contained_entities, or DDS_DomainParticipant_delete_publisher with the implicit publisher as a parameter. Additionally, when a DomainParticipant is deleted, if there are no attached DataWriters that belong to the implicit Publisher, the implicit Publisher will be implicitly deleted.

Parameters
self<<in>> Cannot be NULL.
Returns
The implicit publisher
See also
DDS_PUBLISHER_QOS_DEFAULT
DDS_DomainParticipant_create_publisher

◆ DDS_DomainParticipant_get_implicit_subscriber()

DDS_Subscriber * DDS_DomainParticipant_get_implicit_subscriber ( DDS_DomainParticipant self)

<<extension>> Returns the implicit DDS_Subscriber. If an implicit Subscriber does not already exist, this creates one.

There can only be one implicit Subscriber per DomainParticipant.

The implicit Subscriber is created with DDS_SUBSCRIBER_QOS_DEFAULT and no Listener.

This implicit Subscriber will be deleted automatically when the following functions are called: DDS_DomainParticipant_delete_contained_entities, or DDS_DomainParticipant_delete_subscriber with the subscriber as a parameter. Additionally, when a DomainParticipant is deleted, if there are no attached DataReaders that belong to the implicit Subscriber, the implicit Subscriber will be implicitly deleted.

MT Safety:
UNSAFE. it is not safe to create the implicit subscriber while another thread may be simultaneously calling DDS_DomainParticipant_set_default_subscriber_qos.
Parameters
self<<in>> Cannot be NULL.
Returns
The implicit subscriber
See also
DDS_SUBSCRIBER_QOS_DEFAULT
DDS_DomainParticipant_create_subscriber

◆ DDS_DomainParticipant_ignore_participant()

DDS_ReturnCode_t DDS_DomainParticipant_ignore_participant ( DDS_DomainParticipant self,
const DDS_InstanceHandle_t handle 
)

Instructs RTI Connext to locally ignore a remote DDS_DomainParticipant.

From the time of this call onwards, RTI Connext will locally behave as if the remote participant did not exist. This means it will ignore any topic, publication, or subscription that originates on that DDS_DomainParticipant.

There is no way to reverse this operation.

This operation can be used in conjunction with the discovery of remote participants offered by means of the DDS_ParticipantBuiltinTopicData to provide access control.

Application data can be associated with a DDS_DomainParticipant by means of the USER_DATA policy. This application data is propagated as a field in the built-in topic and can be used by an application to implement its own access control policy.

The DDS_DomainParticipant to ignore is identified by the handle argument. This handle is the one that appears in the DDS_SampleInfo retrieved when reading the data-samples available for the built-in DDS_DataReader to the DDS_DomainParticipant topic. The built-in DDS_DataReader is read with the same FooDataReader_read and FooDataReader_take operations used for any DDS_DataReader.

Parameters
self<<in>> Cannot be NULL.
handle<<in>> DDS_InstanceHandle_t of the DDS_DomainParticipant to be ignored. Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED
See also
DDS_ParticipantBuiltinTopicData
DDS_PARTICIPANT_TOPIC_NAME
DDS_DomainParticipant_get_builtin_subscriber

◆ DDS_DomainParticipant_ignore_topic()

DDS_ReturnCode_t DDS_DomainParticipant_ignore_topic ( DDS_DomainParticipant self,
const DDS_InstanceHandle_t handle 
)

Instructs RTI Connext to locally ignore a DDS_Topic.

This means it will locally ignore any publication, or subscription to the DDS_Topic.

There is no way to reverse this operation.

This operation can be used to save local resources when the application knows that it will never publish or subscribe to data under certain topics.

The DDS_Topic to ignore is identified by the handle argument. This is the handle of a DDS_Topic that appears in the DDS_SampleInfo retrieved when reading data samples from the built-in DDS_DataReader for the DDS_Topic.

Parameters
self<<in>> Cannot be NULL.
handle<<in>> Handle of the DDS_Topic to be ignored. Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED
See also
DDS_TopicBuiltinTopicData
DDS_TOPIC_TOPIC_NAME
DDS_DomainParticipant_get_builtin_subscriber

◆ DDS_DomainParticipant_ignore_publication()

DDS_ReturnCode_t DDS_DomainParticipant_ignore_publication ( DDS_DomainParticipant self,
const DDS_InstanceHandle_t handle 
)

Instructs RTI Connext to locally ignore a publication.

A publication is defined by the association of a topic name, user data, and partition set on the DDS_Publisher (see DDS_PublicationBuiltinTopicData). After this call, any data written by that publication's DDS_DataWriter will be ignored.

This operation can be used to ignore local and remote DataWriters.

The publication (DataWriter) to ignore is identified by the handle argument.

  • To ignore a remote DataWriter, the handle can be obtained from the DDS_SampleInfo retrieved when reading data samples from the built-in DDS_DataReader for the publication topic.

There is no way to reverse this operation.

Parameters
self<<in>> Cannot be NULL.
handle<<in>> Handle of the DDS_DataWriter to be ignored. Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED
See also
DDS_PublicationBuiltinTopicData
DDS_PUBLICATION_TOPIC_NAME
DDS_DomainParticipant_get_builtin_subscriber

◆ DDS_DomainParticipant_ignore_subscription()

DDS_ReturnCode_t DDS_DomainParticipant_ignore_subscription ( DDS_DomainParticipant self,
const DDS_InstanceHandle_t handle 
)

Instructs RTI Connext to locally ignore a subscription.

A subscription is defined by the association of a topic name, user data, and partition set on the DDS_Subscriber (see DDS_SubscriptionBuiltinTopicData). After this call, any data received related to that subscription's DDS_DataReader will be ignored.

This operation can be used to ignore local and remote DataReaders.

The subscription to ignore is identified by the handle argument.

  • To ignore a remote DataReader, the handle can be obtained from the DDS_SampleInfo retrieved when reading data samples from the built-in DDS_DataReader for the subscription topic.

There is no way to reverse this operation.

Parameters
self<<in>> Cannot be NULL.
handle<<in>> Handle of the DDS_DataReader to be ignored. Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED
See also
DDS_SubscriptionBuiltinTopicData
DDS_SUBSCRIPTION_TOPIC_NAME
DDS_DomainParticipant_get_builtin_subscriber

◆ DDS_DomainParticipant_banish_ignored_participants()

DDS_ReturnCode_t DDS_DomainParticipant_banish_ignored_participants ( DDS_DomainParticipant self)

<<extension>> Prevents ignored remote DomainParticipants from receiving traffic from the local DDS_DomainParticipant.

This method complements DDS_DomainParticipant_ignore_participant: ignore_participant prevents the local DDS_DomainParticipant from processing traffic from the remote DomainParticipant, while this method prevents already ignored remote DomainParticipants from processing traffic from the local DomainParticipant.

Note: this method is currently only supported when enabling the RTI Security Plugins. Please refer to the RTI Security Plugins User's Manual for more information.

MT Safety:
Safe.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_NOT_ENABLED
See also
DDS_DomainParticipant_ignore_participant

◆ DDS_DomainParticipant_get_domain_id()

DDS_DomainId_t DDS_DomainParticipant_get_domain_id ( DDS_DomainParticipant self)

Get the unique domain identifier.

This operation retrieves the domain id used to create the DDS_DomainParticipant. The domain id identifies the DDS domain to which the DDS_DomainParticipant belongs. Each DDS domain represents a separate data 'communication plane' isolated from other domains.

Parameters
self<<in>> Cannot be NULL.
Returns
the unique domainId that was used to create the domain
See also
DDS_DomainParticipantFactory_create_participant
DDS_DomainParticipantFactory_create_participant_with_profile

◆ DDS_DomainParticipant_delete_contained_entities()

DDS_ReturnCode_t DDS_DomainParticipant_delete_contained_entities ( DDS_DomainParticipant self)

Delete all the entities that were created by means of the "create" operations on the DDS_DomainParticipant.

This operation deletes all contained DDS_Publisher (including an implicit Publisher, if one exists), DDS_Subscriber (including implicit Subscriber), DDS_Topic, DDS_ContentFilteredTopic, and DDS_MultiTopic objects.

Prior to deleting each contained entity, this operation will recursively call the corresponding delete_contained_entities() operation on each contained entity (if applicable). This pattern is applied recursively. In this manner the operation delete_contained_entities() on the DDS_DomainParticipant will end up recursively deleting all the entities contained in the DDS_DomainParticipant, including the DDS_DataWriter, DDS_DataReader, as well as the DDS_QueryCondition, DDS_ReadCondition, and DDS_TopicQuery objects belonging to the contained DDS_DataReader.

The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted .

If delete_contained_entities() completes successfully, the application may delete the DDS_DomainParticipant.

MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.
Examples
HelloWorld_publisher.c, and HelloWorld_subscriber.c.

◆ DDS_DomainParticipant_assert_liveliness()

DDS_ReturnCode_t DDS_DomainParticipant_assert_liveliness ( DDS_DomainParticipant self)

Manually asserts the liveliness of this DDS_DomainParticipant.

This is used in combination with the DDS_LivelinessQosPolicy to indicate to RTI Connext that the entity remains active.

You need to use this operation if the DDS_DomainParticipant contains DDS_DataWriter entities with the DDS_LivelinessQosPolicy::kind set to DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS and it only affects the liveliness of those DDS_DataWriter entities. Otherwise, it has no effect.

Note: writing data via the FooDataWriter_write or FooDataWriter_write_w_timestamp operation asserts liveliness on the DDS_DataWriter itself and its DDS_DomainParticipant. Consequently the use of assert_liveliness() is only needed if the application is not writing data regularly.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes, or DDS_RETCODE_NOT_ENABLED
See also
DDS_LivelinessQosPolicy

◆ DDS_DomainParticipant_get_publishers()

DDS_ReturnCode_t DDS_DomainParticipant_get_publishers ( DDS_DomainParticipant self,
struct DDS_PublisherSeq publishers 
)

<<extension>> Allows the application to access all the publishers the participant has.

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

MT Safety:
Safe.
Parameters
self<<in>> Cannot be NULL.
publishers<<inout>> a PublisherSeq object where the set or list of publishers will be returned
Returns
One of the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES

◆ DDS_DomainParticipant_get_subscribers()

DDS_ReturnCode_t DDS_DomainParticipant_get_subscribers ( DDS_DomainParticipant self,
struct DDS_SubscriberSeq subscribers 
)

<<extension>> Allows the application to access all the subscribers the participant has.

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

MT Safety:
Safe.
Parameters
self<<in>> Cannot be NULL.
subscribers<<inout>> a SubscriberSeq object where the set or list of subscribers will be returned
Returns
One of the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES

◆ DDS_DomainParticipant_get_current_time()

DDS_ReturnCode_t DDS_DomainParticipant_get_current_time ( DDS_DomainParticipant self,
struct DDS_Time_t current_time 
)

Returns the current value of the time.

The current value of the time that RTI Connext uses to time-stamp DDS_DataWriter and to set the reception-timestamp for the data updates that it receives.

Parameters
self<<in>> Cannot be NULL.
current_time<<inout>> Current time to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DomainParticipant_contains_entity()

DDS_Boolean DDS_DomainParticipant_contains_entity ( DDS_DomainParticipant self,
const DDS_InstanceHandle_t a_handle 
)

Completes successfully with DDS_BOOLEAN_TRUE if the referenced DDS_Entity is contained by the DDS_DomainParticipant.

This operation checks whether or not the given a_handle represents an DDS_Entity that was created from the DDS_DomainParticipant. The containment applies recursively. That is, it applies both to entities (DDS_TopicDescription, DDS_Publisher, or DDS_Subscriber) created directly using the DDS_DomainParticipant as well as entities created using a contained DDS_Publisher, or DDS_Subscriber as the factory, and so forth.

The instance handle for an DDS_Entity may be obtained from built-in topic data, from various statuses, or from the operation DDS_Entity_get_instance_handle.

Parameters
self<<in>> Cannot be NULL.
a_handle<<in>> DDS_InstanceHandle_t of the DDS_Entity to be checked.
Returns
DDS_BOOLEAN_TRUE if DDS_Entity is contained by the DDS_DomainParticipant, or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_DomainParticipant_register_durable_subscription()

DDS_ReturnCode_t DDS_DomainParticipant_register_durable_subscription ( DDS_DomainParticipant self,
const struct DDS_EndpointGroup_t group,
const char *  topic_name 
)

<<extension>> Registers a Durable Subscription on the specified DDS_Topic on all Persistence Services.

If you need to receive all samples published on a DDS_Topic, including the ones published while a DDS_DataReader is inactive or before it may be created, create a Durable Subscription using this method.

In this way, the Persistence Service will ensure that all the samples on that DDS_Topic are retained until they are acknowledged by at least N DataReaders belonging to the Durable Subscription where N is the quorum count.

If the same Durable Subscription is created on a different DDS_Topic, the Persistence Service will implicitly delete the previous Durable Subscription and create a new one on the new DDS_Topic.

Parameters
self<<in>> Cannot be NULL.
group<<in>> DDS_EndpointGroup_t The Durable Subscription name and quorum.
topic_name<<in>> The topic name for which the Durable Subscription is created.
Returns
One of the Standard Return Codes

◆ DDS_DomainParticipant_delete_durable_subscription()

DDS_ReturnCode_t DDS_DomainParticipant_delete_durable_subscription ( DDS_DomainParticipant self,
const struct DDS_EndpointGroup_t group 
)

<<extension>> Deletes an existing Durable Subscription on all Persistence Services.

The Persistence Service will delete the Durable Subscription and the quorum of the existing samples will be considered satisfied.

Parameters
self<<in>> Cannot be NULL.
group<<in>> DDS_EndpointGroup_t specifying the Durable Subscription name. Quorum is not required for this operation.
Returns
One of the Standard Return Codes

◆ DDS_DomainParticipant_resume_endpoint_discovery()

DDS_ReturnCode_t DDS_DomainParticipant_resume_endpoint_discovery ( DDS_DomainParticipant self,
const DDS_InstanceHandle_t remote_participant_handle 
)

<<extension>> Initiates endpoint discovery with the specified remote DDS_DomainParticipant.

If the operation returns DDS_RETCODE_OK, the DDS_DomainParticipant will initiate endpoint discovery with the remote DDS_DomainParticipant provided as a parameter.

When DDS_DiscoveryQosPolicy::enable_endpoint_discovery is set to DDS_BOOLEAN_FALSE, this operation allows the RTI Connext application to select for which remote DomainParticipants endpoint discovery is performed. By disabling endpoint discovery, the DomainParticipant will not store any state about remote endpoints and will not send local endpoint information to remote DomainParticipants.

If DDS_DiscoveryQosPolicy::enable_endpoint_discovery is set to DDS_BOOLEAN_TRUE, endpoint discovery will automatically occur for every discovered DDS_DomainParticipant. In this case, invoking this operation will have no effect and will return DDS_RETCODE_OK.

When DDS_DiscoveryQosPolicy::enable_endpoint_discovery is set to DDS_BOOLEAN_FALSE, you have two options after a remote DDS_DomainParticipant is discovered:

Setting DDS_DiscoveryQosPolicy::enable_endpoint_discovery to DDS_BOOLEAN_FALSE enables application-level authentication use cases, in which a DDS_DomainParticipant will initiate endpoint discovery with a remote DDS_DomainParticipant after successful authentication at the application level.

The remote_participant_handle paremeter is the one that appears in the DDS_SampleInfo retrieved when reading the data samples available for the built-in DDS_ParticipantBuiltinTopicDataDataReader.

If the specified remote DDS_DomainParticipant is not in the database of discovered DomainParticipants or has been previously ignored, this operation will fail with DDS_RETCODE_ERROR.

This operation can be called multiple times on the same remote participant. If endpoint discovery has already been resumed, successive calls will have no effect and will return DDS_RETCODE_OK.

Parameters
self<<in>> Cannot be NULL.
remote_participant_handle<<in>> Handle of a discovered DDS_DomainParticipant for which endpoint discovery is to be resumed. Cannot be NULL.
Returns
One of the Standard Return Codes,or DDS_RETCODE_NOT_ENABLED
See also
DDS_DiscoveryQosPolicy

◆ DDS_DomainParticipant_set_dns_tracker_polling_period()

DDS_ReturnCode_t DDS_DomainParticipant_set_dns_tracker_polling_period ( DDS_DomainParticipant self,
const struct DDS_Duration_t polling_period 
)

<<extension>> Configures the frequency in which the DNS tracker queries the DNS service.

This API allows you to change the frequency of the polling period for the DNS tracker. The range of accepted values, in seconds, goes from 1 second to 1 year. DDS_DURATION_INFINITE is also accepted as a valid value. If the duration is set to DDS_DURATION_INFINITE, the DNS tracker is disabled.

Modifying the DNS tracker polling period through this has no effect on the DDS_DiscoveryConfigQosPolicy::dns_tracker_polling_period when it is retrieved with DDS_DomainParticipant_get_qos().

Parameters
self<<in>> Cannot be NULL.
polling_period<<in>> Duration that is set as the polling period for the DNS tracker.
Returns
One of the Standard Return Codes
See also
DDS_DiscoveryConfigQosPolicy::dns_tracker_polling_period
DDS_DomainParticipant_add_peer

◆ DDS_DomainParticipant_get_dns_tracker_polling_period()

DDS_ReturnCode_t DDS_DomainParticipant_get_dns_tracker_polling_period ( DDS_DomainParticipant self,
struct DDS_Duration_t polling_period 
)

<<extension>> Retrieves the frequency used by the DNS tracker thread to query the DNS service.

The DNS tracker queries the DNS for hostnames specified in the initial peers of a DomainParticipant. The frequency of these queries is defined by DDS_DiscoveryConfigQosPolicy::dns_tracker_polling_period. If the value returned is DDS_DURATION_INFINITE, the DNS tracker is disabled.

Parameters
self<<in>> Cannot be NULL.
polling_period<<out>> Duration that the API populates with the period of the DNS tracker.
Returns
One of the Standard Return Codes
See also
DDS_DiscoveryConfigQosPolicy::dns_tracker_polling_period

◆ DDS_DomainParticipant_get_discovered_participants()

DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participants ( DDS_DomainParticipant self,
struct DDS_InstanceHandleSeq participant_handles 
)

Returns a list of discovered DDS_DomainParticipant entities.

This operation retrieves the list of DDS_DomainParticipant entities that have been discovered in the domain and that the application has not indicated should be "ignored" by means of the DDS_DomainParticipant_ignore_participant operation. When using DDS_DISCOVERYCONFIG_BUILTIN_SPDP2, this list only includes DDS_DomainParticipant entities that the application has received configuration information from.

Parameters
self<<in>> Cannot be NULL.
participant_handles<<inout>> DDS_InstanceHandleSeq to be filled with handles of the discovered DDS_DomainParticipant entities.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ DDS_DomainParticipant_get_discovered_participants_from_subject_name()

DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participants_from_subject_name ( DDS_DomainParticipant self,
struct DDS_InstanceHandleSeq participant_handles,
const char *  subject_name 
)

<<extension>> Returns a list of discovered DDS_DomainParticipant entities that have the given DDS_EntityNameQosPolicy::name.

This operation retrieves the same list as DDS_DomainParticipant_get_discovered_participants, except this list contains only the participants that have the given DDS_EntityNameQosPolicy::name.

Note: this method has different functionality when enabling the RTI Security Plugins. Please refer to the RTI Security Plugins User's Manual for more information.

MT Safety:
Safe.
Parameters
self<<in>> Cannot be NULL.
participant_handles<<inout>> DDS_InstanceHandleSeq to be filled with handles of the discovered DDS_DomainParticipant entities.
subject_name<<in>> The DDS_EntityNameQosPolicy::name by which to filter the list.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ DDS_DomainParticipant_get_discovered_participant_data()

DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participant_data ( DDS_DomainParticipant self,
struct DDS_ParticipantBuiltinTopicData participant_data,
const DDS_InstanceHandle_t participant_handle 
)

Returns DDS_ParticipantBuiltinTopicData for the specified DDS_DomainParticipant.

This operation retrieves information on a DDS_DomainParticipant that has been discovered on the network. The participant must be in the same domain as the participant on which this operation is invoked and must not have been "ignored" by means of the DDS_DomainParticipant_ignore_participant operation.

The participant_handle must correspond to such a DomainParticipant. Otherwise, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

Use the operation DDS_DomainParticipant_get_discovered_participants to find the DDS_DomainParticipant entities that are currently discovered.

MT Safety:
Safe.
Parameters
self<<in>> Cannot be NULL.
participant_data<<inout>> DDS_ParticipantBuiltinTopicData to be filled in with the data for the specified DDS_DomainParticipant.
participant_handle<<in>> DDS_InstanceHandle_t of DDS_DomainParticipant.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED
See also
DDS_ParticipantBuiltinTopicData
DDS_DomainParticipant_get_discovered_participants

◆ DDS_DomainParticipant_get_discovered_participant_subject_name()

DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participant_subject_name ( DDS_DomainParticipant self,
char *  subject_name,
DDS_UnsignedLong subject_name_size,
const DDS_InstanceHandle_t participant_handle 
)

<<extension>> Returns DDS_EntityNameQosPolicy::name for the specified DDS_DomainParticipant.

This operation retrieves the DDS_EntityNameQosPolicy::name of a DDS_DomainParticipant that has been discovered on the network. The participant must be in the same domain as the participant on which this operation is invoked and must not have been "ignored" by means of the DDS_DomainParticipant_ignore_participant operation.

The participant_handle must correspond to such a DomainParticipant. If the participant_handle is DDS_HANDLE_NIL or is not a valid DDS_InstanceHandle_t for a DomainParticipant, then the operation will fail with DDS_RETCODE_BAD_PARAMETER. If the participant_handle corresponds to a DomainParticipant that has not been discovered, then the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

Use the operation DDS_DomainParticipant_get_discovered_participants to find the DDS_DomainParticipant entities that are currently discovered.

Note: this method has different functionality when enabling the RTI Security Plugins. Please refer to the RTI Security Plugins User's Manual for more information.

MT Safety:
Safe.
Parameters
self<<in>> Cannot be NULL.
subject_name<<out>> The char buffer that will be used to store the DDS_EntityNameQosPolicy::name of the discovered DDS_DomainParticipant. If NULL, this function will return the required length of this buffer through the subject_name_size parameter.
subject_name_size<<inout>> Cannot be NULL. The size of the supplied char buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer, which includes space for the NUL terminator. If the supplied buffer is not NULL but this value is not large enough, then this function will fail with DDS_RETCODE_BAD_PARAMETER. If the DDS_EntityNameQosPolicy::name is NULL, then this value will be set to 0.
participant_handle<<in>> DDS_InstanceHandle_t of DDS_DomainParticipant.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED
See also
DDS_EntityNameQosPolicy::name
DDS_DomainParticipant_get_discovered_participants

◆ DDS_DomainParticipant_get_discovered_topics()

DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_topics ( DDS_DomainParticipant self,
struct DDS_InstanceHandleSeq topic_handles 
)

Returns list of discovered DDS_Topic objects.

This operation retrieves the list of DDS_Topic s that have been discovered in the domain and that the application has not indicated should be "ignored" by means of the DDS_DomainParticipant_ignore_topic operation.

Parameters
self<<in>> Cannot be NULL.
topic_handles<<inout>> DDS_InstanceHandleSeq to be filled with handles of the discovered DDS_Topic objects
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

◆ DDS_DomainParticipant_get_discovered_topic_data()

DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_topic_data ( DDS_DomainParticipant self,
struct DDS_TopicBuiltinTopicData topic_data,
const DDS_InstanceHandle_t topic_handle 
)

Returns DDS_TopicBuiltinTopicData for the specified DDS_Topic.

This operation retrieves information on a DDS_Topic that has been discovered by the local Participant and must not have been "ignored" by means of the DDS_DomainParticipant_ignore_topic operation.

The topic_handle must correspond to such a topic. Otherwise, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

This call is not supported for remote topics. If a remote topic_handle is used, the operation will fail with DDS_RETCODE_UNSUPPORTED.

Use the operation DDS_DomainParticipant_get_discovered_topics to find the topics that are currently discovered.

Parameters
self<<in>> Cannot be NULL.
topic_data<<inout>> DDS_TopicBuiltinTopicData to be filled with the specified DDS_Topic's data.
topic_handle<<in>> DDS_InstanceHandle_t of DDS_Topic.
Returns
One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED
See also
DDS_TopicBuiltinTopicData
DDS_DomainParticipant_get_discovered_topics

◆ DDS_DomainParticipant_take_discovery_snapshot()

DDS_ReturnCode_t DDS_DomainParticipant_take_discovery_snapshot ( DDS_DomainParticipant self,
const char *  file_name 
)

Take a snapshot of the remote participants discovered by a local one.

A possible output may be the following:

Remote participants that match the local participant domain=0
name="participantTestName" role="participantTestRole" id="1"
guid_prefix="0x0101D8D1,0x20B83C0D,0x4495246E"
----------------------------------------------------------------------------
1. 0x0101542A,0x2C59B595,0xA1693BDF name="participantTestName"
role="participantTestRole"
unicastLocators="udpv4://192.168.1.170:7411"
----------------------------------------------------------------------------
Precondition
self is not NULL.
Parameters
self<<in>> The local participant.
file_name<<in>> Name of the file where snapshot should be printed. If NULL, the snapshot will be printed through NDDS_Config_Logger. Otherwise, the snapshot will be printed in the file specified by file_name.
Returns
One of the Standard Return Codes.

◆ DDS_DomainParticipant_add_peer()

DDS_ReturnCode_t DDS_DomainParticipant_add_peer ( DDS_DomainParticipant self,
const char *  peer_desc_string 
)

<<extension>> Attempt to contact one or more additional peer participants.

Add the given peer description to the list of peers with which this DDS_DomainParticipant will try to communicate.

This function may be called at any time after this DDS_DomainParticipant has been created (before or after it has been enabled).

If this function is called after DDS_Entity_enable, an attempt will be made to contact the new peer(s) immediately.

If this function is called before the DomainParticipant is enabled, the peer description will simply be added to the list that was populated by DDS_DiscoveryQosPolicy::initial_peers; the first attempted contact will take place after this DDS_DomainParticipant is enabled.

Adding a peer description with this function does not guarantee that any peer(s) discovered as a result will exactly correspond to those described:

  • This DDS_DomainParticipant will attempt to discover peer participants at the given locations but may not succeed if no such participants are available. In this case, this function will not wait for contact attempt(s) to be made and it will not report an error.

To be informed of the exact remote participants that are discovered, regardless of which peers this DDS_DomainParticipant attempts to discover, use the built-in participant topic: DDS_PARTICIPANT_TOPIC_NAME.

To remove specific peer locators, you may use DDS_DomainParticipant_remove_peer. If a peer is removed, the add_peer operation will add it back to the list of peers.

To stop communicating with a peer DDS_DomainParticipant that has been discovered, use DDS_DomainParticipant_ignore_participant.

Adding a peer description with this function has no effect on the DDS_DiscoveryQosPolicy::initial_peers that may be subsequently retrieved with DDS_DomainParticipant_get_qos() (because DDS_DiscoveryQosPolicy is immutable).

Parameters
self<<in>> Cannot be NULL.
peer_desc_string<<in>> New peer descriptor to be added. The format is specified in Peer Descriptor Format. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
Peer Descriptor Format
DDS_DiscoveryQosPolicy::initial_peers
DDS_PARTICIPANT_TOPIC_NAME
DDS_DomainParticipant_get_builtin_subscriber

◆ DDS_DomainParticipant_remove_peer()

DDS_ReturnCode_t DDS_DomainParticipant_remove_peer ( DDS_DomainParticipant self,
const char *  peer_desc_string 
)

<<extension>> Remove one or more peer participants from the list of peers with which this DDS_DomainParticipant will try to communicate.

This function may be called any time after this DDS_DomainParticipant has been enabled

Calling this function has the following effects:

  • If a DDS_DomainParticipant was already discovered, it will be locally removed along with all its entities.
  • Any further requests coming from a DDS_DomainParticipant located on any of the removed peers will be ignored.
  • All the locators contained in the peer description will be removed from the peer list. The local DDS_DomainParticipant will stop sending announcement to those locators.

If remote participants located on a peer that was previously removed are discovered, they will be ignored untill the related peer is added back by using DDS_DomainParticipant_add_peer.

Removing a peer description with this function has no effect on the DDS_DiscoveryQosPolicy::initial_peers that may be subsequently retrieved with DDS_DomainParticipant_get_qos() (because DDS_DiscoveryQosPolicy is immutable).

Parameters
self<<in>> Cannot be NULL.
peer_desc_string<<in>> Peer descriptor to be removed. The format is specified in Peer Descriptor Format. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
Peer Descriptor Format
DDS_DiscoveryQosPolicy::initial_peers
DDS_DomainParticipant_add_peer

◆ DDS_DomainParticipant_set_qos()

DDS_ReturnCode_t DDS_DomainParticipant_set_qos ( DDS_DomainParticipant self,
const struct DDS_DomainParticipantQos qos 
)

Change the QoS of this DomainParticipant.

The DDS_DomainParticipantQos::user_data and DDS_DomainParticipantQos::entity_factory can be changed. The other policies are immutable.

Parameters
self<<in>> Cannot be NULL.
qos<<in>> Set of policies to be applied to DDS_DomainParticipant. Policies must be consistent. Immutable policies cannot be changed after DDS_DomainParticipant is enabled. The special value DDS_PARTICIPANT_QOS_DEFAULT can be used to indicate that the QoS of the DDS_DomainParticipant should be changed to match the current default DDS_DomainParticipantQos set in the DDS_DomainParticipantFactory. Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY if an immutable policy is changed, or DDS_RETCODE_INCONSISTENT_POLICY if policies are inconsistent
See also
DDS_DomainParticipantQos for rules on consistency among QoS policies
set_qos (abstract)

◆ DDS_DomainParticipant_set_qos_with_profile()

DDS_ReturnCode_t DDS_DomainParticipant_set_qos_with_profile ( DDS_DomainParticipant self,
const char *  library_name,
const char *  profile_name 
)

<<extension>> Change the QoS of this domain participant using the input XML QoS profile.

The DDS_DomainParticipantQos::user_data and DDS_DomainParticipantQos::entity_factory can be changed. The other policies are immutable.

Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_DomainParticipantFactory_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_DomainParticipantFactory_set_default_profile).
Returns
One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY if immutable policy is changed, or DDS_RETCODE_INCONSISTENT_POLICY if policies are inconsistent
See also
DDS_DomainParticipantQos for rules on consistency among QoS

◆ DDS_DomainParticipant_get_qos()

DDS_ReturnCode_t DDS_DomainParticipant_get_qos ( DDS_DomainParticipant self,
struct DDS_DomainParticipantQos qos 
)

Get the participant QoS.

This function may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters
self<<in>> Cannot be NULL.
qos<<inout>> QoS to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
get_qos (abstract)

◆ DDS_DomainParticipant_set_property()

DDS_ReturnCode_t DDS_DomainParticipant_set_property ( DDS_DomainParticipant self,
const char *  property_name,
const char *  value,
DDS_Boolean  propagate 
)

Set the value for a property that applies to a DomainParticipant.

Warning
This function is not implemented in all APIs and it's intended only for testing purposes. You should use DDS_DomainParticipant_set_qos instead.
Parameters
self<<in>> Cannot be NULL.
property_name<<in>>. Name of the property that you want to set.
value<<in>>. New value for the property.
propagate<<in>>. Indicates if the property will be propagated or not.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_set_property
DDS_DataReader_set_property
DDS_DomainParticipant_set_qos

◆ DDS_DomainParticipant_set_listener()

DDS_ReturnCode_t DDS_DomainParticipant_set_listener ( DDS_DomainParticipant self,
const struct DDS_DomainParticipantListener l,
DDS_StatusMask  mask 
)

Sets the participant listener.

Parameters
self<<in>> Cannot be NULL.
l<<in>> Listener to be installed on the entity.
mask<<in>> Changes of communication status to be invoked on the listener. See DDS_StatusMask.

The callback function on the listener cannot be NULL if the corresponding status is turned on in the mask.

MT Safety:
Unsafe. This function is not synchronized with the listener callbacks, so it is possible to set a new listener on a participant when the old listener is in a callback.

Once a participant has been enabled, it is therefore important that the listener not be changed unless some application-specific means are available of ensuring that the old listener cannot be concurrently in use. If this contract is violated, it is possible for the DDS_Listener::listener_data field to have been changed without the callback function pointers having been changed (or vica versa); callback functions may therefore be passed an incorrect DDS_Listener::listener_data value.

Returns
One of the Standard Return Codes
See also
set_listener (abstract)

◆ DDS_DomainParticipant_get_listener()

struct DDS_DomainParticipantListener DDS_DomainParticipant_get_listener ( DDS_DomainParticipant self)

Get the participant listener.

Parameters
self<<in>> Cannot be NULL.
Returns
Existing listener attached to the DDS_DomainParticipant.
See also
DDS_DomainParticipant_get_listenerX
get_listener (abstract)

◆ DDS_DomainParticipant_get_listenerX()

DDS_ReturnCode_t DDS_DomainParticipant_get_listenerX ( DDS_DomainParticipant self,
struct DDS_DomainParticipantListener listener 
)

<<extension>> Get the participant listener.

An alternative form of DDS_DomainParticipant_get_listener that fills in an existing listener structure rather than returning one on the stack.

Parameters
self<<in>> Cannot be NULL.
listener<<inout>> Listener structure to be filled up. Cannnot be NULL.
See also
DDS_DomainParticipant_get_listener
get_listener (abstract)

◆ DDS_DomainParticipant_lookup_publisher_by_name()

DDS_Publisher * DDS_DomainParticipant_lookup_publisher_by_name ( DDS_DomainParticipant self,
const char *  publisher_name 
)

<<extension>> Looks up a DDS_Publisher by its entity name within this DDS_DomainParticipant.

Every DDS_Publisher in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.

This operation retrieves a DDS_Publisher within the DDS_DomainParticipant given the entity's name. If there are several DDS_Publisher with the same name within the DDS_DomainParticipant, this function returns the first matching occurrence.

Parameters
self<<in>> Cannot be NULL.
publisher_name<<in>> Entity name of the DDS_Publisher.
Returns
The first DDS_Publisher found with the specified name or NULL if it is not found.
See also
DDS_DomainParticipant_lookup_datawriter_by_name

◆ DDS_DomainParticipant_lookup_subscriber_by_name()

DDS_Subscriber * DDS_DomainParticipant_lookup_subscriber_by_name ( DDS_DomainParticipant self,
const char *  subscriber_name 
)

<<extension>> Retrieves a DDS_Subscriber by its entity name within this DDS_DomainParticipant.

Every DDS_Subscriber in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.

This operation retrieves a DDS_Subscriber within the DDS_DomainParticipant given the entity's name. If there are several DDS_Subscriber with the same name within the DDS_DomainParticipant, this function returns the first matching occurrence.

Parameters
self<<in>> Cannot be NULL.
subscriber_name<<in>> Entity name of the DDS_Subscriber.
Returns
The first DDS_Subscriber found with the specified name or NULL if it is not found.
See also
DDS_DomainParticipant_lookup_datareader_by_name

◆ DDS_DomainParticipant_lookup_datawriter_by_name()

DDS_DataWriter * DDS_DomainParticipant_lookup_datawriter_by_name ( DDS_DomainParticipant self,
const char *  datawriter_full_name 
)

<<extension>> Looks up a DDS_DataWriter by its entity name within this DDS_DomainParticipant.

Every DDS_DataWriter in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.

Every DDS_Publisher in the system has an entity name which is also configured and stored in the EntityName policy.

This operation retrieves a DDS_DataWriter within a DDS_Publisher given the specified name which encodes both to the DDS_DataWriter and the DDS_Publisher name.

If there are several DDS_DataWriter with the same name within the corresponding DDS_Publisher this function returns the first matching occurrence.

The specified name might be given as a fully-qualified entity name or as a plain name.

The fully qualified entity name is a concatenation of the DDS_Publisher to which the DDS_DataWriter belongs and the entity name of of the DDS_DataWriter itself, separated by a double colon "::". For example: MyPublisherName::MyDataWriterName

The plain name contains the DDS_DataWriter name only. In this situation it is implied that the DDS_DataWriter belongs to the implicit DDS_Publisher so the use of a plain name is equivalent to specifying a fully qualified name with the DDS_Publisher name part being "implicit". For example: the plain name "MyDataWriterName" is equivalent to specifiying the fully qualified name "implicit::MyDataWriterName"

The DDS_DataWriter is only looked up within the DDS_Publisher specified in the fully qualified name, or within the implicit DDS_Publisher if the name was not fully qualified.

Parameters
self<<in>> Cannot be NULL.
datawriter_full_name<<in>> Entity name or fully-qualified entity name of the DDS_DataWriter.
Returns
The first DDS_DataWriter found with the specified name or NULL if it is not found.
See also
DDS_Publisher_lookup_datawriter_by_name
DDS_DomainParticipant_lookup_publisher_by_name

◆ DDS_DomainParticipant_lookup_datareader_by_name()

DDS_DataReader * DDS_DomainParticipant_lookup_datareader_by_name ( DDS_DomainParticipant self,
const char *  datareader_full_name 
)

<<extension>> Retrieves up a DDS_DataReader by its entity name in this DDS_DomainParticipant.

Every DDS_DataReader in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.

Every DDS_Subscriber in the system has an entity name which is also configured and stored in the EntityName policy, ENTITY_NAME.

This operation retrieves a DDS_DataReader within a DDS_Subscriber given the specified name which encodes both to the DDS_DataReader and the DDS_Subscriber name.

If there are several DDS_DataReader with the same name within the corresponding DDS_Subscriber this function returns the first matching occurrence.

The specified name might be given as a fully-qualified entity name or as a plain name.

The fully qualified entity name is a concatenation of the DDS_Subscriber to which the DDS_DataReader belongs and the entity name of of the DDS_DataReader itself, separated by a double colon "::". For example: MySubscriberName::MyDataReaderName

The plain name contains the DDS_DataReader name only. In this situation it is implied that the DDS_DataReader belongs to the implicit DDS_Subscriber so the use of a plain name is equivalent to specifying a fully qualified name with the DDS_Subscriber name part being "implicit". For example: the plain name "MyDataReaderName" is equivalent to specifiying the fully qualified name "implicit::MyDataReaderName"

The DDS_DataReader is only looked up within the DDS_Subscriber specified in the fully qualified name, or within the implicit DDS_Subscriber if the name was not fully qualified.

Parameters
self<<in>> Cannot be NULL.
datareader_full_name<<in>> Full entity name of the DDS_DataReader.
Returns
The first DDS_DataReader found with the specified name or NULL if it is not found.
See also
DDS_Subscriber_lookup_datareader_by_name
DDS_DomainParticipant_lookup_subscriber_by_name

Variable Documentation

◆ DDS_DOMAINPARTICIPANTFACTORY_QOS_PRINT_ALL

const struct DDS_DomainParticipantFactoryQos* DDS_DOMAINPARTICIPANTFACTORY_QOS_PRINT_ALL
extern

Special value which can be supplied to DDS_DomainParticipantFactoryQos_to_string_w_params indicating that all of the QoS should be printed.

The DDS_DomainParticipantFactoryQos_to_string_w_params API accepts a base QoS profile as one of its arguments. The resultant string only contains the differences with respect to the supplied base QoS profile. Supplying the DDS_DOMAINPARTICIPANTFACTORY_QOS_PRINT_ALL sentinel value as the base QoS will result in all of the QoS being printed.

Note that there are some QoS policies and fields which are not intended for public use. Even when DDS_DOMAINPARTICIPANTFACTORY_QOS_PRINT_ALL is supplied as the base, these will not be printed unless they differ from the documented default. If you want to see their values, you must use the print_private field within the DDS_QosPrintFormat structure.

This value should only be used as the base parameter to the DDS_DomainParticipantFactoryQos_to_string_w_params API.

◆ DDS_DOMAINPARTICIPANT_QOS_PRINT_ALL

const struct DDS_DomainParticipantQos* DDS_DOMAINPARTICIPANT_QOS_PRINT_ALL
extern

Special value which can be supplied to DDS_DomainParticipantQos_to_string_w_params indicating that all of the QoS should be printed.

The DDS_DomainParticipantQos_to_string_w_params API accepts a base QoS profile as one of its arguments. The resultant string only contains the differences with respect to the supplied base QoS profile. Supplying the DDS_DOMAINPARTICIPANT_QOS_PRINT_ALL sentinel value as the base QoS will result in all of the QoS being printed.

Note that there are some QoS policies and fields which are not intended for public use. Even when DDS_DOMAINPARTICIPANT_QOS_PRINT_ALL is supplied as the base, these will not be printed unless they differ from the documented default. If you want to see their values, you must use the print_private field within the DDS_QosPrintFormat structure.

This value should only be used as the base parameter to the DDS_DomainParticipantQos_to_string_w_params API.

◆ DDS_TOPIC_QOS_DEFAULT

const struct DDS_TopicQos DDS_TOPIC_QOS_DEFAULT
extern

Special value for creating a DDS_Topic with default QoS.

When used in DDS_DomainParticipant_create_topic, this special value is used to indicate that the DDS_Topic should be created with the default DDS_Topic QoS by means of the operation get_default_topic_qos and using the resulting QoS to create the DDS_Topic.

When used in DDS_DomainParticipant_set_default_topic_qos, this special value is used to indicate that the default QoS should be reset back to the initial value that would be used if the DDS_DomainParticipant_set_default_topic_qos operation had never been called.

When used in DDS_Topic_set_qos, this special value is used to indicate that the QoS of the DDS_Topic should be changed to match the current default QoS set in the DDS_DomainParticipant that the DDS_Topic belongs to.

Warning
This value is a constant and should never be modified. You cannot use this value to get the default QoS values for a Topic; for this purpose, use DDS_DomainParticipant_get_default_topic_qos.
See also
DDS_DomainParticipant_create_topic
DDS_DomainParticipant_set_default_topic_qos
DDS_Topic_set_qos
Examples
HelloWorld_publisher.c, and HelloWorld_subscriber.c.

◆ DDS_PUBLISHER_QOS_DEFAULT

const struct DDS_PublisherQos DDS_PUBLISHER_QOS_DEFAULT
extern

Special value for creating a DDS_Publisher with default QoS.

When used in DDS_DomainParticipant_create_publisher, this special value is used to indicate that the DDS_Publisher should be created with the default DDS_Publisher QoS by means of the operation get_default_publisher_qos and using the resulting QoS to create the DDS_Publisher.

When used in DDS_DomainParticipant_set_default_publisher_qos, this special value is used to indicate that the default QoS should be reset back to the initial value that would be used if the DDS_DomainParticipant_set_default_publisher_qos operation had never been called.

When used in DDS_Publisher_set_qos, this special value is used to indicate that the QoS of the DDS_Publisher should be changed to match the current default QoS set in the DDS_DomainParticipant that the DDS_Publisher belongs to.

Warning
This value is a constant and should never be modified. You cannot use this value to get the default QoS values for a Publisher; for this purpose, use DDS_DomainParticipant_get_default_publisher_qos.
See also
DDS_DomainParticipant_create_publisher
DDS_DomainParticipant_set_default_publisher_qos
DDS_Publisher_set_qos
Examples
HelloWorld_publisher.c.

◆ DDS_SUBSCRIBER_QOS_DEFAULT

const struct DDS_SubscriberQos DDS_SUBSCRIBER_QOS_DEFAULT
extern

Special value for creating a DDS_Subscriber with default QoS.

When used in DDS_DomainParticipant_create_subscriber, this special value is used to indicate that the DDS_Subscriber should be created with the default DDS_Subscriber QoS by means of the operation get_default_subscriber_qos and using the resulting QoS to create the DDS_Subscriber.

When used in DDS_DomainParticipant_set_default_subscriber_qos, this special value is used to indicate that the default QoS should be reset back to the initial value that would be used if the DDS_DomainParticipant_set_default_subscriber_qos operation had never been called.

When used in DDS_Subscriber_set_qos, this special value is used to indicate that the QoS of the DDS_Subscriber should be changed to match the current default QoS set in the DDS_DomainParticipant that the DDS_Subscriber belongs to.

Warning
This value is a constant and should never be modified. You cannot use this value to get the default QoS values for a Subscriber; for this purpose, use DDS_DomainParticipant_get_default_subscriber_qos.
See also
DDS_DomainParticipant_create_subscriber
DDS_DomainParticipant_get_default_subscriber_qos
DDS_Subscriber_set_qos
Examples
HelloWorld_subscriber.c.

◆ DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT

const struct DDS_FlowControllerProperty_t DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT
extern

<<extension>> Special value for creating a DDS_FlowController with default property.

When used in DDS_DomainParticipant_create_flowcontroller and DDS_FlowController_set_property, this special value represents the set of values specified on the last successful call to DDS_DomainParticipant_set_default_flowcontroller_property, or else, if the call was never made, the default values listed in DDS_FlowControllerProperty_t.

When used in DDS_DomainParticipant_set_default_flowcontroller_property, this special value indicates that the default QoS should be reset back to the initial value that would be used if the DDS_DomainParticipant_set_default_flowcontroller_property operation had never been called.

Warning
This value is a constant and should never be modified. You cannot use this value to get the default properties for a FlowController; for this purpose, use DDS_DomainParticipant_get_default_flowcontroller_property.
See also
DDS_DomainParticipant_create_flowcontroller
DDS_DomainParticipant_set_default_flowcontroller_property
DDS_FlowController_set_property

◆ DDS_PUBLISHER_QOS_PRINT_ALL

const struct DDS_PublisherQos* DDS_PUBLISHER_QOS_PRINT_ALL
extern

Special value which can be supplied to DDS_PublisherQos_to_string_w_params indicating that all of the QoS should be printed.

The DDS_PublisherQos_to_string_w_params API accepts a base QoS profile as one of its arguments. The resultant string only contains the differences with respect to the supplied base QoS profile. Supplying the DDS_PUBLISHER_QOS_PRINT_ALL sentinel value as the base QoS will result in all of the QoS being printed.

Note that there are some QoS policies and fields which are not intended for public use. Even when DDS_PUBLISHER_QOS_PRINT_ALL is supplied as the base, these will not be printed unless they differ from the documented default. If you want to see their values, you must use the print_private field within the DDS_QosPrintFormat structure.

This value should only be used as the base parameter to the DDS_PublisherQos_to_string_w_params API.

◆ DDS_SQLFILTER_NAME

const char* const DDS_SQLFILTER_NAME

<<extension>> The name of the built-in SQL filter that can be used with ContentFilteredTopics and MultiChannel DataWriters.

See also
Queries and Filters Syntax

◆ DDS_STRINGMATCHFILTER_NAME

const char* const DDS_STRINGMATCHFILTER_NAME

<<extension>> The name of the built-in StringMatch filter that can be used with ContentFilteredTopics and MultiChannel DataWriters.

The StringMatch Filter is a subset of the SQL filter; it only supports the MATCH relational operator on a single string field.

See also
Queries and Filters Syntax

◆ DDS_SUBSCRIBER_QOS_PRINT_ALL

const struct DDS_SubscriberQos* DDS_SUBSCRIBER_QOS_PRINT_ALL
extern

Special value which can be supplied to DDS_SubscriberQos_to_string_w_params indicating that all of the QoS should be printed.

The DDS_SubscriberQos_to_string_w_params API accepts a base QoS profile as one of its arguments. The resultant string only contains the differences with respect to the supplied base QoS profile. Supplying the DDS_SUBSCRIBER_QOS_PRINT_ALL sentinel value as the base QoS will result in all of the QoS being printed.

Note that there are some QoS policies and fields which are not intended for public use. Even when DDS_SUBSCRIBER_QOS_PRINT_ALL is supplied as the base, these will not be printed unless they differ from the documented default. If you want to see their values, you must use the print_private field within the DDS_QosPrintFormat structure.

This value should only be used as the base parameter to the DDS_SubscriberQos_to_string_w_params API.

◆ DDS_TOPIC_QOS_PRINT_ALL

const struct DDS_TopicQos* DDS_TOPIC_QOS_PRINT_ALL
extern

Special value which can be supplied to DDS_TopicQos_to_string_w_params indicating that all of the QoS should be printed.

The DDS_TopicQos_to_string_w_params API accepts a base QoS profile as one of its arguments. The resultant string only contains the differences with respect to the supplied base QoS profile. Supplying the DDS_TOPIC_QOS_PRINT_ALL sentinel value as the base QoS will result in all of the QoS being printed.

Note that there are some QoS policies and fields which are not intended for public use. Even when DDS_TOPIC_QOS_PRINT_ALL is supplied as the base, these will not be printed unless they differ from the documented default. If you want to see their values, you must use the print_private field within the DDS_QosPrintFormat structure.

This value should only be used as the base parameter to the DDS_TopicQos_to_string_w_params API.