|
RTI Connext C API Version 7.3.0
|
DDS_DomainParticipantFactory entity and associated elements More...
Modules | |
| DomainParticipantConfigParams | |
| <<extension>> DDS_DomainParticipantConfigParams_t | |
Data Structures | |
| struct | DDS_DomainParticipantFactoryQos |
| QoS policies supported by a DDS_DomainParticipantFactory. More... | |
Macros | |
| #define | DDS_DomainParticipantFactoryQos_INITIALIZER |
| Initializer for new QoS instances. More... | |
| #define | DDS_TheParticipantFactory DDS_DomainParticipantFactory_get_instance() |
| Can be used as an alias for the singleton factory returned by the operation DDS_DomainParticipantFactory_get_instance. More... | |
Typedefs | |
| typedef struct DDS_DomainParticipantFactoryImpl | DDS_DomainParticipantFactory |
| <<singleton>> <<interface>> Allows creation and destruction of DDS_DomainParticipant objects. More... | |
| typedef DDS_ReturnCode_t(* | DDS_DomainParticipantFactory_RegisterTypeFunction) (DDS_DomainParticipant *participant, const char *type_name) |
| Prototype of a register type function. More... | |
Variables | |
| const struct DDS_DomainParticipantQos | DDS_PARTICIPANT_QOS_DEFAULT |
| Special value for creating a DomainParticipant with default QoS. More... | |
| const struct DDS_DomainParticipantConfigParams_t | DDS_PARTICIPANT_CONFIG_PARAMS_DEFAULT |
| Special value for creating a DDS_DomainParticipant from configuration using default parameters. More... | |
DDS_DomainParticipantFactory entity and associated elements
| #define DDS_DomainParticipantFactoryQos_INITIALIZER |
Initializer for new QoS instances.
New DDS_DomainParticipantFactoryQos instances stored on the stack should be initialized with this value before they are passed to any function. 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:
Note that the above assignment is not a substitute for calling DDS_DomainParticipantFactory_get_qos; that function should be called subsequently to setting the QoS. DDS_DomainParticipantFactoryQos_finalize should be called to free the contained QoS policies that use dynamic memory:
| #define DDS_TheParticipantFactory DDS_DomainParticipantFactory_get_instance() |
Can be used as an alias for the singleton factory returned by the operation DDS_DomainParticipantFactory_get_instance.
| typedef struct DDS_DomainParticipantFactoryImpl DDS_DomainParticipantFactory |
<<singleton>> <<interface>> Allows creation and destruction of DDS_DomainParticipant objects.
The sole purpose of this class is to allow the creation and destruction of DDS_DomainParticipant objects. This class itself is a <<singleton>>, and accessed via the get_instance() function, and destroyed with finalize_instance() function.
A single application can participate in multiple domains by instantiating multiple DDS_DomainParticipant objects.
An application may even instantiate multiple participants in the same domain. Participants in the same domain exchange data in the same way regardless of whether they are in the same application or different applications or on the same node or different nodes; their location is transparent.
There are two important caveats:
| typedef DDS_ReturnCode_t(* DDS_DomainParticipantFactory_RegisterTypeFunction) (DDS_DomainParticipant *participant, const char *type_name) |
Prototype of a register type function.
| participant | <<inout>> DDS_DomainParticipant participant the type is registered with. |
| type_name | <<in>> Name the type is registered with. |
| DDS_Boolean DDS_DomainParticipantFactoryQos_equals | ( | const struct DDS_DomainParticipantFactoryQos * | self, |
| const struct DDS_DomainParticipantFactoryQos * | other | ||
| ) |
Compares two DDS_DomainParticipantFactoryQos for equality.
| self | <<in>> This DomainParticipantFactoryQos. |
| other | <<in>> The other DomainParticipantFactoryQos to be compared with this DomainParticipantFactoryQos. |
| DDS_ReturnCode_t DDS_DomainParticipantFactoryQos_print | ( | const struct DDS_DomainParticipantFactoryQos * | self | ) |
Prints this DDS_DomainParticipantFactoryQos to stdout.
Only the differences between this DDS_DomainParticipantFactoryQos and the documented default are printed. If you wish to print everything regardless, see DDS_DomainParticipantFactoryQos_to_string_w_params. The output is formatted according to the default values for DDS_QosPrintFormat.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactoryQos_to_string | ( | const struct DDS_DomainParticipantFactoryQos * | self, |
| char * | string, | ||
| DDS_UnsignedLong * | string_size | ||
| ) |
Obtains a string representation of this DDS_DomainParticipantQos.
Only the differences between this DDS_DomainParticipantFactoryQos and the documented default are printed to the string. If you wish to print everything regardless, see DDS_DomainParticipantFactoryQos_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_DomainParticipantFactoryQos is written to the buffer.
| self | <<in>> Cannot be NULL. |
| string | <<out>> The char buffer that will be used to store the string representation of this DDS_DomainParticipantFactoryQos. 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. |
| DDS_ReturnCode_t DDS_DomainParticipantFactoryQos_to_string_w_params | ( | const struct DDS_DomainParticipantFactoryQos * | self, |
| char * | string, | ||
| DDS_UnsignedLong * | string_size, | ||
| const struct DDS_DomainParticipantFactoryQos * | base, | ||
| const struct DDS_QosPrintFormat * | format | ||
| ) |
Obtains a string representation of this DDS_DomainParticipantFactoryQos.
Only the differences between this DDS_DomainParticipantFactoryQos and the DDS_DomainParticipantFactoryQos supplied as the base are printed to the string.
It is possible to supply the sentinel value DDS_DOMAINPARTICIPANTFACTORY_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_DomainParticipantFactoryQos is written to the buffer.
| self | <<in>> Cannot be NULL. |
| string | <<out>> The char buffer that will be used to store the string representation of this DDS_DomainParticipantFactoryQos. 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_DomainParticipantFactoryQos 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. |
| DDS_ReturnCode_t DDS_DomainParticipantFactoryQos_initialize | ( | struct DDS_DomainParticipantFactoryQos * | self | ) |
Initializer for new QoS instances.
New DDS_DomainParticipantFactoryQos instances on heap should be initialized with this function before they are passed to any function. 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_DomainParticipantFactory_get_qos; that function should be called subsequently to setting the QoS of an existing factory. DDS_DomainParticipantFactoryQos_finalize should be called to free the contained QoS policies that use dynamic memory:
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactoryQos_finalize | ( | struct DDS_DomainParticipantFactoryQos * | self | ) |
Free any dynamic memory allocated by the policies in this DDS_DomainParticipantFactoryQos.
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 clear 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.
| DDS_ReturnCode_t DDS_DomainParticipantFactoryQos_copy | ( | struct DDS_DomainParticipantFactoryQos * | self, |
| const struct DDS_DomainParticipantFactoryQos * | source | ||
| ) |
Copy the contents of the given QoS into this QoS.
DDS_DomainParticipantFactoryQos 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.
| DDS_DomainParticipantFactory * DDS_DomainParticipantFactory_get_instance | ( | void | ) |
Gets the singleton instance of this class.
DDS_TheParticipantFactory can be used as an alias for the singleton factory returned by this operation.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_finalize_instance | ( | void | ) |
<<extension>> Destroys the singleton instance of this class.
Only necessary to explicitly reclaim resources used by the participant factory singleton. Note that on many OSs, these resources are automatically reclaimed by the OS when the program terminates. However, some memory-check tools still flag these as unreclaimed. So this function provides a way to clean up memory used by the participant factory.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_set_default_participant_qos | ( | DDS_DomainParticipantFactory * | self, |
| const struct DDS_DomainParticipantQos * | qos | ||
| ) |
Sets the default DDS_DomainParticipantQos values for this domain participant factory.
This function may potentially allocate memory depending on the sequences contained in some QoS policies.
| self | <<in>> Cannot be NULL. |
| qos | <<inout>> Qos to be filled up. The special value DDS_PARTICIPANT_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_DomainParticipantFactory_set_default_participant_qos had never been called. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_set_default_participant_qos_with_profile | ( | DDS_DomainParticipantFactory * | self, |
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Sets the default DDS_DomainParticipantQos values for this domain participant factory based on the input XML QoS profile.
This function may potentially allocate memory depending on the sequences contained in some QoS policies.
This default value will be used for newly created DDS_DomainParticipant if DDS_PARTICIPANT_QOS_DEFAULT is specified as the qos parameter when DDS_DomainParticipantFactory_create_participant is called.
| 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). |
If the input profile cannot be found the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_default_participant_qos | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_DomainParticipantQos * | qos | ||
| ) |
Initializes the DDS_DomainParticipantQos instance with default values.
The retrieved qos will match the set of values specified on the last successful call to DDS_DomainParticipantFactory_set_default_participant_qos, or DDS_DomainParticipantFactory_set_default_participant_qos_with_profile, or else, if the call was never made, the default values listed in DDS_DomainParticipantQos.
This function may potentially allocate memory depending on the sequences contained in some QoS policies.
| DDS_DomainParticipant * DDS_DomainParticipantFactory_create_participant | ( | DDS_DomainParticipantFactory * | self, |
| DDS_DomainId_t | domainId, | ||
| const struct DDS_DomainParticipantQos * | qos, | ||
| const struct DDS_DomainParticipantListener * | listener, | ||
| DDS_StatusMask | mask | ||
| ) |
Creates a new DDS_DomainParticipant object.
If you want to create multiple participants on a given host in the same domain, make sure each one has a different participant index (set in the DDS_WireProtocolQosPolicy). This in turn will ensure each participant uses a different port number (since the unicast port numbers are calculated from the participant index and the domain ID).
Note that if there is a single participant per host in a given domain, the participant index can be left at the default value (-1).
listener is specified, none of the listener callback functions can be NULL. | self | <<in>> Cannot be NULL. |
| domainId | <<in>> ID of the domain that the application intends to join. [range] [>=0], and does not violate guidelines stated in DDS_RtpsWellKnownPorts_t. |
| qos | <<in>> the DomainParticipant's QoS. The special value DDS_PARTICIPANT_QOS_DEFAULT can be used to indicate that the DDS_DomainParticipant should be created with the default DDS_DomainParticipantQos set in the DDS_DomainParticipantFactory. Cannot be NULL. |
| listener | <<in>> the domain participant's listener. |
| mask | <<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask. |
| DDS_DomainParticipant * DDS_DomainParticipantFactory_create_participant_with_profile | ( | DDS_DomainParticipantFactory * | self, |
| DDS_DomainId_t | domainId, | ||
| const char * | library_name, | ||
| const char * | profile_name, | ||
| const struct DDS_DomainParticipantListener * | listener, | ||
| DDS_StatusMask | mask | ||
| ) |
<<extension>> Creates a new DDS_DomainParticipant object using the DDS_DomainParticipantQos associated with the input XML QoS profile.
If you want to create multiple participants on a given host in the same domain, make sure each one has a different participant index (set in the DDS_WireProtocolQosPolicy). This in turn will ensure each participant uses a different port number (since the unicast port numbers are calculated from the participant index and the domain ID).
Note that if there is a single participant per host in a given domain, the participant index can be left at the default value (-1).
listener is specified, none of the listener callback functions can be NULL. | self | <<in>> Cannot be NULL. |
| domainId | <<in>> ID of the domain that the application intends to join. [range] [>=0], and does not violate guidelines stated in DDS_RtpsWellKnownPorts_t. |
| 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). |
| listener | <<in>> the DomainParticipant's listener. |
| mask | <<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_delete_participant | ( | DDS_DomainParticipantFactory * | self, |
| DDS_DomainParticipant * | a_participant | ||
| ) |
Deletes an existing DDS_DomainParticipant.
| self | <<in>> Cannot be NULL. |
| a_participant | <<in>> DDS_DomainParticipant to be deleted. |
| DDS_DomainParticipant * DDS_DomainParticipantFactory_lookup_participant | ( | DDS_DomainParticipantFactory * | self, |
| DDS_DomainId_t | domainId | ||
| ) |
Locates an existing DDS_DomainParticipant.
If no such DDS_DomainParticipant exists, the operation will return NULL value.
If multiple DDS_DomainParticipant entities belonging to that domainId exist, then the operation will return one of them. It is not specified which one.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_qos | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_DomainParticipantFactoryQos * | qos | ||
| ) |
Gets the value for participant factory QoS.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_set_qos | ( | DDS_DomainParticipantFactory * | self, |
| const struct DDS_DomainParticipantFactoryQos * | qos | ||
| ) |
Sets the value for a participant factory QoS.
The DDS_DomainParticipantFactoryQos::entity_factory can be changed. The other policies are immutable.
Note that despite having QoS, the DDS_DomainParticipantFactory is not an DDS_Entity.
| self | <<in>> Cannot be NULL. |
| qos | <<in>> Set of policies to be applied to DDS_DomainParticipantFactory. Policies must be consistent. Immutable policies can only be changed before calling any other RTI Connext functions except for DDS_DomainParticipantFactory_get_qos Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_load_profiles | ( | DDS_DomainParticipantFactory * | self | ) |
<<extension>> Loads the XML QoS profiles.
The XML QoS profiles are loaded implicitly after the first DDS_DomainParticipant is created or explicitly, after a call to this function.
This has the same effect as DDS_DomainParticipantFactory_reload_profiles().
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_reload_profiles | ( | DDS_DomainParticipantFactory * | self | ) |
<<extension>> Reloads the XML QoS profiles.
The XML QoS profiles are loaded implicitly after the first DDS_DomainParticipant is created or explicitly, after a call to this function.
This has the same effect as DDS_DomainParticipantFactory_load_profiles().
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_unload_profiles | ( | DDS_DomainParticipantFactory * | self | ) |
<<extension>> Unloads the XML QoS profiles.
The resources associated with the XML QoS profiles are freed. Any reference to the profiles after calling this function will fail with an error.
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_set_default_library | ( | DDS_DomainParticipantFactory * | self, |
| const char * | library_name | ||
| ) |
<<extension>> Sets the default XML library for a DDS_DomainParticipantFactory.
Any API requiring a library_name as a parameter can use NULL to refer to the default library set with this function.
Note: if the library set with this function no longer exists after reloading the QoS profiles (for example, by changing DDS_DomainParticipantFactoryQos::profile) the default library will be set to the last library containing a profile with the attribute is_default_qos=true or NULL no such library exists.
| self | <<in>> Cannot be NULL. |
| library_name | <<in>> Library name. If library_name is NULL any previous default is unset. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_set_default_profile | ( | DDS_DomainParticipantFactory * | self, |
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Sets the default XML profile for a DDS_DomainParticipantFactory.
This function specifies the profile that will be used as the default the next time a default DomainParticipantFactory profile is needed during a call to a DomainParticipantFactory function. When calling a DDS_DomainParticipantFactory 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.)
This function does not set the default QoS for newly created DomainParticipants; for this functionality, use DDS_DomainParticipantFactory_set_default_participant_qos_with_profile (you may pass in NULL after having called set_default_profile()).
Note: if the profile set with this function no longer exists after reloading the QoS profiles (for example, by changing DDS_DomainParticipantFactoryQos::profile) the default profile will be set to the last one marked with the attribute is_default_qos=true or NULL no such profile exists.
| 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. |
| const char * DDS_DomainParticipantFactory_get_default_library | ( | DDS_DomainParticipantFactory * | self | ) |
<<extension>> Gets the default XML library associated with a DDS_DomainParticipantFactory.
| self | <<in>> Cannot be NULL. |
is_default_qos="true", this function returns the library where the last one is contained. | const char * DDS_DomainParticipantFactory_get_default_profile | ( | DDS_DomainParticipantFactory * | self | ) |
<<extension>> Gets the default XML profile associated with a DDS_DomainParticipantFactory.
| self | <<in>> Cannot be NULL. |
is_default_qos="true", this function returns the name of one of them | const char * DDS_DomainParticipantFactory_get_default_profile_library | ( | DDS_DomainParticipantFactory * | self | ) |
<<extension>> Gets the library where the default XML profile is contained for a DDS_DomainParticipantFactory.
The default profile library is automatically set when DDS_DomainParticipantFactory_set_default_profile is called.
This library can be different than the DDS_DomainParticipantFactory default library (see DDS_DomainParticipantFactory_get_default_library).
| self | <<in>> Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_participant_factory_qos_from_profile | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_DomainParticipantFactoryQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Gets the DDS_DomainParticipantFactoryQos values associated with the input XML QoS profile.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_participant_qos_from_profile | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_DomainParticipantQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Gets the DDS_DomainParticipantQos values associated with the input XML QoS profile.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_publisher_qos_from_profile | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_PublisherQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Gets the DDS_PublisherQos values associated with the input XML QoS profile.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_subscriber_qos_from_profile | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_SubscriberQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Gets the DDS_SubscriberQos values associated with the input XML QoS profile.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_datareader_qos_from_profile | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_DataReaderQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Gets the DDS_DataReaderQos values associated with the input XML QoS profile.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_datareader_qos_from_profile_w_topic_name | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_DataReaderQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name, | ||
| const char * | topic_name | ||
| ) |
<<extension>> Gets the DDS_DataReaderQos values associated with the input XML QoS profile while applying topic filters to the input topic name.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
| topic_name | <<in>> Topic name that will be evaluated against the topic_filter attribute in the XML QoS profile. If topic_name is null, RTI Connext will match only QoSs without explicit topic_filter expressions. |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_datawriter_qos_from_profile | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_DataWriterQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Gets the DDS_DataWriterQos values associated with the input XML QoS profile.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_datawriter_qos_from_profile_w_topic_name | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_DataWriterQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name, | ||
| const char * | topic_name | ||
| ) |
<<extension>> Gets the DDS_DataWriterQos values associated with the input XML QoS profile while applying topic filters to the input topic name.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
| topic_name | <<in>> Topic name that will be evaluated against the topic_filter attribute in the XML QoS profile. If topic_name is null, RTI Connext will match only QoSs without explicit topic_filter expressions. |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_topic_qos_from_profile | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_TopicQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name | ||
| ) |
<<extension>> Gets the DDS_TopicQos values associated with the input XML QoS profile.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_topic_qos_from_profile_w_topic_name | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_TopicQos * | qos, | ||
| const char * | library_name, | ||
| const char * | profile_name, | ||
| const char * | topic_name | ||
| ) |
<<extension>> Gets the DDS_TopicQos values associated with the input XML QoS profile while applying topic filters to the input topic name.
| self | <<in>> Cannot be NULL. |
| qos | <<out>> Qos to be filled up. 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). |
| topic_name | <<in>> Topic name that will be evaluated against the topic_filter attribute in the XML QoS profile. If topic_name is null, RTI Connext will match only QoSs without explicit topic_filter expressions. |
If the input profile cannot be found, the function fails with DDS_RETCODE_ERROR.
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_qos_profile_libraries | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_StringSeq * | library_names | ||
| ) |
<<extension>> Gets the names of all XML QoS profile libraries associated with the DDS_DomainParticipantFactory
| self | <<in>> Cannot be NULL. |
| library_names | <<out>> DDS_StringSeq to be filled with names of XML QoS profile libraries. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_qos_profiles | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_StringSeq * | profile_names, | ||
| const char * | library_name | ||
| ) |
<<extension>> Gets the names of all XML QoS profiles associated with the input XML QoS profile library.
| self | <<in>> Cannot be NULL. |
| profile_names | <<out>> DDS_StringSeq to be filled with names of XML QoS profiles. 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). |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_unregister_thread | ( | DDS_DomainParticipantFactory * | self | ) |
<<extension>> Allows the user to release thread specific resources kept by the middleware.
This function should be called by the user right before exiting a thread where DDS API were used. In this way the middleware will be able to free all the resources related to this specific thread. The best approach is to call the function during the thread deletion after all the DDS related API have have been called.
| self | <<in>> Cannot be NULL. |
| const DDS_TypeCode * DDS_DomainParticipantFactory_get_typecode_from_config | ( | DDS_DomainParticipantFactory * | self, |
| const char * | type_name | ||
| ) |
<<extension>> Gets a DDS_TypeCode from a definition provided in an XML configuration file.
| DDS_DomainParticipant * DDS_DomainParticipantFactory_create_participant_from_config | ( | DDS_DomainParticipantFactory * | self, |
| const char * | configuration_name | ||
| ) |
<<extension>> Creates a DDS_DomainParticipant given its configuration name from a description provided in an XML configuration file.
This operation creates a DDS_DomainParticipant registering all the necessary data types and creating all the contained entities (DDS_Topic, DDS_Publisher, DDS_Subscriber, DDS_DataWriter, DDS_DataReader) from a description given in an XML configuration file.
The configuration name is the fully qualified name of the XML participant object, consisting of the name of the participant library plus the name of participant configuration.
For example the name "MyParticipantLibrary::PublicationParticipant" can be used to create the domain participant from the description in an XML file with contents shown in the snippet below:
The entities belonging to the newly created DDS_DomainParticipant can be retrieved with the help of lookup operations such as: DDS_DomainParticipant_lookup_datareader_by_name.
This operation is equivalent to call DDS_DomainParticipantFactory_create_participant_from_config_w_params passing DDS_PARTICIPANT_CONFIG_PARAMS_DEFAULT as parameters.
| self | <<in>> Cannot be NULL. |
| configuration_name | <<in>> Name of the participant configuration in the XML file. |
| DDS_DomainParticipant * DDS_DomainParticipantFactory_create_participant_from_config_w_params | ( | DDS_DomainParticipantFactory * | self, |
| const char * | configuration_name, | ||
| const struct DDS_DomainParticipantConfigParams_t * | params | ||
| ) |
<<extension>> Creates a DDS_DomainParticipant given its configuration name from a description provided in an XML configuration file and a set of parameters that allow changing some properties of such configuration.
The operation will create a DDS_DomainParticipant the same way specified in DDS_DomainParticipantFactory_create_participant_from_config.
In addition, this operation allows overriding the domain ID, participant name, and entities QoS specified in the configuration.
| self | <<in>> Cannot be NULL. |
| configuration_name | <<in>> Name of the participant configuration in the XML file. |
| params | <<in>> input parameters that allow changing some properties of the configuration referred to by configuration_name. |
| DDS_DomainParticipant * DDS_DomainParticipantFactory_lookup_participant_by_name | ( | DDS_DomainParticipantFactory * | self, |
| const char * | participant_name | ||
| ) |
<<extension>> Looks up a DDS_DomainParticipant by its entity name in the DDS_DomainParticipantFactory.
Every DDS_DomainParticipant in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.
This operation retrieves a DDS_DomainParticipant within the DDS_DomainParticipantFactory given the entity's name. If there are several DDS_DomainParticipant with the same name within the DDS_DomainParticipantFactory this function returns the first matching occurrence.
| self | <<in>> Cannot be NULL. |
| participant_name | <<in>> Entity name of the DDS_DomainParticipant. Cannot be NULL. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_register_type_support | ( | DDS_DomainParticipantFactory * | self, |
| DDS_DomainParticipantFactory_RegisterTypeFunction | register_type_fcn, | ||
| const char * | type_name | ||
| ) |
<<extension>> Registers a DDS_TypeSupport with the DDS_DomainParticipantFactory to enable automatic registration if the corresponding type, should it be needed by a DDS_DomainParticipant.
Types refered by the DDS_Topic entities within a DDS_DomainParticipant must be registered with the DDS_DomainParticipant.
Type registration in a DDS_DomainParticipant is performed by a call to the FooTypeSupport_register_type operation. This can be done directly from the application code or indirectly by the RTI Connext infrastructure as a result of parsing an XML configuration file that refers to that type.
The DDS_DomainParticipantFactory_register_type_support operation provides the DDS_DomainParticipantFactory with the information it needs to automatically call the FooTypeSupport_register_type operation and register the corresponding type if the type is needed as a result of parsing an XML configuration file.
Automatic type registration while parsing XML files can also be done by the RTI Connext infrastructure based on the type description provided in the XML files. If the DDS_TypeSupport has been registered with the DDS_DomainParticipantFactory this definition takes precedence over the description of the type given in the XML file.
The DDS_DomainParticipantFactory_register_type_support operation receives a FooTypeSupport_register_type function as a parameter. This function is normally generated using rtiddsgen from a description of the corresponsing type in IDL, XML, or XSD.
The typical workflow when using this function is as follows: Define the data-type in IDL (or XML, or XSD) in a file. E.g. Foo.idl Run rtiddsgen in that file to generate the TypeSupport files, for the desired programming language. E.g. in C++ FooTypeSupport.h FooTypeSupport.cxx Include the proper header file (e.g. FooTypeSupport.h) in your program and call DDS_DomainParticipantFactory_register_type_support passing the function that was generated by rtiddsgen. E.g. FooTypeSupport::register_type Include the TypeSupport source file in your project such that it is compiled and linked. E.g. FooTypeSupport.cxx
You may refer to the Getting Started Guide for additional details in this process.
Note that only one register function is allowed per registered type name.
| self | <<in>> Cannot be NULL. |
| register_type_fcn | <<in>> DDS_DomainParticipantFactory_RegisterTypeFunction to be used for registering the type with a DDS_DomainParticipant. |
| type_name | <<in>> Name the type is registered with. |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_get_participants | ( | DDS_DomainParticipantFactory * | self, |
| struct DDS_DomainParticipantSeq * | participants | ||
| ) |
<<extension>> Allows the application to access all the participants the DomainParticipantFactory has.
If the sequence doesn't own its buffer, and its maximum is less than the total number of participants, it will be filled up to its maximum, and fail with DDS_RETCODE_OUT_OF_RESOURCES.
DomainParticipants are ordered in the output sequence from the most recently created to the oldest.
| self | <<in>> Cannot be NULL. |
| participants | <<inout>> a DomainParticipantSeq object where the set or list of participants will be returned |
| DDS_ReturnCode_t DDS_DomainParticipantFactory_set_thread_factory | ( | DDS_DomainParticipantFactory * | self, |
| const struct DDS_ThreadFactory * | thread_factory | ||
| ) |
<<extension>> Sets a DDS_ThreadFactory in the DDS_DomainParticipantFactory that will be used to create the internal threads of the DDS middleware.
DDS threads are managed by the DDS_DomainParticipant, which is responsible for creating and deleting threads throughout its lifecycle. Some threads are created when the DDS_DomainParticipant gets enabled (i.e., database, event, etc.) and others when special features are enabled (i.e., asynchronous publication thread).
DDS threads have DDS_DomainParticipant scope. This means every DomainParticipant creates all the necessary threads to operate and each DDS_DomainParticipant will create its own independent set of threads.
Each DDS_DomainParticipant creates an independent set of DDS threads and will use the DDS_ThreadFactory that is held by the DDS_DomainParticipantFactory at the time the DomainParticipant is created. A DDS_ThreadFactory is immutable from a DDS_DomainParticipant point of view. This means that a DDS_DomainParticipant will use throughout its lifecycle the same DDS_ThreadFactory that was set when it was created, even if a new DDS_ThreadFactory is set in the DDS_DomainParticipantFactory later. That is, if a new DDS_ThreadFactory is set, a previously created DDS_DomainParticipant will not be affected.
ThreadFactory lifecycle: A DDS_ThreadFactory instance must be alive while there are DomainParticipants using it. A DDS_ThreadFactory instance can be deleted only after all DomainParticipants using it are deleted.
By default, the DDS_DomainParticipantFactory has an internal DDS_ThreadFactory so threads are created automatically by the core product. These threads are usually created using the typical framework for the target platform (i.e., pthread for Linux systems).
| self | <<in>> Cannot be NULL. |
| thread_factory | <<in>> Instance of a DDS_ThreadFactory to be used for creating the DDS threads. If null is specified, the current DDS_ThreadFactory is removed and the internal default will be used. |
|
extern |
Special value for creating a DomainParticipant with default QoS.
When used in DDS_DomainParticipantFactory_create_participant, this special value is used to indicate that the DDS_DomainParticipant should be created with the default DDS_DomainParticipant QoS by means of the operation DDS_DomainParticipantFactory_get_default_participant_qos() and using the resulting QoS to create the DDS_DomainParticipant.
When used in DDS_DomainParticipantFactory_set_default_participant_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_DomainParticipantFactory_set_default_participant_qos operation had never been called.
When used in DDS_DomainParticipant_set_qos, this special value is used to indicate that the QoS of the DDS_DomainParticipant should be changed to match the current default QoS set in the DDS_DomainParticipantFactory that the DDS_DomainParticipant belongs to.
RTI Connext treats this special value as a constant.
|
extern |
Special value for creating a DDS_DomainParticipant from configuration using default parameters.
This value can be used only in DDS_DomainParticipantFactory_create_participant_from_config_w_params and indicates that the DDS_DomainParticipant must be created applying the information defined in the participant configuration. That is, the domain ID, participant entity name, and QoS profiles for all the entities will be retrieved from the configuration.
RTI Connext treats this special value as a constant.