Entity Use Cases
[Programming How-To's]

Working with entities. More...

Enabling an entity

    if (DDS_Entity_enable((DDS_Entity*)entity) != DDS_RETCODE_OK) {
        printf("***Error: failed to enable entity\n");
    }

Checking if a status changed on an entity.

Given an DDS_Entity and a DDS_StatusKind to check for, get the list of statuses that have changed since the last time they were respectively cleared.
```
    DDS_StatusMask status_changes_mask;
    
    status_changes_mask = DDS_Entity_get_status_changes(entity); 
```

Check if status_kind was changed since the last time it was cleared. A plain communication status change is cleared when the status is read using the entity's get_<plain communication status>() method. A read communication status change is cleared when the data is taken from the middleware via a TDataReader_take() call [see Changes in Status for details].
```
    if (status_changes_mask & status_kind) {
        return 1; /* ... YES, status_kind changed ... */
    } else {
        return 0; /* ... NO, status_kind did NOT change ... */
    }        
```

Changing the QoS for an entity

The QoS for an entity can be specified at the entity creation time. Once an entity has been created, its QoS can be manipulated as follows.

Get an entity's QoS settings using get_qos (abstract)

    if (DDS_DomainParticipant_get_qos(entity, &qos) != DDS_RETCODE_OK) {
        printf("***Error: failed to get qos\n");
    }

Change the desired qos policy fields

    /* Change the desired qos policies */
    /* qos.policy.field = ... */

Set the qos using set_qos (abstract).

    switch (DDS_DomainParticipant_set_qos(entity, &qos)) {
        case DDS_RETCODE_OK: { /* success */
        } break;        
        case DDS_RETCODE_IMMUTABLE_POLICY: {
            printf("***Error: tried changing a policy that can only be"
                   "          set at entity creation time\n");
        } break;
        case DDS_RETCODE_INCONSISTENT_POLICY: {
            printf("***Error: tried changing a policy to a value inconsistent"
                   "          with other policy settings\n");
        } break;
        default: {             
            printf("***Error: some other failure\n");                
        }                     
    }   
    
    DDS_DomainParticipantQos_finalize(&qos);

Changing the listener and enabling/disabling statuses associated with it

The listener for an entity can be specified at the entity creation time. By default the listener is enabled for all the statuses supported by the entity.

Once an entity has been created, its listener and/or the statuses for which it is enabled can be manipulated as follows.

User defines entity listener methods

    /* ... methods defined by EntityListener ... */
    MyEntityListener_LivelinessChanged(   /* one example method */
                        void* listener_data,
                        DDS_Entity* entity,
                        const struct DDS_LivelinessChangedStatus *status);

Set the entity_listener functions

    /* ... set the listener struct to the previously defined functions ...
           one example is shown */
    entity_listener.on_liveliness_changed = MyEntityListener_LivelinessChanged;

Get an entity's listener using get_listener (abstract)

    entity_listener = DDS_Entity_get_listener(entity);

Enable status_kind for the listener

    enabled_status_list |= status_kind;

Disable status_kind for the listener

    enabled_status_list &= ~status_kind;

Set an entity's listener to entity_listener using set_listener (abstract). Only enable the listener for the statuses specified by the enabled_status_list.

    if (DDS_Entity_set_listener(entity, &entity_listener, enabled_status_list) 
                 != DDS_RETCODE_OK) {
        printf("***Error: setting entity listener\n");
    }

Enabling/Disabling statuses associated with a status condition

Upon entity creation, by default, all the statuses are enabled for the DDS_StatusCondition associated with the entity.

Once an entity has been created, the list of statuses for which the DDS_StatusCondition is triggered can be manipulated as follows.

Given an entity, a status_kind, and the associated status_condition:

    statuscondition = DDS_Entity_get_statuscondition(entity);

Get the list of statuses enabled for the status_condition

    enabled_status_list = DDS_StatusCondition_get_enabled_statuses(statuscondition);

Check if the given status_kind is enabled for the status_condition

    if (enabled_status_list & status_kind) {
        /*... YES, status_kind is enabled ... */
    } else {
        /* ... NO, status_kind is NOT enabled ... */
    }

Enable status_kind for the status_condition

    if (DDS_StatusCondition_set_enabled_statuses(status_condition,
                                   enabled_status_list | status_kind) 
                 != DDS_RETCODE_OK) {
        /* ... check for cause of failure */
    }

Disable status_kind for the status_condition