Function dds_set_listener

Function Documentation

dds_return_t dds_set_listener(dds_entity_t entity, const dds_listener_t *listener)

Set entity listeners.

This operation attaches a dds_listener_t to the dds_entity_t. Only one Listener can be attached to each Entity. If a Listener was already attached, this operation will replace it with the new one. In other words, all related callbacks are replaced (possibly with NULL).

When listener parameter is NULL, all listener callbacks that were possibly set on the Entity will be removed.

For each communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever that plain communication status changes. For each plain communication status activated in the mask, the associated Listener callback is invoked and the communication status is reset to FALSE, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the get_<status_name> from inside the listener it will see the status already reset.

In case a related callback within the Listener is not set, the Listener of the Parent entity is called recursively, until a Listener with the appropriate callback set has been found and called. This allows the application to set (for instance) a default behaviour in the Listener of the containing Publisher and a DataWriter specific behaviour when needed. In case the callback is not set in the Publishers’ Listener either, the communication status will be propagated to the Listener of the DomainParticipant of the containing DomainParticipant. In case the callback is not set in the DomainParticipants’ Listener either, the Communication Status flag will be set, resulting in a possible WaitSet trigger.

Note

Not all listener callbacks are related to all entities.

Parameters

  • entity – [in] Entity on which to get the listeners.

  • listener – [in] Pointer to the listener structure that contains the set of listener callbacks (maybe NULL).

Return values

  • DDS_RETCODE_OK – The listeners of to the entity have been successfully been copied into the specified listener parameter.

  • DDS_RETCODE_ERROR – An internal error has occurred.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

Returns

A dds_return_t indicating success or failure.