DomainParticipant

DDS_DomainParticipant entity and associated elements More...

Data Structures
struct	DDS_DomainParticipantListener
	<<interface>> <<cert>> Listener for participant status. More...
struct	DDS_DomainParticipantQos
	<<cert>> QoS policies supported by a DDS_DomainParticipant entity. More...

Macros
#define	DDS_DomainParticipantListener_INITIALIZER
	<<cert>> Initializer for new DDS_DomainParticipantListener.
#define	DDS_DomainParticipantQos_INITIALIZER
	<<cert>> Initializer for new QoS instances.

Typedefs
typedef struct DDS_DomainParticipantImpl	DDS_DomainParticipant
	<<interface>> <<cert>> Container for all DDS_DomainEntity objects.

Functions
DDS_ReturnCode_t	DDS_DomainParticipantQos_initialize (struct DDS_DomainParticipantQos *self)
	<<cert>> Initializer for new QoS instances.
DDS_ReturnCode_t	DDS_DomainParticipantQos_copy (struct DDS_DomainParticipantQos *self, const struct DDS_DomainParticipantQos *source)
	<<cert>> Copy the contents of the given QoS into this QoS. The destination structure must be preallocated and initialized.
DDS_Boolean	DDS_DomainParticipantQos_is_equal (const struct DDS_DomainParticipantQos *left, const struct DDS_DomainParticipantQos *right)
	<<cert>> Compare two DDS_DomainParticipantQos policies for equality.
DDS_Entity *	DDS_DomainParticipant_as_entity (DDS_DomainParticipant *self)
	<<cert>> Access a DDS_DomainParticipant's supertype instance.
DDS_Publisher *	DDS_DomainParticipant_create_publisher (DDS_DomainParticipant *self, const struct DDS_PublisherQos *qos, const struct DDS_PublisherListener *listener, DDS_StatusMask mask)
	<<cert>> Creates a DDS_Publisher with the desired QoS policies and attaches to it the specified DDS_PublisherListener.
DDS_Subscriber *	DDS_DomainParticipant_create_subscriber (DDS_DomainParticipant *self, const struct DDS_SubscriberQos *qos, const struct DDS_SubscriberListener *listener, DDS_StatusMask mask)
	<<cert>> Creates a DDS_Subscriber with the desired QoS policies and attaches to it the specified DDS_SubscriberListener.
DDS_Topic *	DDS_DomainParticipant_create_topic (DDS_DomainParticipant *self, const char *topic_name, const char *type_name, const struct DDS_TopicQos *qos, const struct DDS_TopicListener *listener, DDS_StatusMask mask)
	<<cert>> Creates a DDS_Topic with the desired QoS policies
DDS_TopicDescription *	DDS_DomainParticipant_lookup_topicdescription (DDS_DomainParticipant *self, const char *topic_name)
	<<cert>> Lookup an existing locally-created DDS_TopicDescription, based on its name.
DDS_ReturnCode_t	DDS_DomainParticipant_add_peer (DDS_DomainParticipant *self, const char *peer)
	<<eXtension>> <<cert>> Attempt to contact one or more additional peer participants.
DDS_DomainId_t	DDS_DomainParticipant_get_domain_id (DDS_DomainParticipant *self)
	<<cert>> Get the unique domain identifier.
DDS_ReturnCode_t	DDS_DomainParticipant_get_current_time (DDS_DomainParticipant *self, struct DDS_Time_t *current_time)
	<<cert>> Returns the current value of the time.
DDS_ReturnCode_t	DDS_DomainParticipant_register_type (DDS_DomainParticipant *self, const char *type_name, struct NDDS_Type_Plugin *plugin)
	<<eXtension>> <<cert>> Allows an application to communicate to RTI Connext Micro the existence of a data type.

Variables
struct DDS_TopicQos	DDS_TOPIC_QOS_DEFAULT
	<<cert>> Special value for creating a DDS_Topic with default QoS. Note that this is the only supported parameter in RTI Connext Micro when creating a topic.
struct DDS_PublisherQos	DDS_PUBLISHER_QOS_DEFAULT
	<<cert>> Special value for creating a DDS_Publisher with default QoS.
struct DDS_SubscriberQos	DDS_SUBSCRIBER_QOS_DEFAULT
	<<cert>> Special value for creating a DDS_Subscriber with default QoS.

---

Detailed Description

DDS_DomainParticipant entity and associated elements

---

Macro Definition Documentation

#define DDS_DomainParticipantListener_INITIALIZER

<<cert>> Initializer for new DDS_DomainParticipantListener.

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

 DDS_DomainParticipantListener listener = DDS_DomainParticipantListener_INITIALIZER;

See also:

DDS_DomainParticipantListener

#define DDS_DomainParticipantQos_INITIALIZER

<<cert>> Initializer for new QoS instances.

DDS_DomainParticipantQos instances stored on the stack must be initialized with this value before they are passed to any functions. This step ensures that the contained QoS policies that use dynamic memory are properly initialized. The initializer 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_DomainParticipantQos myQos = DDS_DomainParticipantQos_INITIALIZER;                     

---

Typedef Documentation

typedef struct DDS_DomainParticipantImpl DDS_DomainParticipant

<<interface>> <<cert>> Container for all DDS_DomainEntity objects.

The DomainParticipant object plays several roles:

- It acts as a container for all other DDS_Entity objects.

- It acts as factory for the DDS_Publisher, DDS_Subscriber, DDS_Topic and DDS_Entity objects.

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

A DDS_DomainParticipant may be created in a disabled or enabled state; refer to DDS_Entity_enable for details. The initial state of the DDS_DomainParticipant is determined by DDS_DomainParticipantFactoryQos::entity_factory.

The documentation for each operation on the DDS_DomainParticipant includes any restrictions with respect to whether the operation is valid only for a disabled or enabled DDS_DomainParticipant.

The following operations may be called even if the DDS_DomainParticipant is not enabled. Other operations will fail with the value DDS_RETCODE_NOT_ENABLED if called on a disabled DomainParticipant:

• Operations defined at the base-class level namely, enable()
• Factory operations: create_topic(), create_publisher(), create_subscriber()

  QoS:

  DDS_DomainParticipantQos

  Status:

  Status Kinds

  Listener:

  DDS_DomainParticipantListener

---

Function Documentation

DDS_ReturnCode_t DDS_DomainParticipantQos_initialize

(

struct DDS_DomainParticipantQos *

self

)

<<cert>> Initializer for new QoS instances.

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

Parameters:

self	<<in>> Cannot be NULL.

Returns:

One of the Standard Return Codes

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

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

DDS_DomainParticipantQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory as 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_DomainParticipantQos_INITIALIZER

DDS_DomainParticipantQos_initialize

DDS_Boolean DDS_DomainParticipantQos_is_equal	(	const struct DDS_DomainParticipantQos *	left,
		const struct DDS_DomainParticipantQos *	right
	)

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

Parameters:

[in]	left	The left side of the comparison.
[in]	right	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_DomainParticipantQos_INITIALIZER

DDS_DomainParticipantQos_initialize

DDS_Entity* DDS_DomainParticipant_as_entity

(

DDS_DomainParticipant *

self

)

<<cert>> Access a DDS_DomainParticipant's supertype instance.

Parameters:

self	<<in>> Cannot be NULL.

Returns:

DDS_DomainParticipant's supertype DDS_Entity instance

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

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

Precondition:

The specified QoS policies must be consistent, or the operation will fail and no DDS_Publisher will be created.

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

Parameters:

self	<<in>> Cannot be NULL.
qos	<<in>> QoS to be used for creating the new DDS_Publisher. The special value DDS_PUBLISHER_QOS_DEFAULT can be used to indicate that the DDS_Publisher should be created with the default DDS_PublisherQos set in the DDS_DomainParticipant. Cannot be NULL.
listener	<<in>>. Listener to be attached to the newly created DDS_Publisher.
mask	<<in>>. Changes of communication status to be invoked on the listener.

Returns:

newly created publisher object 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.

See also:

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

DDS_PublisherQos for rules on consistency among QoS

DDS_PUBLISHER_QOS_DEFAULT

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

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

Precondition:

The specified QoS policies must be consistent, or the operation will fail and no DDS_Subscriber will be created.

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

Parameters:

self	<<in>> Cannot be NULL.
qos	<<in>> QoS to be used for creating the new DDS_Subscriber. The special value DDS_SUBSCRIBER_QOS_DEFAULT can be used to indicate that the DDS_Subscriber should be created with the default DDS_SubscriberQos set in the DDS_DomainParticipant. Cannot be NULL.
listener	<<in>>. Listener to be attached to the newly created DDS_Subscriber.
mask	<<in>>. Changes of communication status to be invoked on the listener.

Returns:

newly created subscriber object 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.

See also:

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

DDS_SubscriberQos for rules on consistency among QoS

DDS_SUBSCRIBER_QOS_DEFAULT

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

<<cert>> Creates a DDS_Topic with the desired QoS policies

Precondition:

The application is not allowed to create two DDS_TopicDescription objects with the same topic_name attached to the same DDS_DomainParticipant. If the application attempts this, this function will fail and return NULL.

The specified QoS policies must be consistent, or the operation will fail and no DDS_Topic will be created.

Prior to creating a DDS_Topic, the type must have been registered with RTI Connext Micro. This is done using the DDS_DomainParticipant_register_type operation on a derived class of the NDDS_Type_Plugin interface.

Parameters:

self	<<in>> Cannot be NULL.
topic_name	<<in>> Name for the new topic, must not exceed 255 characters. Cannot be NULL.
type_name	<<in>> The type to which the new DDS_Topic will be bound. Cannot be NULL.
qos	<<in>> Must be DDS_TOPIC_QOS_DEFAULT.

Cannot be NULL.

Parameters:

listener	<<in>>. Listener to be attached to the newly created DDS_Topic.
mask	<<in>>. Changes of communication status to be invoked on the listener.

Returns:

newly created topic, 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.

See also:

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

DDS_TopicQos for rules on consistency among QoS

DDS_TOPIC_QOS_DEFAULT

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

<<cert>> Lookup an existing locally-created DDS_TopicDescription, based on its name.

The returned topic can either be enabled or disabled.

The operation DDS_DomainParticipant_lookup_topicdescription searches among the locally created topics and returns a pointer to a DDS_TopicDescription. It is possible to delete the DDS_TopicDescription returned by DDS_DomainParticipant_lookup_topicdescription, provided it has no readers or writers, but then it is really deleted and subsequent lookups will fail.

Parameters:

self	<<in>> Cannot be NULL.
topic_name	<<in>> Name of DDS_TopicDescription to search for. This string must be no more than 255 characters. Cannot be NULL.

Returns:

the topic description if it has already been created locally, or NULL otherwise.

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_ReturnCode_t DDS_DomainParticipant_add_peer	(	DDS_DomainParticipant *	self,
		const char *	peer
	)

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

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

This function may be called at any time after this DDS_DomainParticipant has been created, before or after it has been enabled. If it is called after DDS_Entity_enable, an attempt will be made to contact the new peer(s) immediately. If it is called before, the peer description will simply be added to the list that was populated by DDS_DiscoveryQosPolicy::initial_peers; the first attempted contact will take place after this DDS_DomainParticipant is enabled.

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

• This DDS_DomainParticipant will attempt to discover peer participants at the given locations, but may not succeed if no such participants are available. Such a situation will not result in an error result from this function, which will not wait for contact attempt(s) to be made.
• If remote participants such as are described by the given peer description are discovered, the distributed application is configured with asymmetric peer lists, and DDS_DiscoveryQosPolicy::accept_unknown_peers is set to DDS_BOOLEAN_TRUE this DDS_DomainParticipant may actually discover more peers than are described in the given peer description.

Adding a peer description with this function has no effect on DDS_DiscoveryQosPolicy::initial_peers.

Parameters:

self	<<in>> Cannot be NULL.
peer	<<in>> New peer descriptor to be added. 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.

See also:

DDS_DiscoveryQosPolicy::initial_peers

DDS_PARTICIPANT_TOPIC_NAME

DDS_DomainId_t DDS_DomainParticipant_get_domain_id

(

DDS_DomainParticipant *

self

)

<<cert>> Get the unique domain identifier.

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

Parameters:

self	<<in>> Cannot be NULL.

Returns:

the unique domainId that was used to create the domain

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_DomainParticipantFactory_create_participant

DDS_ReturnCode_t DDS_DomainParticipant_get_current_time	(	DDS_DomainParticipant *	self,
		struct DDS_Time_t *	current_time
	)

<<cert>> Returns the current value of the time.

The current value of the time that RTI Connext Micro uses to time-stamp DDS_DataWriter and to set the reception-timestamp for the data updates that it receives. Note that the definition of the current time is dependent on the platform and may not be the actual wall-clock time. Additional information for specific platforms can be found in the User's Manual.

Parameters:

self	<<in>> Cannot be NULL.
current_time	<<inout>> Current time to be filled up. Cannot be NULL.

Returns:

One of the Standard Return Codes

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_ReturnCode_t DDS_DomainParticipant_register_type	(	DDS_DomainParticipant *	self,
		const char *	type_name,
		struct NDDS_Type_Plugin *	plugin
	)

<<eXtension>> <<cert>> Allows an application to communicate to RTI Connext Micro the existence of a data type.

The generated implementation of the operation embeds all the knowledge that has to be communicated to the middleware in order to make it able to manage the contents of data of that type. This includes in particular the key definition that will allow RTI Connext Micro to distinguish different instances of the same type.

The same NDDS_Type_Plugin can be registered multiple times with a DDS_DomainParticipant using the same or different values for the type_name. If register_type is called multiple times on the same NDDS_Type_Plugin with the same DDS_DomainParticipant and type_name, the second (and subsequent) registrations are ignored by the operation fails with DDS_RETCODE_OK.

Precondition:

Cannot use the same type_name to register two different NDDS_Type_Plugin with the same DDS_DomainParticipant, or else the operation will fail and DDS_RETCODE_PRECONDITION_NOT_MET will be returned.

Parameters:

self	<<in>> Cannot be NULL.
type_name	<<in>> the type name under with the data type Foo is registered with the participant; this type name is used when creating a new DDS_Topic. (See DDS_DomainParticipant_create_topic.) The name may not be NULL or longer than 255 characters.
plugin	<<in>> the Foo type plugin to register the data type with. Cannot be NULL.

Returns:

One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_OUT_OF_RESOURCES.

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_DomainParticipant_create_topic

---

Variable Documentation

struct DDS_TopicQos DDS_TOPIC_QOS_DEFAULT

<<cert>> Special value for creating a DDS_Topic with default QoS. Note that this is the only supported parameter in RTI Connext Micro when creating a topic.

RTI Connext Micro does not support the Topic QoS. This represents the a placeholder for Topic QoS values. This is the only valid paramater that can be passed into the DDS_DomainParticipant_create_topic function (no other values for QoS are supported).

See also:

DDS_DomainParticipant_create_topic

struct DDS_PublisherQos DDS_PUBLISHER_QOS_DEFAULT

<<cert>> Special value for creating a DDS_Publisher with default QoS.

When used in DDS_DomainParticipant_create_publisher, this special value is used to indicate that the DDS_Publisher should be created with the default DDS_Publisher QoS.

See also:

DDS_DomainParticipant_create_publisher

struct DDS_SubscriberQos DDS_SUBSCRIBER_QOS_DEFAULT

<<cert>> Special value for creating a DDS_Subscriber with default QoS.

When used in DDS_DomainParticipant_create_subscriber, this special value is used to indicate that the DDS_Subscriber should be created with the default DDS_Subscriber QoS.

See also:

DDS_DomainParticipant_create_subscriber