Open topic with navigation
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 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:
In the following, a ‘Factory’ refers to a DomainParticipant, Publisher, or Subscriber; a ‘child’ refers to an entity created by the factory:
The following operations may be invoked on disabled Entities:
Finally, there are extended QosPolicies that are not a part of the DDS specification but offered by Connext DDS 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.
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.
© 2018 RTI
Open topic with navigation