/*
 * (c) Copyright, Real-Time Innovations, 2022-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_fileTracker_h
#define osapi_fileTracker_h

#include "log/log_makeheader.h"

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

#ifdef __cplusplus
extern "C" {
#endif

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Type describing what kind of event the File Tracker observed for a
 * tracked file.
 */
typedef enum {
    /* File Tracker has not observed any relevant event for the file. */
    RTI_OSAPI_FILE_TRACKER_EVENT_KIND_FILE_NONE,
    /*
     * File Tracker has detected the file has transitioned from existing
     * to not existing (i.e., the file has been deleted).
     */
    RTI_OSAPI_FILE_TRACKER_EVENT_KIND_FILE_DELETED,
    /*
     * File Tracker has detected the file has transitioned from not existing
     * to existing. This will happen either if an already tracked non-existing
     * file has been created, but also when the File Tracker first starts
     * tracking a file that already exists.
     */
    RTI_OSAPI_FILE_TRACKER_EVENT_KIND_FILE_NEW,
    /*
     * File Tracker has detected the file has changed in any way (except
     * being deleted or new, which is covered by other event kinds).
     */
    RTI_OSAPI_FILE_TRACKER_EVENT_KIND_FILE_CHANGED
} RTIOsapiFileTrackerEventKind;

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief A struct passed to the File Tracker callback function describing
 * a single file change.
 */
struct RTIOsapiFileTrackerEvent {
    RTIOsapiFileTrackerEventKind kind;
    const char *fileName;
};


#define RTIOsapiFileTrackerEvent_INITIALIZER \
  { \
    RTI_OSAPI_FILE_TRACKER_EVENT_KIND_FILE_NONE, /* kind */ \
    NULL                                         /* fileName */ \
  }

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Describes how the File Tracker will track files.
 */
typedef enum {
    /*
     * Default behavior, the tracker will rely on asynchronous OS notification
     * if supported, and polling if not.
     */
    RTI_OSAPI_FILE_TRACKER_DETECTION_KIND_AUTO,
    /* Polls tracked files periodically to track their status. */
    RTI_OSAPI_FILE_TRACKER_DETECTION_KIND_POLLING,
    /* Relies on asynchronous OS notifications to track files' status. */
    RTI_OSAPI_FILE_TRACKER_DETECTION_KIND_OS_NOTIFICATION
} RTIOsapiFileTrackerDetectionKind;

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Class in charge of detecting file changes and notifying the
 * changes by means of a listener.
 */
struct RTIOsapiFileTracker;

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief This callback function receives notifications upon file status
 * changes.
 */
typedef void (*RTIOsapiFileTracker_OnFileChangeCallback)(
        void *listenerData,
        const struct RTIOsapiFileTrackerEvent *fileTrackerEvent);

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Listener for file status changes. One of the members is a pointer to
 * the callback function used for file change notifications.
 */
struct RTIOsapiFileTrackerListener {
    void *listenerData;
    RTIOsapiFileTracker_OnFileChangeCallback onFileChange;
};

#define RTIOsapiFileTrackerListener_INITIALIZER \
  { \
    NULL, /* listenerData */ \
    NULL  /* onFileChange */ \
  }

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief A property used to configure the File Tracker.
 */
struct RTIOsapiFileTrackerProperty {
    /*
     * Determines how the File Tracker will track files.
     */
    RTIOsapiFileTrackerDetectionKind detectionKind;
    /*
     * Poll period in milliseconds to check for file status changes. Only used
     * if detectionKind is either POLLING or AUTO.
     */
    RTI_UINT32 pollPeriodMillisec;
    /* Name of the thread managing File Tracker events. */
    char threadName[RTI_OSAPI_THREAD_NAME_MAX_SIZE];
};


#define RTIOsapiFileTrackerProperty_INITIALIZER \
  { \
    RTI_OSAPI_FILE_TRACKER_DETECTION_KIND_AUTO, /* detectionKind */ \
    500,                                        /* pollPeriodMillisec */ \
    ""                                          /* threadName */ \
  }

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Creates a File Tracker based on the passed listener and property.
 *
 * @param property Configuration for the File Tracker.
 *
 * @return A File Tracker object.
 *
 */
extern RTIOsapiDllExport struct RTIOsapiFileTracker *RTIOsapiFileTracker_new(
        const struct RTIOsapiFileTrackerProperty *property);

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Destroys a File Tracker object.
 *
 * @param self File Tracker to destroy.
 */
extern RTIOsapiDllExport void RTIOsapiFileTracker_delete(
        struct RTIOsapiFileTracker *self);

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Starts tracking a file on behalf the passed listener.
 *
 * @param self File Tracker.
 * @param listener Listener to invoke upon file status changes.
 * @param fileName Name of the file to start tracking.
 *
 * @return RTI_TRUE on success, RTI_FALSE on failure. One reason for failure is
 * if the listener is already tracking the file.
 */
extern RTIOsapiDllExport RTIBool RTIOsapiFileTracker_startTrackingFile(
        struct RTIOsapiFileTracker *self,
        const struct RTIOsapiFileTrackerListener *listener,
        const char *fileName);

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Stops tracking a file on behalf the passed listener.
 *
 * @param self File Tracker.
 * @param listener Listener to invoke upon file status changes.
 * @param fileName Name of the file to start tracking.
 *
 * @return RTI_TRUE on success, RTI_FALSE on failure.
 */
extern RTIOsapiDllExport RTIBool RTIOsapiFileTracker_stopTrackingFile(
        struct RTIOsapiFileTracker *self,
        const struct RTIOsapiFileTrackerListener *listener,
        const char *fileName);

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Stops tracking all files associated with given listener.
 *
 * @param self File Tracker.
 * @param listener Listener that we want to stop.
 *
 * @return RTI_TRUE on success, RTI_FALSE on failure.
 */
extern RTIOsapiDllExport
RTIBool RTIOsapiFileTracker_stopTrackingAllFilesPerListener(
        struct RTIOsapiFileTracker *self,
        const struct RTIOsapiFileTrackerListener *listener);

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * \brief Stops tracking all files.
 *
 * @param self File Tracker.
 *
 * @return RTI_TRUE on success, RTI_FALSE on failure.
 */
extern RTIOsapiDllExport
RTIBool RTIOsapiFileTracker_stopTrackingAllFiles(
        struct RTIOsapiFileTracker *self);

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

#endif /* osapi_fileTracker_h */