DomainParticipantFactory

DDS_DomainParticipantFactory entity and associated elements More...

Data Structures
struct	DDS_DomainParticipantFactoryQos
	<<cert>> QoS policies supported by a DDS_DomainParticipantFactory. More...

Macros
#define	DDS_DomainParticipantFactoryQos_INITIALIZER
	<<cert>> Initializer for new QoS instances.
#define	DDS_TheParticipantFactory   DDS_DomainParticipantFactory_get_instance()
	<<cert>> Can be used as an alias for the singleton factory returned by the operation DDS_DomainParticipantFactory_get_instance().

Typedefs
typedef struct DDS_DomainParticipantFactoryImpl	DDS_DomainParticipantFactory
	<<singleton>> <<interface>> <<cert>> Allows creation and destruction of DDS_DomainParticipant objects.

Functions
DDS_ReturnCode_t	DDS_DomainParticipantFactoryQos_initialize (struct DDS_DomainParticipantFactoryQos *self)
	<<cert>> Initializer for new QoS instances.
DDS_ReturnCode_t	DDS_DomainParticipantFactoryQos_finalize (struct DDS_DomainParticipantFactoryQos *self)
	Free any dynamic memory allocated by the policies in this DDS_DomainParticipantFactoryQos.
DDS_ReturnCode_t	DDS_DomainParticipantFactoryQos_copy (struct DDS_DomainParticipantFactoryQos *self, const struct DDS_DomainParticipantFactoryQos *source)
	<<cert>> Copy the contents of the given QoS into this QoS. The destination structure must be preallocated and initialized.
DDS_Boolean	DDS_DomainParticipantFactoryQos_is_equal (const struct DDS_DomainParticipantFactoryQos *left, const struct DDS_DomainParticipantFactoryQos *right)
	<<cert>> Compare two DDS_DomainParticipantFactoryQos policies for equality.
DDS_DomainParticipantFactory *	DDS_DomainParticipantFactory_get_instance (void)
	<<cert>> Gets the singleton instance of this class.
DDS_ReturnCode_t	DDS_DomainParticipantFactory_finalize_instance (void)
	<<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_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)
	<<cert>> Creates a new DDS_DomainParticipant object.
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)
	<<cert>> Locates an existing DDS_DomainParticipant.
DDS_DomainParticipant *	DDS_DomainParticipantFactory_lookup_participant_by_name (DDS_DomainParticipantFactory *self, const char *participant_name)
	<<cert>> Retrieves a DDS_DomainParticipant by its entity name within the DDS_DomainParticipantFactory.
DDS_ReturnCode_t	DDS_DomainParticipantFactory_get_qos (DDS_DomainParticipantFactory *self, struct DDS_DomainParticipantFactoryQos *qos)
	<<cert>> Gets the value for participant factory QoS.
DDS_ReturnCode_t	DDS_DomainParticipantFactory_set_qos (DDS_DomainParticipantFactory *self, const struct DDS_DomainParticipantFactoryQos *qos)
	<<cert>> Sets the value for a participant factory QoS.
RT_Registry_T *	DDS_DomainParticipantFactory_get_registry (DDS_DomainParticipantFactory *self)
	<<cert>> Retrieves the singleton registry instance associated with the factory.
DDS_DomainParticipant *	DDS_DomainParticipantFactory_create_participant_from_config (DDS_DomainParticipantFactory *self, const char *configuration_name)
	<<cert>> <<eXtension>> Creates a new DDS_DomainParticipant given its configuration name from a description provided in configuration file.

Variables
const struct DDS_DomainParticipantQos	DDS_PARTICIPANT_QOS_DEFAULT
	<<cert>> Special value for creating domain participant with default QoS.

Detailed Description

DDS_DomainParticipantFactory entity and associated elements

Macro Definition Documentation

DDS_DomainParticipantFactoryQos_INITIALIZER

#define DDS_DomainParticipantFactoryQos_INITIALIZER

<<cert>> Initializer for new QoS instances.

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.

DDS_TheParticipantFactory

#define DDS_TheParticipantFactory   DDS_DomainParticipantFactory_get_instance()

<<cert>> Can be used as an alias for the singleton factory returned by the operation DDS_DomainParticipantFactory_get_instance().

Typedef Documentation

DDS_DomainParticipantFactory

typedef struct DDS_DomainParticipantFactoryImpl DDS_DomainParticipantFactory

<<singleton>> <<interface>> <<cert>> 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:

• With multiple participants in the same domain on the same node (in the same application or different applications), each participant must be assigned its own receive ports. The receive ports are calculated based on the domain ID and the participant index set in the DDS_WireProtocolQosPolicy. The default index (-1) causes the participant to automatically search for the next available index, starting at 0, when it is created. If an index larger or equal to 0 is assigned then only that value will be used. If another participant with the same index already exists the participant creation will fail.

  NOTE: An exception to this rule is multicast ports. Multicast ports are shared between participants in the same domain on the same host). Thus, the index value is ignored.

• 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 permissible for an application built on top of RTI Connext DDS Micro 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_DomainParticipantFactoryQos_initialize()

DDS_ReturnCode_t DDS_DomainParticipantFactoryQos_initialize

(

struct DDS_DomainParticipantFactoryQos *

self

)

<<cert>> Initializer for new QoS instances.

Parameters

self	<<in>> Cannot be NULL.

API Restriction:

This function may be called before DDS_DomainParticipantFactory_get_instance.

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

Parameters

self	<<in>> Cannot be NULL.

Returns

One of the Standard Return Codes

API Restriction:

This function must only be called after DDS_DomainParticipantFactory_get_instance.

See also

DDS_DomainParticipantFactoryQos_INITIALIZER

DDS_DomainParticipantFactoryQos_initialize

DDS_DomainParticipantFactoryQos_copy()

DDS_ReturnCode_t DDS_DomainParticipantFactoryQos_copy	(	struct DDS_DomainParticipantFactoryQos *	self,
		const struct DDS_DomainParticipantFactoryQos *	source )

<<cert>> Copy the contents of the given QoS into this QoS. The destination structure must be preallocated and initialized.

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

MT Safety:

UNSAFE. This operation is not thread safe. This operation does not protect the source or destination from being modified by another thread while the source is being copied to the destination.

API Restriction:

This function must only be called after DDS_DomainParticipantFactory_get_instance.

See also

DDS_DomainParticipantFactoryQos_INITIALIZER

DDS_DomainParticipantFactoryQos_is_equal()

DDS_Boolean DDS_DomainParticipantFactoryQos_is_equal	(	const struct DDS_DomainParticipantFactoryQos *	left,
		const struct DDS_DomainParticipantFactoryQos *	right )

<<cert>> Compare two DDS_DomainParticipantFactoryQos policies for equality.

Parameters

left	<<in>> The left side of the comparison.
right	<<in>> The right side of the comparison.

Returns

DDS_BOOLEAN_TRUE if left is equal to right, otherwise DDS_BOOLEAN_FALSE.

MT Safety:

UNSAFE. This operation does not protect against the left or right side from being modified by another thread while the comparison is made.

See also

DDS_DomainParticipantFactoryQos_INITIALIZER

DDS_DomainParticipantFactoryQos_initialize

DDS_DomainParticipantFactory_get_instance()

DDS_DomainParticipantFactory * DDS_DomainParticipantFactory_get_instance

(

void

)

<<cert>> Gets the singleton instance of this class.

MT Safety:

UNSAFE on the FIRST call to DDS_DomainParticipantFactory_get_instance(). It is not safe for two threads to simultaneously make the first call to get an instance of the factory. Subsequent calls are thread safe.

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

DDS_DomainParticipantFactory_get_instance also initializes the RTI Connext DDS Micro library and should be called before any other API, unless the API is explicitly mentioned as safe to call before DDS_DomainParticipantFactory_get_instance.

Returns

the singleton DDS_DomainParticipantFactory instance.

ARINC 653 API Restriction:

This function must only be called before a partition enters NORMAL mode.

See also

::DDS_DomainParticipantFactory_TheParticipantFactory

DDS_DomainParticipantFactory_finalize_instance()

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 OSes, these resources are automatically reclaimed by the OS when the program terminates. Some memory checker tools still flag these as unreclaimed however. 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 reclaimed. Another call to DDS_DomainParticipantFactory_get_instance will return a new lifecycle of the singleton.

MT Safety:

UNSAFE for two threads to simultaneously call DDS_DomainParticipantFactory_finalize_instance() or DDS_DomainParticipantFactory_get_instance() at the same time.

Returns

One of the Standard Return Codes, or DDS_RETCODE_PRECONDITION_NOT_MET

DDS_DomainParticipantFactory_set_default_participant_qos()

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.

Subsequent participants created from this factory that specify DDS_PARTICIPANT_QOS_DEFAULT will use the QoS values set by this operation.

Parameters

self	<<in>> Cannot be NULL.
qos	<<in>> Qos to be used by the DDS_DomainParticipant. 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 have 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_DomainParticipantFactory_get_default_participant_qos()

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

Returns

One of the Standard Return Codes

See also

DDS_PARTICIPANT_QOS_DEFAULT

DDS_DomainParticipantFactory_create_participant

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 )

<<cert>> Creates a new DDS_DomainParticipant object.

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

The default participant index value (-1) causes the participant to automatically search for the first available participant index, starting at 0, when it is created. This is appropriate for most use cases, including when there are multiple participants per host in the same domain.

Precondition

if listener is specified, a listener callback must be provided for each status enabled in the mask.

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 domain participant'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

MT Safety:

This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

ARINC 653 API Restriction:

This function must only be called before a partition enters NORMAL mode.

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

DDS_DomainParticipantFactory_delete_participant()

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.

DDS_DomainParticipantFactory_lookup_participant()

DDS_DomainParticipant * DDS_DomainParticipantFactory_lookup_participant	(	DDS_DomainParticipantFactory *	self,
		DDS_DomainId_t	domainId )

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

MT Safety:

This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

Returns

domain participant if it exists, or NULL

DDS_DomainParticipantFactory_lookup_participant_by_name()

DDS_DomainParticipant * DDS_DomainParticipantFactory_lookup_participant_by_name	(	DDS_DomainParticipantFactory *	self,
		const char *	participant_name )

<<cert>> Retrieves a DDS_DomainParticipant by its entity name within the DDS_DomainParticipantFactory.

This returned DDS_DomainParticipant is either enabled or disabled.

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.

Parameters

self	<<in>> Cannot be NULL.
participant_name	<<in>> Entity name of the DDS_DomainParticipant. Cannot be NULL.

Returns

The first DDS_DomainParticipant found with the specified name or NULL if it is not found.

MT Safety:

UNSAFE. It is not safe to lookup a DDS_DomainParticipant in one thread while another thread is simultaneously creating or destroying that DDS_DomainParticipant.

DDS_DomainParticipantFactory_get_qos()

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

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

MT Safety:

This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

DDS_DomainParticipantFactory_set_qos()

DDS_ReturnCode_t DDS_DomainParticipantFactory_set_qos	(	DDS_DomainParticipantFactory *	self,
		const struct DDS_DomainParticipantFactoryQos *	qos )

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

Note that this function may cause RTI Connext DDS Micro to free and reallocate memory, depending on the QoS policies that are changed.

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 Connext DDS Micro 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

MT Safety:

This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

See also

DDS_DomainParticipantFactoryQos for rules on consistency among QoS

DDS_DomainParticipantFactory_get_registry()

RT_Registry_T * DDS_DomainParticipantFactory_get_registry

(

DDS_DomainParticipantFactory *

self

)

<<cert>> Retrieves the singleton registry instance associated with the factory.

Parameters

self	<<in>> Cannot be NULL.

Returns

the registry instance or NULL on failure.

MT Safety:

This operation is thread safe. However, note that the arguments are not protected from being modified by other threads and must not be modified until the call returns.

DDS_DomainParticipantFactory_create_participant_from_config()

DDS_DomainParticipant * DDS_DomainParticipantFactory_create_participant_from_config	(	DDS_DomainParticipantFactory *	self,
		const char *	configuration_name )

<<cert>> <<eXtension>> Creates a new DDS_DomainParticipant given its configuration name from a description provided in configuration file.

This operation creates a DDS_DomainParticipant and all the contained entities (DDS_Topic, DDS_Publisher, DDS_Subscriber, DDS_DataWriter, DDS_DataReader) from a description given in a configuration file.

The configuration name is the fully qualified name of the application, consisting of the name of the application library plus the name of application configuration.

For example the name "MyApplicationLibrary::PublicationParticipant" can be used to create the application from the configuration with library name "MyApplicationLibrary" and participant name "PublicationParticipant"

The entities belonging to the newly created DDS_DomainParticipant can be retrieved with the help of lookup operations such as: DDS_DomainParticipant_lookup_publisher_by_name.

Parameters

self	<<in>> Cannot be NULL.
configuration_name	<<in>> Name of RTI Connext DDS Micro application configuration in the configuration file. Cannot be NULL.

Returns

Pointer to DDS_DomainParticipant or NULL on failure

Variable Documentation

DDS_PARTICIPANT_QOS_DEFAULT

const struct DDS_DomainParticipantQos DDS_PARTICIPANT_QOS_DEFAULT

extern

<<cert>> Special value for creating domain participant 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.

NOTE: You cannot use this value to get the default QoS for a DomainParticipant; for this purpose, use DDS_DomainParticipantFactory_get_default_participant_qos.

See also

DDS_DomainParticipantFactory_create_participant()

Referenced by DDS_DomainParticipant_unregister_type().