You are here: Part 2: Core Concepts > Sending Data > Publisher/Subscriber QosPolicies > ENTITYFACTORY QosPolicy

ENTITYFACTORY QosPolicy

This QosPolicy controls whether or not child Entities are created in the enabled state.

This QosPolicy applies to the DomainParticipantFactory, DomainParticipants, Publishers, and Subscribers, which act as ‘factories’ for the creation of subordinate Entities. A DomainParticipantFactory is used to create DomainParticipants. A DomainParticipant is used to create both Publishers and Subscribers. A Publisher is used to create DataWriters, similarly a Subscriber is used to create DataReaders.

Entities can be created either in an ‘enabled’ or ‘disabled’ state. An enabled entity can actively participate in communication. A disabled entity cannot be discovered or take part in communication until it is explicitly enabled. For example, Connext DDS will not send data if the write() operation is called on a disabled DataWriter, nor will Connext DDS deliver data to a disabled DataReader. You can only enable a disabled entity. Once an entity is enabled, you cannot disable it, see Enabling DDS Entities about the enable() method.

The ENTITYFACTORY contains only one member, as illustrated in .

DDS_EntityFactoryQosPolicy

Type

Field Name

Description

DDS_Boolean

autoenable_created_entities

DDS_BOOLEAN_TRUE: enable Entities when they are created

DDS_BOOLEAN_FALSE: do not enable Entities when they are created

The ENTITYFACTORY QosPolicy controls whether the Entities created from the factory are automatically enabled upon creation or are left disabled. For example, if a Publisher is configured to auto-enable created Entities, then all DataWriters created from that Publisher will be automatically enabled.

Note: if an entity is disabled, then all of the child Entities it creates are also created in a disabled state, regardless of the setting of this QosPolicy. However, enabling a disabled entity will enable all of its children if this QosPolicy is set to autoenable child Entities.

Note: an entity can only be enabled; it cannot be disabled after its been enabled.

See Example for an example of how to set this policy.

There are various reasons why you may want to create Entities in the disabled state:

See Enabling DDS Entities for more information about enabled/disabled Entities.

Example

The code in Figure 25 illustrates how to use the ENTITYFACTORY QoS.

Figure 25 Configuring a Publisher so that New DataWriters are Disabled

DDS_PublisherQos publisher_qos;1Note in C, you must initialize the QoS structures before they are used, see Special QosPolicy Handling Considerations for C on page 1.
// topic, publisher, writer_listener already created
if (publisher->get_qos(publisher_qos) != DDS_RETCODE_OK) {
    // handle error
}
publisher_qos.entity_factory.autoenable_created_entities 
    = DDS_BOOLEAN_FALSE;
if (publisher->set_qos(publisher_qos) != DDS_RETCODE_OK) {
    // handle error
}
// Subsequently created DataWriters are created disabled and
// must be explicitly enabled by the user-code
DDSDataWriter* writer = publisher->create_datawriter(topic,
    DDS_DATAWRITER_QOS_DEFAULT, writer_listener, DDS_STATUS_MASK_ALL);
// now do other initialization
// Now explicitly enable the DataWriter, this will allow other
// applications to discover the DataWriter and for this application
// to send data when the DataWriter’s write() method is called
writer->enable();

Properties

This QosPolicy can be modified at any time.

It can be set differently on the publishing and subscribing sides.

Related QosPolicies

This QosPolicy does not interact with any other policies.

Applicable DDS Entities

System Resource Considerations

This QosPolicy does not significantly impact the use of system resources.

© 2016 RTI