# Listener

group (Listener API)

  This defines the public API of listeners in the Eclipse Cyclone DDS C language binding.

  Typedefs

  typedef struct dds_listener dds_listener_t

    DDS Listener type (opaque).

  Functions

  dds_listener_t *dds_create_listener(void *arg)

    Allocate memory and initializes to default values (DDS_LUNSET) of a listener.

    Parameters:

      - arg – [in] optional pointer that will be passed on to the listener callbacks

    Returns:

      Returns a pointer to the allocated memory for dds_listener_t structure.

  void dds_delete_listener(dds_listener_t *listener)

    Delete the memory allocated to listener structure.

    Parameters:

      - listener – [in] pointer to the listener struct to delete

  void dds_reset_listener(dds_listener_t *listener)

    Reset the listener structure contents to DDS_LUNSET.

    Parameters:

      - listener – [inout] pointer to the listener struct to reset

  void dds_copy_listener(dds_listener_t *dst, const dds_listener_t *src)

    Copy the listener callbacks from source to destination.

    Parameters:

      - dst – [inout] The pointer to the destination listener structure, where the content is to copied

      - src – [in] The pointer to the source listener structure to be copied

  void dds_merge_listener(dds_listener_t *dst, const dds_listener_t *src)

    Copy the listener callbacks from source to destination, unless already set.

    Any listener callbacks already set in `dst` (including NULL) are skipped, only those set to DDS_LUNSET are copied from `src`.

    Parameters:

      - dst – [inout] The pointer to the destination listener structure, where the content is merged

      - src – [in] The pointer to the source listener structure to be copied

## DCPS Status

group (DDS C Communication Status API)

  This defines the public API of the Communication Status in the Eclipse Cyclone DDS C language binding. Listeners are implemented as structs containing callback functions that take listener status types as arguments.

  Typedefs

  typedef struct dds_offered_deadline_missed_status dds_offered_deadline_missed_status_t

    DCPS_Status_OfferedDeadlineMissed DOC_TODO.

  typedef struct dds_offered_incompatible_qos_status dds_offered_incompatible_qos_status_t

    DCPS_Status_OfferedIncompatibleQoS DOC_TODO.

  typedef struct dds_publication_matched_status dds_publication_matched_status_t

    DCPS_Status_PublicationMatched DOC_TODO.

  typedef struct dds_liveliness_lost_status dds_liveliness_lost_status_t

    DCPS_Status_LivelinessLost DOC_TODO.

  typedef struct dds_subscription_matched_status dds_subscription_matched_status_t

    DCPS_Status_SubscriptionMatched DOC_TODO.

  typedef struct dds_sample_rejected_status dds_sample_rejected_status_t

    DCPS_Status_SampleRejected DOC_TODO.

  typedef struct dds_liveliness_changed_status dds_liveliness_changed_status_t

    DCPS_Status_LivelinessChanged DOC_TODO.

  typedef struct dds_requested_deadline_missed_status dds_requested_deadline_missed_status_t

    DCPS_Status_RequestedDeadlineMissed DOC_TODO.

  typedef struct dds_requested_incompatible_qos_status dds_requested_incompatible_qos_status_t

    DCPS_Status_RequestedIncompatibleQoS DOC_TODO.

  typedef struct dds_sample_lost_status dds_sample_lost_status_t

    DCPS_Status_SampleLost DOC_TODO.

  typedef struct dds_inconsistent_topic_status dds_inconsistent_topic_status_t

    DCPS_Status_InconsistentTopic DOC_TODO.

  Enums

  enum dds_sample_rejected_status_kind

    Rejected Status DOC_TODO.

    Values:

    enumerator DDS_NOT_REJECTED

      DOC_TODO

    enumerator DDS_REJECTED_BY_INSTANCES_LIMIT

      DOC_TODO

    enumerator DDS_REJECTED_BY_SAMPLES_LIMIT

      DOC_TODO

    enumerator DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT

      DOC_TODO

  struct dds_offered_deadline_missed_status
    #include <dds_public_status.h>

    DCPS_Status_OfferedDeadlineMissed DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

    dds_instance_handle_t last_instance_handle

      DOC_TODO

  struct dds_offered_incompatible_qos_status
    #include <dds_public_status.h>

    DCPS_Status_OfferedIncompatibleQoS DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

    uint32_t last_policy_id

      DOC_TODO

  struct dds_publication_matched_status
    #include <dds_public_status.h>

    DCPS_Status_PublicationMatched DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

    uint32_t current_count

      DOC_TODO

    int32_t current_count_change

      DOC_TODO

    dds_instance_handle_t last_subscription_handle

      DOC_TODO

  struct dds_liveliness_lost_status
    #include <dds_public_status.h>

    DCPS_Status_LivelinessLost DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

  struct dds_subscription_matched_status
    #include <dds_public_status.h>

    DCPS_Status_SubscriptionMatched DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

    uint32_t current_count

      DOC_TODO

    int32_t current_count_change

      DOC_TODO

    dds_instance_handle_t last_publication_handle

      DOC_TODO

  struct dds_sample_rejected_status
    #include <dds_public_status.h>

    DCPS_Status_SampleRejected DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

    dds_sample_rejected_status_kind last_reason

      DOC_TODO

    dds_instance_handle_t last_instance_handle

      DOC_TODO

  struct dds_liveliness_changed_status
    #include <dds_public_status.h>

    DCPS_Status_LivelinessChanged DOC_TODO.

    Public Members

    uint32_t alive_count

      DOC_TODO

    uint32_t not_alive_count

      DOC_TODO

    int32_t alive_count_change

      DOC_TODO

    int32_t not_alive_count_change

      DOC_TODO

    dds_instance_handle_t last_publication_handle

      DOC_TODO

  struct dds_requested_deadline_missed_status
    #include <dds_public_status.h>

    DCPS_Status_RequestedDeadlineMissed DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

    dds_instance_handle_t last_instance_handle

      DOC_TODO

  struct dds_requested_incompatible_qos_status
    #include <dds_public_status.h>

    DCPS_Status_RequestedIncompatibleQoS DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

    uint32_t last_policy_id

      DOC_TODO

  struct dds_sample_lost_status
    #include <dds_public_status.h>

    DCPS_Status_SampleLost DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

  struct dds_inconsistent_topic_status
    #include <dds_public_status.h>

    DCPS_Status_InconsistentTopic DOC_TODO.

    Public Members

    uint32_t total_count

      DOC_TODO

    int32_t total_count_change

      DOC_TODO

## Setters

group (Setters)

  Functions

  dds_return_t dds_lset_data_available_arg(dds_listener_t *listener, dds_on_data_available_fn callback, void *arg, bool reset_on_invoke)

    Set the data_available callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_data_on_readers_arg(dds_listener_t *listener, dds_on_data_on_readers_fn callback, void *arg, bool reset_on_invoke)

    Set the data_on_readers callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_inconsistent_topic_arg(dds_listener_t *listener, dds_on_inconsistent_topic_fn callback, void *arg, bool reset_on_invoke)

    Set the inconsistent_topic callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_liveliness_changed_arg(dds_listener_t *listener, dds_on_liveliness_changed_fn callback, void *arg, bool reset_on_invoke)

    Set the liveliness_changed callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_liveliness_lost_arg(dds_listener_t *listener, dds_on_liveliness_lost_fn callback, void *arg, bool reset_on_invoke)

    Set the liveliness_lost callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_offered_deadline_missed_arg(dds_listener_t *listener, dds_on_offered_deadline_missed_fn callback, void *arg, bool reset_on_invoke)

    Set the offered_deadline_missed callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_offered_incompatible_qos_arg(dds_listener_t *listener, dds_on_offered_incompatible_qos_fn callback, void *arg, bool reset_on_invoke)

    Set the offered_incompatible_qos callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_publication_matched_arg(dds_listener_t *listener, dds_on_publication_matched_fn callback, void *arg, bool reset_on_invoke)

    Set the publication_matched callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_requested_deadline_missed_arg(dds_listener_t *listener, dds_on_requested_deadline_missed_fn callback, void *arg, bool reset_on_invoke)

    Set the requested_deadline_missed callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_requested_incompatible_qos_arg(dds_listener_t *listener, dds_on_requested_incompatible_qos_fn callback, void *arg, bool reset_on_invoke)

    Set the requested_incompatible_qos callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_sample_lost_arg(dds_listener_t *listener, dds_on_sample_lost_fn callback, void *arg, bool reset_on_invoke)

    Set the sample_lost callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_sample_rejected_arg(dds_listener_t *listener, dds_on_sample_rejected_fn callback, void *arg, bool reset_on_invoke)

    Set the sample_rejected callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lset_subscription_matched_arg(dds_listener_t *listener, dds_on_subscription_matched_fn callback, void *arg, bool reset_on_invoke)

    Set the subscription_matched callback and argument in the listener structure.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

      - arg – [in] callback argument that is passed uninterpreted to the callback function

      - reset_on_invoke – [in] whether or not the status should be cleared when the listener callback is invoked

    Return values:

      - DDS_RETCODE_OK – success

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  void dds_lset_inconsistent_topic(dds_listener_t *listener, dds_on_inconsistent_topic_fn callback)

    Set the inconsistent_topic callback in the listener structure.

    Equivalent to calling dds_lset_inconsistent_topic_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_liveliness_lost(dds_listener_t *listener, dds_on_liveliness_lost_fn callback)

    Set the liveliness_lost callback in the listener structure.

    Equivalent to calling dds_lset_liveliness_lost_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_offered_deadline_missed(dds_listener_t *listener, dds_on_offered_deadline_missed_fn callback)

    Set the offered_deadline_missed callback in the listener structure.

    Equivalent to calling dds_lset_offered_deadline_missed_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_offered_incompatible_qos(dds_listener_t *listener, dds_on_offered_incompatible_qos_fn callback)

    Set the offered_incompatible_qos callback in the listener structure.

    Equivalent to calling dds_lset_offered_incompatible_qos_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_data_on_readers(dds_listener_t *listener, dds_on_data_on_readers_fn callback)

    Set the data_on_readers callback in the listener structure.

    Equivalent to calling dds_lset_data_on_readers_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_sample_lost(dds_listener_t *listener, dds_on_sample_lost_fn callback)

    Set the sample_lost callback in the listener structure.

    Equivalent to calling dds_lset_sample_lost_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_data_available(dds_listener_t *listener, dds_on_data_available_fn callback)

    Set the data_available callback in the listener structure.

    Equivalent to calling dds_lset_data_available_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_sample_rejected(dds_listener_t *listener, dds_on_sample_rejected_fn callback)

    Set the sample_rejected callback in the listener structure.

    Equivalent to calling dds_lset_sample_rejected_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_liveliness_changed(dds_listener_t *listener, dds_on_liveliness_changed_fn callback)

    Set the liveliness_changed callback in the listener structure.

    Equivalent to calling dds_lset_liveliness_changed_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_requested_deadline_missed(dds_listener_t *listener, dds_on_requested_deadline_missed_fn callback)

    Set the requested_deadline_missed callback in the listener structure.

    Equivalent to calling dds_lset_requested_deadline_missed_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_requested_incompatible_qos(dds_listener_t *listener, dds_on_requested_incompatible_qos_fn callback)

    Set the requested_incompatible_qos callback in the listener structure.

    Equivalent to calling dds_lset_requested_incompatible_qos_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_publication_matched(dds_listener_t *listener, dds_on_publication_matched_fn callback)

    Set the publication_matched callback in the listener structure.

    Equivalent to calling dds_lset_publication_matched_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

  void dds_lset_subscription_matched(dds_listener_t *listener, dds_on_subscription_matched_fn callback)

    Set the subscription_matched callback in the listener structure.

    Equivalent to calling dds_lset_subscription_matched_arg with arg set to the argument passed in dds_create_listener() and reset_on_invoke to true, and throwing away the result.

    Parameters:

      - listener – [inout] listener structure to update

      - callback – [in] the callback to set or a null pointer

## Getters

group (Getters)

  Functions

  dds_return_t dds_lget_data_available_arg(const dds_listener_t *listener, dds_on_data_available_fn *callback, void **arg, bool *reset_on_invoke)

    Get the data_available callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_data_on_readers_arg(const dds_listener_t *listener, dds_on_data_on_readers_fn *callback, void **arg, bool *reset_on_invoke)

    Get the data_on_readers callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_inconsistent_topic_arg(const dds_listener_t *listener, dds_on_inconsistent_topic_fn *callback, void **arg, bool *reset_on_invoke)

    Get the inconsistent_topic callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_liveliness_changed_arg(const dds_listener_t *listener, dds_on_liveliness_changed_fn *callback, void **arg, bool *reset_on_invoke)

    Get the liveliness_changed callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_liveliness_lost_arg(const dds_listener_t *listener, dds_on_liveliness_lost_fn *callback, void **arg, bool *reset_on_invoke)

    Get the liveliness_lost callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_offered_deadline_missed_arg(const dds_listener_t *listener, dds_on_offered_deadline_missed_fn *callback, void **arg, bool *reset_on_invoke)

    Get the offered_deadline_missed callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_offered_incompatible_qos_arg(const dds_listener_t *listener, dds_on_offered_incompatible_qos_fn *callback, void **arg, bool *reset_on_invoke)

    Get the offered_incompatible_qos callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_publication_matched_arg(const dds_listener_t *listener, dds_on_publication_matched_fn *callback, void **arg, bool *reset_on_invoke)

    Get the publication_matched callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_requested_deadline_missed_arg(const dds_listener_t *listener, dds_on_requested_deadline_missed_fn *callback, void **arg, bool *reset_on_invoke)

    Get the subscription_matched callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_requested_incompatible_qos_arg(const dds_listener_t *listener, dds_on_requested_incompatible_qos_fn *callback, void **arg, bool *reset_on_invoke)

    Get the requested_incompatible_qos callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_sample_lost_arg(const dds_listener_t *listener, dds_on_sample_lost_fn *callback, void **arg, bool *reset_on_invoke)

    Get the sample_lost callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_sample_rejected_arg(const dds_listener_t *listener, dds_on_sample_rejected_fn *callback, void **arg, bool *reset_on_invoke)

    Get the sample_rejected callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  dds_return_t dds_lget_subscription_matched_arg(const dds_listener_t *listener, dds_on_subscription_matched_fn *callback, void **arg, bool *reset_on_invoke)

    Get the subscription_matched callback from the listener structure.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

      - arg – [out] Callback argument pointer; may be a null pointer

      - reset_on_invoke – [out] Whether the status is reset by listener invocation; may be a null pointer

    Return values:

      - DDS_RETCODE_OK – if successful

      - DDS_RETCODE_BAD_PARAMETER – listener is a null pointer

  void dds_lget_inconsistent_topic(const dds_listener_t *listener, dds_on_inconsistent_topic_fn *callback)

    Get the inconsistent_topic callback from the listener structure.

    Equivalent to calling dds_lget_inconsistent_topic_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_liveliness_lost(const dds_listener_t *listener, dds_on_liveliness_lost_fn *callback)

    Get the liveliness_lost callback from the listener structure.

    Equivalent to calling dds_lget_liveliness_lost_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_offered_deadline_missed(const dds_listener_t *listener, dds_on_offered_deadline_missed_fn *callback)

    Get the offered_deadline_missed callback from the listener structure.

    Equivalent to calling dds_lget_offered_deadline_missed_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_offered_incompatible_qos(const dds_listener_t *listener, dds_on_offered_incompatible_qos_fn *callback)

    Get the offered_incompatible_qos callback from the listener structure.

    Equivalent to calling dds_lget_offered_incompatible_qos_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_data_on_readers(const dds_listener_t *listener, dds_on_data_on_readers_fn *callback)

    Get the data_on_readers callback from the listener structure.

    Equivalent to calling dds_lget_data_on_readers_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_sample_lost(const dds_listener_t *listener, dds_on_sample_lost_fn *callback)

    Get the sample_lost callback from the listener structure.

    Equivalent to calling dds_lget_sample_lost_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_data_available(const dds_listener_t *listener, dds_on_data_available_fn *callback)

    Get the data_available callback from the listener structure.

    Equivalent to calling dds_lget_data_available_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_sample_rejected(const dds_listener_t *listener, dds_on_sample_rejected_fn *callback)

    Get the sample_rejected callback from the listener structure.

    Equivalent to calling dds_lget_sample_rejected_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_liveliness_changed(const dds_listener_t *listener, dds_on_liveliness_changed_fn *callback)

    Get the liveliness_changed callback from the listener structure.

    Equivalent to calling dds_lget_liveliness_changed_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_requested_deadline_missed(const dds_listener_t *listener, dds_on_requested_deadline_missed_fn *callback)

    Get the requested_deadline_missed callback from the listener structure.

    Equivalent to calling dds_lget_requested_deadline_missed_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_requested_incompatible_qos(const dds_listener_t *listener, dds_on_requested_incompatible_qos_fn *callback)

    Get the requested_incompatible_qos callback from the listener structure.

    Equivalent to calling dds_lget_requested_incompatible_qos_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_publication_matched(const dds_listener_t *listener, dds_on_publication_matched_fn *callback)

    Get the publication_matched callback from the listener structure.

    Equivalent to calling dds_lget_publication_matched_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

  void dds_lget_subscription_matched(const dds_listener_t *listener, dds_on_subscription_matched_fn *callback)

    Get the subscription_matched callback from the listener structure.

    Equivalent to calling dds_lget_subscription_matched_arg with arg and reset_on_invoke set to a null pointer and throwing away the result.

    Parameters:

      - listener – [in] The pointer to the listener structure, where the callback will be retrieved from

      - callback – [out] Callback function; may be a null pointer

## Interaction with DDS Entities

group (Entity Listener)

  Get or set listener associated with an entity, type of listener provided much match type of entity.

  Functions

  dds_return_t dds_get_listener(dds_entity_t entity, dds_listener_t *listener)

    Get entity listeners.

    This operation allows access to the existing listeners attached to the entity.

    DOC_TODO: Link to (generic) Listener and status information.

    Parameters:

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

      - listener – [out] Pointer to the listener structure that returns the set of listener callbacks.

    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_BAD_PARAMETER – The listener parameter is NULL.

      - 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.

  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).

    A call to this operation will immediately invoke any listener callbacks for which the corresponding status flag is set. It may cause spurious invocations, including multiple invocations for one listener. For most cases this is unlikely, but for the DATA_ON_READERS listeners it is quite likely, though not certain.

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

    ###

    #### Communication Status

    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.

    ###

    #### Status Propagation

    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. DOC_TODO: Link to (generic) Listener and status information.

    Returns:

      A dds_return_t indicating success or failure.