You are here: Part 2: Core Concepts > DDS Entities > Common Operations for All DDS Entities > Enabling DDS Entities

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 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_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;
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:


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:

The following operations may be invoked on disabled Entities:

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.

© 2016 RTI