qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/ndds/osapi/osapi_interfaceTracker.h

/*
 * (c) Copyright, Real-Time Innovations, 2015-2024.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef osapi_interfaceTracker_h
#define osapi_interfaceTracker_h

#include "osapi/osapi_dll.h"
#include "osapi/osapi_thread.h"
#include "osapi/osapi_interfaces.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
    RTI_OSAPI_INTERFACE_TRACKER_EVENT_KIND_INTERFACE_DELETED,
    RTI_OSAPI_INTERFACE_TRACKER_EVENT_KIND_INTERFACE_NEW,
    RTI_OSAPI_INTERFACE_TRACKER_EVENT_KIND_INTERFACE_CHANGED
} RTIOsapiInterfaceTrackerEventKind;

#define RTIOsapiInterfaceTrackerEventKind_toString(ek) \
  (ek == RTI_OSAPI_INTERFACE_TRACKER_EVENT_KIND_INTERFACE_DELETED \
           ? "DELETED" \
           : (ek == RTI_OSAPI_INTERFACE_TRACKER_EVENT_KIND_INTERFACE_NEW \
                      ? "NEW" \
                      : (ek == RTI_OSAPI_INTERFACE_TRACKER_EVENT_KIND_INTERFACE_CHANGED \
                                 ? "CHANGED" \
                                 : "<UNKNOWN>")))

/** @internal \ingroup RTIOsapiSocketClass
 * \brief An struct passed to the interface tracker callback function describing
 * a single interface change
 */
struct RTIOsapiInterfaceTrackerEvent {
    RTIOsapiInterfaceTrackerEventKind kind;
    RTIOsapiSocket_InterfaceDescription *sourceInterface;
};

/** @internal \ingroup RTIOsapiSocketClass
 * \brief AUTO sets both, simultaneous asynchronous and synchronous detection.
 */
typedef enum {
    RTI_OSAPI_INTERFACE_TRACKER_DETECTION_KIND_AUTO,
    RTI_OSAPI_INTERFACE_TRACKER_DETECTION_KIND_POLLING,
    RTI_OSAPI_INTERFACE_TRACKER_DETECTION_KIND_OS_NOTIFICATION
} RTIOsapiInterfaceTrackerDetectionKind;

/** @internal \ingroup RTIOsapiSocketClass
 * \brief A property used to initialize the interface tracker.
 */
struct RTIOsapiInterfaceTrackerProperty {
    RTIOsapiSocketAFKind addressFamilyKind;
    RTIOsapiInterfaceTrackerDetectionKind detectionKind;
    unsigned int interfaceMask;
    /* milliseconds */
    unsigned int interfacePollPeriod;
    char threadName[RTI_OSAPI_THREAD_NAME_MAX_SIZE];
};

struct RTIOsapiInterfaceTrackerListener;

struct RTIOsapiInterfaceTracker;

/** @internal \ingroup RTIOsapiSocketClass
 * \brief This callback function receives notifications on interface changes.   .
 */
typedef void (*RTIOsapiInterfaceTracker_OnInterfaceChangeCallback)(
        void *listenerData,
        struct RTIOsapiInterfaceTracker *interfaceTracker,
        const struct RTIOsapiInterfaceTrackerEvent *trackerEvent);


#define RTI_OSAPI_INTERFACE_TRACKER_EVENT_INITIALIZER \
  { \
    0, NULL \
  }
#define RTI_OSAPI_INTERFACE_TRACKER_PROPERTY_DEFAULT \
  { \
    RTI_OSAPI_SOCKET_AF_INET, /* autoIdKind */ \
    RTI_OSAPI_INTERFACE_TRACKER_DETECTION_KIND_AUTO, /* detectionKind */ \
    0,  /* interfaceMask */ \
    0,  /* interfacePollPeriod */ \
    "", /* threadName */ \
  }
#define RTI_OSAPI_INTERFACE_TRACKER_LISTENER_INITIALIZER \
  { \
    NULL, NULL \
  }

/** @internal \ingroup RTIOsapiSocketClass
  \brief This  struct is passed to the interface tracker in order to initialize
 * the tracker. One of the members is a pointer to the callback function used
 * for interface change notifications.
 */
struct RTIOsapiInterfaceTrackerListener {
    void *listenerData;
    RTIOsapiInterfaceTracker_OnInterfaceChangeCallback onInterfaceChange;
};

extern RTIOsapiDllExport struct RTIOsapiInterfaceTracker *
RTIOsapiInterfaceTracker_new(
        const struct RTIOsapiInterfaceTrackerListener *listener,
        const struct RTIOsapiInterfaceTrackerProperty *property);

extern RTIOsapiDllExport void RTIOsapiInterfaceTracker_delete(
        struct RTIOsapiInterfaceTracker *self);

/** @internal \ingroup RTIOsapiSocketClass
 * \brief This function can be called to get a loan of the (up to date)
 * interfaceArray data. the interfaceArray is owned and maintained by the
 * interface tracker. The pointer retrieved should not be retained and it does
 * not need to be deleted. A call to
 * RTIOsapiInterfaceTracker_returnInterfaceArrayLoan is necessary to indicate
 * the interfaceArray data is no longer needed. No interface updates
 * will be received until returnInterfaceArrayLoan is called. The
 * interfaceTracker may get blocked on the delete method if
 * returnInterfaceArrayLoan is not called.
 *
 * @return true on success
 */
extern RTIOsapiDllExport RTIBool RTIOsapiInterfaceTracker_loanInterfaceArray(
        struct RTIOsapiInterfaceTracker *self,
        struct RTIOsapiSocket_InterfaceDescription **interfaceArray,
        int *interfaceCount);

/** @internal \ingroup RTIOsapiSocketClass
 * \brief This function complements the interface data retrieval made by using
 * RTIOsapiInterfaceTracker_loanInterfaceArray, and should always be called
 * each time RTIOsapiInterfaceTracker_loanInterfaceArray is called.
 *
 * A call to RTIOsapiInterfaceTracker_returnInterfaceArrayLoan is necessary to
 * indicate the interfaceArray data is no longer needed. Once loanInterfaceArray
 * is called no interface updates will be received until
 * returnInterfaceArrayLoan is invoked. The interfaceTracker may get blocked on
 * the delete method if a loanInterfaceArray is issued without a corresponding
 * returnInterfaceArrayLoan call.
 */
extern RTIOsapiDllExport void RTIOsapiInterfaceTracker_returnInterfaceArrayLoan(
        struct RTIOsapiInterfaceTracker *self);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* osapi_interfaceTracker_h */