Entities¶

All entities are represented by a process-private handle, with one call to enable an entity when it was created disabled. An entity is created enabled by default. Note: disabled creation is currently not supported.

group entity

Every DDS object in the library is an Entity. All entities are represented by a process-private handle, with one call to enable an entity when it was created disabled. An entity is created enabled by default. Note: disabled creation is currently not supported.

Typedefs

typedef int32_t dds_entity_t¶

Handle to an entity.

A valid entity handle will always have a positive integer value. Should the value be negative, it is one of the DDS_RETCODE_* error codes.

Functions

dds_return_t dds_enable(dds_entity_t entity)¶

Enable entity.

This operation enables the dds_entity_t. Created dds_entity_t objects can start in either an enabled or disabled state. This is controlled by the value of the entityfactory policy on the corresponding parent entity for the given entity. Enabled entities are immediately activated at creation time meaning all their immutable QoS settings can no longer be changed. Disabled Entities are not yet activated, so it is still possible to change their immutable QoS settings. However, once activated the immutable QoS settings can no longer be changed. Creating disabled entities can make sense when the creator of the DDS_Entity does not yet know which QoS settings to apply, thus allowing another piece of code to set the QoS later on.

The default setting of DDS_EntityFactoryQosPolicy is such that, by default, entities are created in an enabled state so that it is not necessary to explicitly call dds_enable on newly-created entities.

The dds_enable operation produces the same results no matter how many times it is performed. Calling dds_enable on an already enabled DDS_Entity returns DDS_RETCODE_OK and has no effect.

If an Entity has not yet been enabled, the only operations that can be invoked on it are: the ones to set, get or copy the QosPolicy settings, the ones that set (or get) the Listener, the ones that get the Status and the dds_get_status_changes operation (although the status of a disabled entity never changes). Other operations will return the error DDS_RETCODE_NOT_ENABLED.

Entities created with a parent that is disabled, are created disabled regardless of the setting of the entityfactory policy.

If the entityfactory policy has autoenable_created_entities set to TRUE, the dds_enable operation on the parent will automatically enable all child entities created with the parent.

The Listeners associated with an Entity are not called until the Entity is enabled. Conditions associated with an Entity that is not enabled are “inactive”, that is, have a trigger_value which is FALSE.

Note

Delayed entity enabling is not supported yet (CHAM-96).

Parameters

entity – [in] The entity to enable.

Return values

DDS_RETCODE_OK – The listeners of to the entity have been successfully been copied into the specified listener parameter.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.
DDS_RETCODE_PRECONDITION_NOT_MET – The parent of the given Entity is not enabled.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_delete(dds_entity_t entity)¶

Delete given entity.

This operation will delete the given entity. It will also automatically delete all its children, childrens’ children, etc entities.

Parameters

entity – [in] Entity to delete.

Return values

DDS_RETCODE_OK – The entity and its children (recursive are deleted).
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_entity_t dds_get_publisher(dds_entity_t writer)¶

Get entity publisher.

This operation returns the publisher to which the given entity belongs. For instance, it will return the Publisher that was used when creating a DataWriter (when that DataWriter was provided here).

Parameters

writer – [in] Entity from which to get its publisher.

Return values

>0 – A valid publisher handle.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A valid entity or an error code.

dds_entity_t dds_get_subscriber(dds_entity_t entity)¶

Get entity subscriber.

This operation returns the subscriber to which the given entity belongs. For instance, it will return the Subscriber that was used when creating a DataReader (when that DataReader was provided here).

Parameters

entity – [in] Entity from which to get its subscriber.

Return values

>0 – A valid subscriber handle.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted. DOC_TODO: Link to generic dds entity relations documentation.

Returns

A valid subscriber handle or an error code.

dds_entity_t dds_get_datareader(dds_entity_t entity)¶

Get entity datareader.

This operation returns the datareader to which the given entity belongs. For instance, it will return the DataReader that was used when creating a ReadCondition (when that ReadCondition was provided here).

Parameters

entity – [in] Entity from which to get its datareader.

Return values

>0 – A valid reader handle.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted. DOC_TODO: Link to generic dds entity relations documentation.

Returns

A valid reader handle or an error code.

dds_return_t dds_get_instance_handle(dds_entity_t entity, dds_instance_handle_t *ihdl)¶

Returns the instance handle that represents the entity.

Parameters

entity – [in] Entity of which to get the instance handle.
ihdl – [out] Pointer to dds_instance_handle_t.

Return values

DDS_RETCODE_OK – Success.
DDS_RETCODE_ERROR – An internal error has occurred. DOC_TODO: Check list of return codes is complete.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_get_guid(dds_entity_t entity, dds_guid_t *guid)¶

Returns the GUID that represents the entity in the network, and therefore only supports participants, readers and writers.

DOC_TODO: Check list of return codes is complete.

Parameters

entity – [in] Entity of which to get the instance handle.
guid – [out] Where to store the GUID.

Return values

DDS_RETCODE_OK – Success.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ERROR – An internal error has occurred.

Returns

A dds_return_t indicating success or failure.

dds_entity_t dds_get_parent(dds_entity_t entity)¶

Get entity parent.

This operation returns the parent to which the given entity belongs. For instance, it will return the Participant that was used when creating a Publisher (when that Publisher was provided here).

When a reader or a writer are created with a participant, then a subscriber or publisher are created implicitly. This function will return the implicit parent and not the used participant.

Parameters

entity – [in] Entity from which to get its parent.

Return values

>0 – A valid entity handle.
DDS_ENTITY_NIL – Called with a participant.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted. DOC_TODO: Link to generic dds entity relations documentation.

Returns

A valid entity handle or an error code.

dds_entity_t dds_get_participant(dds_entity_t entity)¶

Get entity participant.

This operation returns the participant to which the given entity belongs. For instance, it will return the Participant that was used when creating a Publisher that was used to create a DataWriter (when that DataWriter was provided here).

DOC_TODO: Link to generic dds entity relations documentation.

Parameters

entity – [in] Entity from which to get its participant.

Return values

>0 – A valid participant handle.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A valid entity or an error code.

dds_return_t dds_get_children(dds_entity_t entity, dds_entity_t *children, size_t size)¶

Get entity children.

This operation returns the children that the entity contains. For instance, it will return all the Topics, Publishers and Subscribers of the Participant that was used to create those entities (when that Participant is provided here).

This functions takes a pre-allocated list to put the children in and will return the number of found children. It is possible that the given size of the list is not the same as the number of found children. If less children are found, then the last few entries in the list are untouched. When more children are found, then only ‘size’ number of entries are inserted into the list, but still complete count of the found children is returned. Which children are returned in the latter case is undefined.

When supplying NULL as list and 0 as size, you can use this to acquire the number of children without having to pre-allocate a list.

When a reader or a writer are created with a participant, then a subscriber or publisher are created implicitly. When used on the participant, this function will return the implicit subscriber and/or publisher and not the related reader/writer.

Parameters

entity – [in] Entity from which to get its children.
children – [out] Pre-allocated array to contain the found children.
size – [in] Size of the pre-allocated children’s list.

Return values

>=0 – Number of found children (can be larger than ‘size’).
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – The children parameter is NULL, while a size is provided.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

Number of children or an error code.

dds_return_t dds_get_domainid(dds_entity_t entity, dds_domainid_t *id)¶

Get the domain id to which this entity is attached.

When creating a participant entity, it is attached to a certain domain. All the children (like Publishers) and childrens’ children (like DataReaders), etc are also attached to that domain.

This function will return the original domain ID when called on any of the entities within that hierarchy. For entities not associated with a domain, the id is set to DDS_DOMAIN_DEFAULT.

Parameters

entity – [in] Entity from which to get its children.
id – [out] Pointer to put the domain ID in.

Return values

DDS_RETCODE_OK – Domain ID was returned.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – The id parameter is NULL.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_triggered(dds_entity_t entity)¶

Checks whether the entity has one of its enabled statuses triggered.

Parameters

entity – [in] Entity for which to check for triggered status.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_entity_t dds_get_topic(dds_entity_t entity)¶

Get the topic.

This operation returns a topic (handle) when the function call is done with reader, writer, read condition or query condition. For instance, it will return the topic when it is used for creating the reader or writer. For the conditions, it returns the topic that is used for creating the reader which was used to create the condition.

Parameters

entity – [in] The entity.

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_BAD_PARAMETER – The entity parameter is not a valid parameter.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.

dds_return_t dds_assert_liveliness(dds_entity_t entity)¶

This operation manually asserts the liveliness of a writer or domain participant.

This operation manually asserts the liveliness of a writer or domain participant. This is used in combination with the Liveliness QoS policy to indicate that the entity remains active. This operation need only be used if the liveliness kind in the QoS is either DDS_LIVELINESS_MANUAL_BY_PARTICIPANT or DDS_LIVELINESS_MANUAL_BY_TOPIC.

Parameters

entity – [in] A domain participant or writer

Return values

DDS_RETCODE_OK – The operation was successful.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

Returns

A dds_return_t indicating success or failure.

group entity_qos

Almost all entities have get/set qos operations defined on them, again following the DCPS spec. But unlike the DCPS spec, the “present” field in qos_t allows one to initialize just the one QoS one wants to set & pass it to set_qos.

Functions

dds_return_t dds_get_qos(dds_entity_t entity, dds_qos_t *qos)¶

Get entity QoS policies.

This operation allows access to the existing set of QoS policies for the entity.

DOC_TODO: Link to generic QoS information documentation.

Parameters

entity – [in] Entity on which to get qos.
qos – [out] Pointer to the qos structure that returns the set policies.

Return values

DDS_RETCODE_OK – The existing set of QoS policy values applied to the entity has successfully been copied into the specified qos parameter.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – The qos parameter is NULL.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure. The QoS object will have at least all QoS relevant for the entity present and the corresponding dds_qget_… will return true.

dds_return_t dds_set_qos(dds_entity_t entity, const dds_qos_t *qos)¶

Set entity QoS policies.

This operation replaces the existing set of Qos Policy settings for an entity. The parameter qos must contain the struct with the QosPolicy settings which is checked for self-consistency.

The set of QosPolicy settings specified by the qos parameter are applied on top of the existing QoS, replacing the values of any policies previously set (provided, the operation returned DDS_RETCODE_OK).

Not all policies are changeable when the entity is enabled.

DOC_TODO: Link to generic QoS information documentation.

Note

Currently only Latency Budget and Ownership Strength are changeable QoS that can be set.

Parameters

entity – [in] Entity from which to get qos.
qos – [in] Pointer to the qos structure that provides the policies.

Return values

DDS_RETCODE_OK – The new QoS policies are set.
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – The qos parameter is NULL.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.
DDS_RETCODE_IMMUTABLE_POLICY – The entity is enabled and one or more of the policies of the QoS are immutable.
DDS_RETCODE_INCONSISTENT_POLICY – A few policies within the QoS are not consistent with each other.

Returns

A dds_return_t indicating success or failure.

DCPS Status¶

group dcps_status_getters

get_<status> APIs return the status of an entity and resets the status

Functions

dds_return_t dds_get_inconsistent_topic_status(dds_entity_t topic, dds_inconsistent_topic_status_t *status)¶

Get INCONSISTENT_TOPIC status.

This operation gets the status value corresponding to INCONSISTENT_TOPIC and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

topic – [in] The entity to get the status
status – [out] The pointer to dds_inconsistent_topic_status_t to get the status

Return values

DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

0 - Success

Returns

<0 - Failure

dds_return_t dds_get_publication_matched_status(dds_entity_t writer, dds_publication_matched_status_t *status)¶

Get PUBLICATION_MATCHED status.

This operation gets the status value corresponding to PUBLICATION_MATCHED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

writer – [in] The entity to get the status
status – [out] The pointer to dds_publication_matched_status_t to get the status

Return values

DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

0 - Success

Returns

<0 - Failure

dds_return_t dds_get_liveliness_lost_status(dds_entity_t writer, dds_liveliness_lost_status_t *status)¶

Get LIVELINESS_LOST status.

This operation gets the status value corresponding to LIVELINESS_LOST and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

writer – [in] The entity to get the status
status – [out] The pointer to dds_liveliness_lost_status_t to get the status

Return values

DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

0 - Success

Returns

<0 - Failure

dds_return_t dds_get_offered_deadline_missed_status(dds_entity_t writer, dds_offered_deadline_missed_status_t *status)¶

Get OFFERED_DEADLINE_MISSED status.

This operation gets the status value corresponding to OFFERED_DEADLINE_MISSED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

writer – [in] The entity to get the status
status – [out] The pointer to dds_offered_deadline_missed_status_t to get the status

Return values

DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

0 - Success

Returns

<0 - Failure

dds_return_t dds_get_offered_incompatible_qos_status(dds_entity_t writer, dds_offered_incompatible_qos_status_t *status)¶

Get OFFERED_INCOMPATIBLE_QOS status.

This operation gets the status value corresponding to OFFERED_INCOMPATIBLE_QOS and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

writer – [in] The writer entity to get the status
status – [out] The pointer to dds_offered_incompatible_qos_status_t to get the status

Return values

DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

0 - Success

Returns

<0 - Failure

dds_return_t dds_get_subscription_matched_status(dds_entity_t reader, dds_subscription_matched_status_t *status)¶

Get SUBSCRIPTION_MATCHED status.

This operation gets the status value corresponding to SUBSCRIPTION_MATCHED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

reader – [in] The reader entity to get the status
status – [out] The pointer to dds_subscription_matched_status_t to get the status

Return values

DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

0 - Success

Returns

<0 - Failure

dds_return_t dds_get_liveliness_changed_status(dds_entity_t reader, dds_liveliness_changed_status_t *status)¶

Get LIVELINESS_CHANGED status.

This operation gets the status value corresponding to LIVELINESS_CHANGED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

reader – [in] The entity to get the status
status – [out] The pointer to dds_liveliness_changed_status_t to get the status

Return values

DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

0 - Success

Returns

<0 - Failure

dds_return_t dds_get_sample_rejected_status(dds_entity_t reader, dds_sample_rejected_status_t *status)¶

Get SAMPLE_REJECTED status.

This operation gets the status value corresponding to SAMPLE_REJECTED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

reader – [in] The entity to get the status
status – [out] The pointer to dds_sample_rejected_status_t to get the status

Return values

DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

0 - Success

Returns

<0 - Failure

dds_return_t dds_get_sample_lost_status(dds_entity_t reader, dds_sample_lost_status_t *status)¶

Get SAMPLE_LOST status.

This operation gets the status value corresponding to SAMPLE_LOST and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

reader – [in] The entity to get the status
status – [out] The pointer to dds_sample_lost_status_t to get the status

Return values

DDS_RETCODE_OK – Success
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure

dds_return_t dds_get_requested_deadline_missed_status(dds_entity_t reader, dds_requested_deadline_missed_status_t *status)¶

Get REQUESTED_DEADLINE_MISSED status.

This operation gets the status value corresponding to REQUESTED_DEADLINE_MISSED and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

reader – [in] The entity to get the status
status – [out] The pointer to dds_requested_deadline_missed_status_t to get the status

Return values

DDS_RETCODE_OK – Success
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure

dds_return_t dds_get_requested_incompatible_qos_status(dds_entity_t reader, dds_requested_incompatible_qos_status_t *status)¶

Get REQUESTED_INCOMPATIBLE_QOS status.

This operation gets the status value corresponding to REQUESTED_INCOMPATIBLE_QOS and reset the status. The value can be obtained, only if the status is enabled for an entity. NULL value for status is allowed and it will reset the trigger value when status is enabled.

Parameters

reader – [in] The entity to get the status
status – [out] The pointer to dds_requested_incompatible_qos_status_t to get the status

Return values

DDS_RETCODE_OK – Success
DDS_RETCODE_ERROR – An internal error has occurred.
DDS_RETCODE_BAD_PARAMETER – One of the given arguments is not valid.
DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.
DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure

Interaction with Listeners¶

You can find the documentation on the interactions with listeners in the listener API documentation:.