15.2 Enabling DDS Entities

The enable() operation changes an Entity from a non-operational to an operational state. Entity objects can be created disabled or enabled. This is controlled by the value of the 46.2 ENTITYFACTORY QosPolicy on the corresponding factory for the Entity (not on the Entity itself).

By default, all Entities are automatically created in the enabled state. This means that as soon as the Entity is created, it is ready to be used. In some cases, you may want to create the Entity in a ‘disabled’ state. For example, by default, as soon as you create a DataReader, the DataReader will start receiving new DDS samples for its Topic if they are being sent. However, your application may still be initializing other components and may not be ready to process the data at that time. In that case, you can tell the Subscriber to create the DataReader in a disabled state. After all of the other parts of the application have been created and initialized, then the DataReader can be enabled to actually receive messages.

To create a particular entity in a disabled state, modify the EntityFactory QosPolicy of its corresponding factory entity before calling create_<entity>(). For example, to create a disabled DataReader, modify the Subscriber’s QoS as follows:

DDS_SubscriberQos subscriber_qos;
subscriber->get_qos(subscriber_qos);
subscriber_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;
subscriber->set_qos(subscriber_qos);
DDSDataReader* datareader = 
    subscriber->create_datareader(topic, DDS_DATAREADER_QOS_DEFAULT, listener);

When the application is ready to process received data, it can enable the DataReader:

datareader->enable();

15.2.1 Rules for Calling enable()

In the following, a ‘Factory’ refers to a DomainParticipant, Publisher, or Subscriber; a ‘child’ refers to an entity created by the factory:

  • If the factory is disabled, its children are always created disabled.
  • If the factory is enabled, its children will be created according to the setting in the factory's EntityFactoryQoS value.
  • Calling enable() on a child whose factory object is still disabled will fail and return DDS_RECODE_RECONDITION_NOT_MET.
  • Calling enable() on a factory with EntityFactoryQoS set to DDS_BOOLEAN_TRUE will recursively enable all of the factory’s children. If the factory’s EntityFactoryQoS is set to DDS_BOOLEAN_FALSE, only the factory itself will be enabled.
  • Calling enable() on an entity that is already enabled returns DDS_RETCODE_OK and has no effect.
  • There is no complementary “disable” operation. You cannot disable an entity after it is enabled. Disabled Entities must have been created in that state.
  • An entity’s Listener will only be invoked if the entity is enabled.
  • The existence of an entity is not propagated to other DomainParticipants until the entity is enabled (see 22. Discovery Overview).
  • If a DataWriter/DataReader is to be created in an enabled state, then the associated Topic must already be enabled. The enabled state of the Topic does not matter, if the Publisher/Subscriber has its EntityFactory QosPolicy to create children in a disabled state.
  • When calling enable() for a DataWriter/DataReader, both the Publisher/Subscriber and the Topic must be enabled, or the operation will fail and return DDS_RETCODE_PRECONDITION_NOT_MET.

The following operations may be invoked on disabled Entities:

  • get_qos() and set_qos()Some DDS-specified QosPolicies are immutable—they cannot be changed after an Entity is enabled. This means that for those policies, if the entity was created in the disabled state, get/set_qos() can be used to change the values of those policies until enabled() is called on the Entity. After the Entity is enabled, changing the values of those policies will not affect the Entity. However, there are mutable QosPolicies whose values can be changed at anytime–even after the Entity has been enabled.

    • Finally, there are extended QosPolicies that are not a part of the DDS specification but offered by Connext to control extended features for an Entity. Some of those extended QosPolicies cannot be changed after the Entity has been created—regardless of whether the Entity is enabled or disabled.

    Into which exact categories a QosPolicy falls—mutable at any time, immutable after enable, immutable after creation—is described in the documentation for the specific policy.

  • get_status_changes() and get_*_status()The status of an Entity can be retrieved at any time (but the status of a disabled Entity never changes). (Note: get_*_status() resets the related status so it no longer considered “changed.”)
  • get_statuscondition()An Entity’s StatusCondition can be checked at any time (although the status of a disabled Entity never changes).
  • get_listener() and set_listener()An Entity’s Listener can be changed at any time.
  • create_*() and delete_*()A factory Entity can still be used to create or delete any child Entity that it can produce. Note: following the rules discussed previously, a disabled Entity will always create its children in a disabled state, no matter what the value of the EntityFactory QosPolicy is.
  • lookup_*()An Entity can always look up children it has previously created.

Most other operations are not allowed on disabled Entities. Executing one of those operations when an Entity is disabled will result in a return code of DDS_RETCODE_NOT_ENABLED. The documentation for a particular operation will explicitly state if it is not allowed to be used if the Entity is disabled.

The builtin transports are implicitly registered when (a) the DomainParticipant is enabled, (b) the first DataWriter/DataReader is created, or (c) you look up a builtin data reader, whichever happens first. Any changes to the builtin transport properties that are made after the builtin transports have been registered will have no affect on any DataWriters/DataReaders.