Entity Support

DDS_Entity, DDS_Listener and related items. More...

Data Structures
struct	DDS_Listener
	<<interface>> Abstract base class for all Listener interfaces. More...

Macros
#define	DDS_Listener_INITIALIZER
	Initialize the DDS_Listener::listener_data pointer to NULL.

Typedefs
typedef struct DDS_EntityImpl	DDS_Entity
	<<interface>> Abstract base class for all the DDS objects that support QoS policies, and a listener.
typedef struct DDS_DomainEntityImpl	DDS_DomainEntity
	<<interface>> Abstract base class for all DDS entities except for the DDS_DomainParticipant.

Functions
DDS_ReturnCode_t	DDS_Entity_enable (DDS_Entity *self)
	<<cert>> Enables the DDS_Entity.
DDS_InstanceHandle_t	DDS_Entity_get_instance_handle (DDS_Entity *self)
	<<cert>> Allows access to the DDS_InstanceHandle_t associated with the DDS_Entity.
DDS_EntityKind_t	DDS_Entity_get_entity_kind (DDS_Entity *self)
	Determine the type of DDS_Entity.
DDS_StatusCondition *	DDS_Entity_get_statuscondition (DDS_Entity *self)
	<<cert>> Return the DDS_StatusCondition associated with a particular DDS_Entity.
DDS_StatusMask	DDS_Entity_get_status_changes (DDS_Entity *self)
	<<cert>> Retrieves the list of communication statuses in the DDS_Entity that are triggered.

---

Detailed Description

DDS_Entity, DDS_Listener and related items.

DDS_Entity subtypes are created and destroyed by factory objects. With the exception of DDS_DomainParticipant, whose factory is DDS_DomainParticipantFactory, all DDS_Entity factory objects are themselves DDS_Entity subtypes as well.

Important: all DDS_Entity delete operations are inherently thread-unsafe. The user must take extreme care that a given DDS_Entity is not destroyed in one thread while being used concurrently (including being deleted concurrently) in another thread. An operation's effect in the presence of the concurrent deletion of the operation's target DDS_Entity is undefined.

---

Macro Definition Documentation

#define DDS_Listener_INITIALIZER

Initialize the DDS_Listener::listener_data pointer to NULL.

---

Typedef Documentation

typedef struct DDS_EntityImpl DDS_Entity

<<interface>> Abstract base class for all the DDS objects that support QoS policies, and a listener.

All operations except for set_qos(), get_qos(), set_listener(), get_listener() and enable(), may return the value DDS_RETCODE_NOT_ENABLED.

QoS:

QoS Policies

Status:

Status Kinds

Listener:

DDS_Listener

Abstract operations

Each derived entity provides the following operations specific to its role in RTI Connext Micro.

set_qos (abstract)

This operation sets the QoS policies of the DDS_Entity.

This operation must be provided by each of the derived DDS_Entity classes (DDS_DomainParticipant, DDS_Topic, DDS_Publisher, DDS_DataWriter, DDS_Subscriber, and DDS_DataReader) so that the policies that are meaningful to each DDS_Entity can be set.

Precondition:

Certain policies are immutable (see QoS Policies): they can only be set at DDS_Entity creation time or before the entity is enabled. If set_qos() is invoked after the DDS_Entity is enabled and it attempts to change the value of an immutable policy, the operation will fail and return DDS_RETCODE_IMMUTABLE_POLICY.

Certain values of QoS policies can be incompatible with the settings of the other policies. The set_qos() operation will also fail if it specifies a set of values that, once combined with the existing values, would result in an inconsistent set of policies. In this case, the operation will fail and return DDS_RETCODE_INCONSISTENT_POLICY.

If the application supplies a non-default value for a QoS policy that is not supported by the implementation of the service, the set_qos operation will fail and return DDS_RETCODE_UNSUPPORTED.

Postcondition:

The existing set of policies is only changed if the set_qos() operation succeeds. This is indicated by a return code of DDS_RETCODE_OK. In all other cases, none of the policies are modified.

Each derived DDS_Entity class (DDS_DomainParticipant, DDS_Topic, DDS_Publisher, DDS_DataWriter, DDS_Subscriber, DDS_DataReader) has a corresponding special value of the QoS (DDS_PARTICIPANT_QOS_DEFAULT, DDS_PUBLISHER_QOS_DEFAULT, DDS_SUBSCRIBER_QOS_DEFAULT, DDS_TOPIC_QOS_DEFAULT, DDS_DATAWRITER_QOS_DEFAULT, DDS_DATAREADER_QOS_DEFAULT). This special value may be used as a parameter to the set_qos operation to indicate that the QoS of the DDS_Entity should be changed to match the current default QoS set in the DDS_Entity's factory. The operation set_qos cannot modify the immutable QoS, so a successful return of the operation indicates that the mutable QoS for the Entity has been modified to match the current default for the DDS_Entity's factory.

The set of policies specified in the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set.

Possible error codes returned in addition to Standard Return Codes : DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.

get_qos (abstract)

This operation allows access to the existing set of QoS policies for the DDS_Entity. This operation must be provided by each of the derived DDS_Entity classes (DDS_DomainParticipant, DDS_Topic, DDS_Publisher, DDS_DataWriter, DDS_Subscriber, and DDS_DataReader), so that the policies that are meaningful to each DDS_Entity can be retrieved.

Possible error codes are Standard Return Codes.

set_listener (abstract)

This operation installs a DDS_Listener on the DDS_Entity. The listener will only be invoked on the changes of communication status indicated by the specified mask.

This operation must be provided by each of the derived DDS_Entity classes (DDS_DomainParticipant, DDS_Topic, DDS_Publisher, DDS_DataWriter, DDS_Subscriber, and DDS_DataReader), so that the listener is of the concrete type suitable to the particular DDS_Entity.

It is permitted to use NULL as the value of the listener. The NULL listener behaves as if the mask is DDS_STATUS_MASK_NONE.

Postcondition:

Only one listener can be attached to each DDS_Entity. If a listener was already set, the operation set_listener() will replace it with the new one. Consequently, if the value NULL is passed for the listener parameter to the set_listener operation, any existing listener will be removed.

get_listener (abstract)

This operation allows access to the existing DDS_Listener attached to the DDS_Entity.

This operation must be provided by each of the derived DDS_Entity classes (DDS_DomainParticipant, DDS_Topic, DDS_Publisher, DDS_DataWriter, DDS_Subscriber, and DDS_DataReader) so that the listener is of the concrete type suitable to the particular DDS_Entity.

If no listener is installed on the DDS_Entity, this operation will return NULL.

typedef struct DDS_DomainEntityImpl DDS_DomainEntity

<<interface>> Abstract base class for all DDS entities except for the DDS_DomainParticipant.

Its sole purpose is to conceptually express that DDS_DomainParticipant is a special kind of DDS_Entity that acts as a container of all other DDS_Entity but itself cannot contain other DDS_DomainParticipant.

---

Function Documentation

DDS_ReturnCode_t DDS_Entity_enable

(

DDS_Entity *

self

)

<<cert>> Enables the DDS_Entity.

This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the ENTITY_FACTORY QoS policy on the corresponding factory for the DDS_Entity.

By default, ENTITY_FACTORY is set so that it is not necessary to explicitly call DDS_Entity_enable on newly created entities.

The DDS_Entity_enable operation is idempotent. Calling enable on an already enabled Entity returns OK and has no effect.

If a DDS_Entity has not yet been enabled, the following kinds of operations may be invoked on it:

• set or get the QoS policies (including default QoS policies) and listener
• 'factory' operations
• 'lookup' operations

Other operations may explicitly state that they may be called on disabled entities; those that do not will return the error DDS_RETCODE_NOT_ENABLED.

It is legal to delete an DDS_Entity that has not been enabled by calling the proper operation on its factory.

Entities created from a factory that is disabled are created disabled, regardless of the setting of the DDS_EntityFactoryQosPolicy.

Calling enable on an Entity whose factory is not enabled will fail and return DDS_RETCODE_PRECONDITION_NOT_MET.

If DDS_EntityFactoryQosPolicy::autoenable_created_entities is TRUE, the enable operation on a factory will automatically enable all entities created from that factory.

Listeners associated with an entity are not called until the entity is enabled.

Parameters:

self	<<in>> Cannot be NULL.

Returns:

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

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_InstanceHandle_t DDS_Entity_get_instance_handle

(

DDS_Entity *

self

)

<<cert>> Allows access to the DDS_InstanceHandle_t associated with the DDS_Entity.

This operation returns the DDS_InstanceHandle_t that represents the DDS_Entity.

Parameters:

self	<<in>> Cannot be NULL.

Returns:

the instance handle associated with this entity.

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_EntityKind_t DDS_Entity_get_entity_kind

(

DDS_Entity *

self

)

Determine the type of DDS_Entity.

Parameters:

self	<<in>> Cannot be NULL.

Returns:

a value of DDS_EntityKind_t representing the type of this DDS_Entity.

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_StatusCondition* DDS_Entity_get_statuscondition

(

DDS_Entity *

self

)

<<cert>> Return the DDS_StatusCondition associated with a particular DDS_Entity.

Parameters:

self	<<in>> Cannot be NULL.

Returns:

The DDS_StatusCondition that belongs to the specified DDS_Entity.

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_StatusMask DDS_Entity_get_status_changes

(

DDS_Entity *

self

)

<<cert>> Retrieves the list of communication statuses in the DDS_Entity that are triggered.

That is, the list of statuses whose value has changed since the last time the application read the status using the get_*_status() function.

When the entity is first created or if the entity is not enabled, all communication statuses are in the "untriggered" state so the list returned by the get_status_changes operation will be empty.

The list of statuses returned by the get_status_changes operation refers to the status that are triggered on the Entity itself and does not include statuses that apply to contained entities.

Parameters:

self	<<in>> Cannot be NULL.

Returns:

list of communication statuses in the DDS_Entity that are triggered.

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:

Status Kinds