DomainParticipantFactory
[Domain Module]

DDS_DomainParticipantFactory entity and associated elements More...


Data Structures
struct	DDS_DomainParticipantFactoryQos
	QoS policies supported by a DDS_DomainParticipantFactory. More...
Defines
#define	DDS_DomainParticipantFactoryQos_INITIALIZER
	Initializer for new QoS instances.
Typedefs
typedef struct DDS_DomainParticipantFactoryImpl	DDS_DomainParticipantFactory
	<<singleton>> <<interface>> Allows creation and destruction of DDS_DomainParticipant objects.
Functions
DDS_ReturnCode_t	DDS_DomainParticipantFactoryQos_initialize (struct DDS_DomainParticipantFactoryQos *self)
	Initializer for new QoS instances.
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_ReturnCode_t	DDS_DomainParticipantFactoryQos_finalize (struct DDS_DomainParticipantFactoryQos *self)
	Free any dynamic memory allocated by the policies in this DDS_DomainParticipantFactoryQos.
DDS_DomainParticipantFactory *	DDS_DomainParticipantFactory_get_instance ()
	Gets the singleton instance of this class.
DDS_ReturnCode_t	DDS_DomainParticipantFactory_finalize_instance ()
	<<eXtension>> Destroys the singleton instance of this class.
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.
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.
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_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.
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.
DDS_ReturnCode_t	DDS_DomainParticipantFactory_delete_participant (DDS_DomainParticipantFactory self, DDS_DomainParticipant a_participant)
	Deletes an existing DDS_DomainParticipant.
DDS_DomainParticipant *	DDS_DomainParticipantFactory_lookup_participant (DDS_DomainParticipantFactory *self, DDS_DomainId_t domainId)
	Locates an existing DDS_DomainParticipant.
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.
DDS_ReturnCode_t	DDS_DomainParticipantFactory_load_profiles (DDS_DomainParticipantFactory *self)
	<<eXtension>> Loads the XML QoS profiles.
DDS_ReturnCode_t	DDS_DomainParticipantFactory_reload_profiles (DDS_DomainParticipantFactory *self)
	<<eXtension>> Reloads the XML QoS profiles.
DDS_ReturnCode_t	DDS_DomainParticipantFactory_unload_profiles (DDS_DomainParticipantFactory *self)
	<<eXtension>> Unloads the XML QoS profiles.
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.
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.
const char *	DDS_DomainParticipantFactory_get_default_library (DDS_DomainParticipantFactory *self)
	<<eXtension>> Gets the default XML library associated with a DDS_DomainParticipantFactory.
const char *	DDS_DomainParticipantFactory_get_default_profile (DDS_DomainParticipantFactory *self)
	<<eXtension>> Gets the default XML profile associated with a DDS_DomainParticipantFactory.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
DDS_ReturnCode_t	DDS_DomainParticipantFactory_unregister_thread (DDS_DomainParticipantFactory *self)
	<<eXtension>> Allows the user to release thread specific resources kept by the middleware.
Variables
struct DDS_DomainParticipantQos	DDS_PARTICIPANT_QOS_DEFAULT
	Special value for creating a DomainParticipant with default QoS.

Detailed Description

DDS_DomainParticipantFactory entity and associated elements

Define Documentation

#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:

 struct DDS_DomainParticipantFactoryQos myQos = DDS_DomainParticipantFactoryQos_INITIALIZER;

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:

 struct DDS_DomainParticipantFactoryQos myQos = DDS_DomainParticipantFactoryQos_INITIALIZER;
  DDS_DomainParticipantFactory_get_qos(myFactory, &myQos);
  DDS_DomainParticipantFactory_set_qos(myFactory, &myQos);
  DDS_DomainParticpiantFactoryQos_finalize(myFactory, &myQos);

See also:: DDS_DomainParticipantFactory_get_qos
DDS_DomainParticipantFactoryQos_finalize

Typedef Documentation

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:

When there are multiple participants on the same node (in the same application or different applications) in the same domain, the application(s) must make sure that the participants do not try to bind to the same port numbers. You must disambiguate between the participants by setting a participant ID for each participant (). The port numbers used by a participant are calculated based on both the participant index and the domain ID, so if all participants on the same node have different participant indexes, they can coexist in the same domain.
You cannot mix entities from different participants. For example, you cannot delete a topic on a different participant than you created it from, and you cannot ask a subscriber to create a reader for a topic created from a participant different than the subscriber's own participant. (Note that it is permissable for an application built on top of RTI Data Distribution Service to know about entities from different participants. For example, an application could keep references to a reader from one domain and a writer from another and then bridge the domains by writing the data received in the reader callback.)

See also:: DDS_DomainParticipant

Function Documentation

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:

 DDS_DomainParticipantFactoryQos *myQos = malloc(sizeof(struct DDS_DomainParticipantFactoryQos)); 
  DDS_DomainParticipantQos_initialize(myQos); 
  DDS_DomainParticipantFactory_get_qos(myFactory, myQos);
  DDS_DomainParticipantFactory_set_qos(myFactory, myQos);
  DDS_DomainParticipantFactoryQos_finalize(myQos);
  free(myQos);

Parameters:

self

<<in>> Cannot be NULL.

Returns:: One of the Standard Return Codes

See also:: DDS_DomainParticipantFactory_get_qos
DDS_DomainParticipantFactoryQos_finalize

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.

Parameters:

	self	<<in>> Cannot be NULL.
	source	<<in>>. QoS to be copied from.

Returns:: One of the Standard Return Codes

DDS_DomainParticipantFactoryQos_initialize

DDS_DomainParticipantFactoryQos_finalize

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.

Returns:: One of the Standard Return Codes

See also:: DDS_DomainParticipantFactoryQos_INITIALIZER
DDS_DomainParticipantFactoryQos_initialize

DDS_DomainParticipantFactory* DDS_DomainParticipantFactory_get_instance ( )

Gets the singleton instance of this class.

MT Safety:: On non-Linux systems: UNSAFE for multiple threads to simultaneously make the FIRST call to either DDS_DomainParticipantFactory_get_instance() or DDS_DomainParticipantFactory_finalize_instance(). Subsequent calls are thread safe. (On Linux systems, these calls are thread safe.)

DDS_TheParticipantFactory can be used as an alias for the singleton factory returned by this operation.

Returns:: The singleton DDS_DomainParticipantFactory instance.

See also:: DDS_TheParticipantFactory

DDS_ReturnCode_t DDS_DomainParticipantFactory_finalize_instance ( )

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

Precondition:: All participants created from the factory have been deleted.

Postcondition:: All resources belonging to the factory have been reclaimed. Another call to DDS_DomainParticipantFactory_get_instance will return a new lifecycle of the singleton.

MT Safety:: On non-Linux systems: UNSAFE for multiple threads to simultaneously make the FIRST call to either DDS_DomainParticipantFactory_get_instance() or DDS_DomainParticipantFactory_finalize_instance(). Subsequent calls are thread safe. (On Linux systems, these calls are thread safe.)

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

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.

MT Safety:: UNSAFE. It is not safe to retrieve the default QoS value from a domain participant factory while another thread may be simultaneously calling DDS_DomainParticipantFactory_set_default_participant_qos

Parameters:

	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.

Returns:: One of the Standard Return Codes

See also:: DDS_PARTICIPANT_QOS_DEFAULT
DDS_DomainParticipantFactory_create_participant

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.

Precondition:: The DDS_DomainParticipantQos 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 retrieve the default QoS value from a domain participant factory while another thread may be simultaneously calling DDS_DomainParticipantFactory_set_default_participant_qos

Parameters:

	self	<<in>> Cannot be NULL.
	library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Data Distribution Service will use the default library (see DDS_DomainParticipantFactory_set_default_library).
	profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Data Distribution Service 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.

Returns:: One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

See also:: DDS_PARTICIPANT_QOS_DEFAULT
DDS_DomainParticipantFactory_create_participant_with_profile

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.

Parameters:

	self	<<in>> Cannot be NULL.
	qos	<<out>> the domain participant's QoS Cannot be NULL.

MT Safety:: UNSAFE. It is not safe to retrieve the default QoS value from a domain participant factory while another thread may be simultaneously calling DDS_DomainParticipantFactory_set_default_participant_qos

Returns:: One of the Standard Return Codes

See also:: DDS_PARTICIPANT_QOS_DEFAULT
DDS_DomainParticipantFactory_create_participant

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.

Precondition:: The specified QoS policies must be consistent or the operation will fail and no DDS_DomainParticipant will be created.

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

Precondition:: If listener is specified, none of the listener callback functions can be NULL.

Parameters:

	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.

Returns:: domain participant or NULL on failure

See also:

Specifying QoS on entities for information on setting QoS before entity creation

DDS_DomainParticipantQos for rules on consistency among QoS

DDS_PARTICIPANT_QOS_DEFAULT

NDDS_DISCOVERY_PEERS

DDS_DomainParticipantFactory_create_participant_with_profile()

DDS_DomainParticipantFactory_get_default_participant_qos()

DDS_DomainParticipant_set_listener()

Examples:: HelloWorld_publisher.c, and HelloWorld_subscriber.c.

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.

Precondition:: The DDS_DomainParticipantQos in the input profile must be consistent, or the operation will fail and no DDS_DomainParticipant will be created.

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

Precondition:: if listener is specified, none of the listener callback functions can be NULL.

Parameters:

	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 Data Distribution Service will use the default library (see DDS_DomainParticipantFactory_set_default_library).
	profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Data Distribution Service 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.

Returns:: domain participant or NULL on failure

See also:

Specifying QoS on entities for information on setting QoS before entity creation

DDS_DomainParticipantQos for rules on consistency among QoS

DDS_PARTICIPANT_QOS_DEFAULT

NDDS_DISCOVERY_PEERS

DDS_DomainParticipantFactory_create_participant()

DDS_DomainParticipantFactory_get_default_participant_qos()

DDS_DomainParticipant_set_listener()

DDS_ReturnCode_t DDS_DomainParticipantFactory_delete_participant	(	DDS_DomainParticipantFactory *	self,
		DDS_DomainParticipant *	a_participant
	)

Deletes an existing DDS_DomainParticipant.

Precondition:: All domain entities belonging to the participant must have already been deleted. Otherwise it fails with the error DDS_RETCODE_PRECONDITION_NOT_MET.

Postcondition:: Listener installed on the DDS_DomainParticipant will not be called after this function returns successfully.

Parameters:

	self	<<in>> Cannot be NULL.
	a_participant	<<in>> DDS_DomainParticipant to be deleted.

Returns:: One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET.

Examples:: HelloWorld_publisher.c, and HelloWorld_subscriber.c.

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.

Parameters:

	self	<<in>> Cannot be NULL.
	domainId	<<in>> ID of the domain participant to lookup.

Returns:: domain participant if it exists, or NULL

DDS_ReturnCode_t DDS_DomainParticipantFactory_get_qos	(	DDS_DomainParticipantFactory *	self,
		struct DDS_DomainParticipantFactoryQos *	qos
	)

Gets the value for participant factory 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_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.

Parameters:

	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 Data Distribution Service functions except for DDS_DomainParticipantFactory_get_qos Cannot be NULL.

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_DomainParticipantFactoryQos for rules on consistency among QoS

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

Parameters:

self

<<in>> Cannot be NULL.

Returns:: One of the Standard Return Codes

See also:: DDS_ProfileQosPolicy

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

Parameters:

self

<<in>> Cannot be NULL.

Returns:: One of the Standard Return Codes

See also:: DDS_ProfileQosPolicy

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.

Parameters:

self

<<in>> Cannot be NULL.

Returns:: One of the Standard Return Codes

See also:: DDS_ProfileQosPolicy

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.

See also:: DDS_DomainParticipantFactory_set_default_profile for more information.

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_DomainParticipantFactory_get_default_library

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

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_DomainParticipantFactory_get_default_profile
DDS_DomainParticipantFactory_get_default_profile_library

const char* DDS_DomainParticipantFactory_get_default_library ( DDS_DomainParticipantFactory * self )

<<eXtension>> Gets the default XML library associated with a DDS_DomainParticipantFactory.

Parameters:

self

<<in>> Cannot be NULL.

Returns:: The default library or null if the default library was not set.

See also:: DDS_DomainParticipantFactory_set_default_library

const char* DDS_DomainParticipantFactory_get_default_profile ( DDS_DomainParticipantFactory * self )

<<eXtension>> Gets the default XML profile associated with a DDS_DomainParticipantFactory.

Parameters:

self

<<in>> Cannot be NULL.

Returns:: The default profile or null if the default profile was not set.

See also:: DDS_DomainParticipantFactory_set_default_profile

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

Parameters:

self

<<in>> Cannot be NULL.

Returns:: The default profile library or null if the default profile was not set.

See also:: DDS_DomainParticipantFactory_set_default_profile

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.

Parameters:

	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 Data Distribution Service will use the default library (see DDS_DomainParticipantFactory_set_default_library).
	profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Data Distribution Service will use the default profile (see DDS_DomainParticipantFactory_set_default_profile).