qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/ndds/netio/netio_dnsTracker.h

/*
 * Copyright (c) 2024 Real-Time Innovations, Inc. 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 netio_dnsTracker_h
#define netio_dnsTracker_h

#ifndef rti_makeheader_h
  #include "log/log_makeheader.h"
#endif
#ifndef osapi_thread_h
  #include "osapi/osapi_thread.h"
#endif
#ifndef osapi_semaphore_h
  #include "osapi/osapi_semaphore.h"
#endif
#ifndef reda_worker_h
  #include "reda/reda_worker.h"
#endif
#ifndef transport_common_user_h
  #include "transport/transport_common_user.h"
#endif
#include "netio/netio_dll.h"
#include "netio/netio_common.h"
#include "netio/netio_configurator.h"

#ifdef __cplusplus
    extern "C" {
#endif

/*e \defgroup RTINetioDnsTrackerType RTINetioDnsTracker
 * \ingroup RTINetioConfiguratorComponent
 *
 * @brief A DNS tracker is an entity that maintains a list of hostnames with
 * their corresponding IP addresses. The DNS tracker resolves those IP addresses
 * using DNS calls. This entity creates a thread that polls periodically the
 * name resolution. If the DNS tracker detects a change, calls a listener
 * function.
 */

/* The maximum number of elements that the listener storage can hold. */
#define RTI_NETIO_DNS_TRACKER_LISTENER_STORAGE_DATA_MAX_SIZE 8

/*e @ingroup RTINetioDnsTrackerType
 * @brief This struct can be used to provide parameters to the
 * listener callbacks.
 */
struct RTINetioDnsTrackerListenerStorage {
    void *field[RTI_NETIO_DNS_TRACKER_LISTENER_STORAGE_DATA_MAX_SIZE];
};

#define RTI_NETIO_DNS_TRACKER_LISTENER_STORAGE_DEFAULT \
        {{NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}}

struct RTINetioDnsTrackerListener;

/*e @ingroup RTINetioDnsTrackerType
 * @brief Listener callback that is called when a change is detected
 *
 * @param listener The listener call
 * @param storage The storage provided
 * @param locator The locator that has changed
 * @param newAddress The new address for the locator
 */
typedef RTIBool (*RTINetio_onHostnameUpdated_Fcn)(
        struct RTINetioDnsTrackerListener *listener,
        struct RTINetioDnsTrackerListenerStorage *storage,
        const struct RTINetioLocator *locator,
        const NDDS_Transport_Address_t *newAddress,
        struct REDAWorker *worker);

/*e @ingroup RTINetioDnsTrackerType
 * @brief The listener that the DNS tracker calls upon a change in the hostname
 * resolution.
 */
struct RTINetioDnsTrackerListener {
    RTINetio_onHostnameUpdated_Fcn onHostnameUpdated;
};

#define RTI_NETIO_DNS_TRACKER_LISTENER_DEFAULT \
        {NULL}

/*e @ingroup RTINetioDnsTrackerType
 * @brief A DNS tracker object. This object monitors hostnames and their
 * corresponding IP addresses. It calls the onHostnameUpdated callback
 * every time that a tracked hostname changes its resolved IP address.
 */
struct RTINetioDnsTracker;

/*e @ingroup RTINetioDnsTrackerType
 * @brief The properties struct for the RTINetioDnsTracker.
 */
struct RTINetioDnsTrackerProperty {
    /*
     * The period used to poll the DNS looking for updates. If set to infinite
     * the DNS tracker stops updating and therefore removing destinations from
     * its list.
     */
    struct RTINtpTime period;
};


#define RTI_NETIO_DNS_TRACKER_PROPERTY_DEFAULT {\
    RTI_NTP_TIME_MAX /* period */ \
}

/*e @ingroup RTINetioDnsTrackerType
 * @brief Creates an RTINetioDnsTracker
 *
 * @param configurator: it keeps the information regarding the transports
 * installed.
 * @param threadName: name used to identify the thread.
 * @param property: properties of the RTINetioDnsTracker.
 * @param listener: callbacks used by the RTINetioDnsTracker.
 * @param storage: information to provide the callbacks.
 * @param ea: exclusive area that protects the RTINetioDnsTracker and its list.
 * @param workerFactory: used to create a worker for the thread.
 */
extern RTINetioDllExport struct RTINetioDnsTracker *
RTINetioDnsTracker_new(
        const struct RTINetioConfigurator *configurator,
        const char *threadName,
        const struct RTINetioDnsTrackerProperty *property,
        const struct RTINetioDnsTrackerListener *listener,
        const struct RTINetioDnsTrackerListenerStorage *storage,
        struct REDAExclusiveArea *ea,
        struct REDAWorkerFactory *workerFactory);

/*e @ingroup RTINetioDnsTrackerType
 * @brief Destroys an RTINetioDnsTracker
 */
extern RTINetioDllExport void
RTINetioDnsTracker_delete(struct RTINetioDnsTracker *me);

/*e @ingroup RTINetioDnsTrackerType
 * @brief Asserts a new destination into the tracker. Increasing the refcount of
 * the destination if it already existed.
 *
 * @param destination: the destination to be added.
 */
extern RTINetioDllExport RTIBool
RTINetioDnsTracker_assertDestination(
        struct RTINetioDnsTracker * me,
        const struct RTINetioLocator *destination,
        struct REDAWorker *worker);

/*e @ingroup RTINetioDnsTrackerType
 * @brief Decreases the refcount of a destination in the tracker, setting it
 * for removal when it reaches a refcount of 0. This API does not actually
 * remove the destination from the list. The thread will check if a destination
 * needs to be removed and will remove it during the next iteration.
 *
 * @param destination: the destination to be removed.
 */
extern RTINetioDllExport void
RTINetioDnsTracker_removeDestination(
        struct RTINetioDnsTracker * me,
        const struct RTINetioLocator *destination,
        struct REDAWorker *worker);

/*e @ingroup RTINetioDnsTrackerType
 * @brief Sets the property of a tracker in while it is running. Calling to this
 * function also triggers a DNS resolution for the stored hostnames.
 *
 * @param newProperty: the new values for the properties
 */
extern RTINetioDllExport RTIBool
RTINetioDnsTracker_setProperty(
        struct RTINetioDnsTracker *me,
        const struct RTINetioDnsTrackerProperty *newProperty,
        struct REDAWorker *worker);

/*e @ingroup RTINetioDnsTrackerType
 * @brief Gets the property of a tracker in while it is running.
 *
 * @param property: returns the value of the property.
 */
extern RTINetioDllExport RTIBool
RTINetioDnsTracker_getProperty(
        struct RTINetioDnsTracker *me,
        struct RTINetioDnsTrackerProperty *property,
        struct REDAWorker *worker);

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

#endif /* netio_dnsTracker_h */