Function dds_enable

Function Documentation

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.