/*
 * (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_file_h
#define osapi_file_h


#include <errno.h>
#include "osapi/osapi_type.h"
#include "osapi/osapi_dll.h"
#include "osapi/osapi_vxVersions.h"
#include "osapi/osapi_ntptime.h"
#include <stdio.h>
#include <stdarg.h>

#if defined(RTI_UNIX)
#include <unistd.h>
#endif

#ifdef RTI_WIN32
  #include <io.h>
#endif

#ifdef __cplusplus
extern "C" {
#endif

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Closes a file.
 *
 * This API shall only be called upon a file descriptor that is open.
 *
 * @param f file descriptor to close.
 *
 * @return 0 on success, EOF on failure.
 */
extern RTIOsapiDllExport int RTIOsapiFile_close(FILE *f);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Opens a file
 *
 * @param fileName the name of the file to open.
 * @param mode the mode to use to open the file. See the online documentation
 * for fopen for a description of the possible modes.
 *
 * @return a pointer to the opened file on success, NULL on failure.
 * Opening a file with read mode (r as the first character in the mode argument)
 * shall fail if the file does not exist or cannot be read.
 */
extern RTIOsapiDllExport FILE *RTIOsapiFile_open(
        const char *fileName,
        const char *mode);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Read a character.
 *
 * This API gets the next character from the specified stream and advances the
 * position indicator for the stream.
 *
 * @param f file descriptor on which the operation is to be performed.
 *
 * @return This function returns an unsigned char cast to an int, or EOF
 * on end of file or error.
 */
extern RTIOsapiDllExport int RTIOsapiFile_getc(FILE *f);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Write a character.
 *
 * This API writes a character (an unsigned char) specified by the argument res
 * to the specified stream and advances the position indicator for the stream.
 *
 * @param f file descriptor that identifies the stream where the character is
 * to be written.
 * @param res This is the character to be written. The character is passed as
 * an unsigned char cast to an int.
 *
 * @return This function returns the character written as an unsigned char cast
 * to an int or EOF on error.
 */
extern RTIOsapiDllExport int RTIOsapiFile_putc(FILE *f, int res);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Write a string to a file.
 *
 * This API writes the string pointed to by str to the specified stream.
 *
 * @param f file descriptor that identifies the stream where the string
 * is to be written.
 * @param str This is the string to be written. The string is expected to
 * be null-terminated.
 *
 * @return On success, a non-negative value is returned. On error, the function
 * returns EOF.
 */
extern RTIOsapiDllExport int RTIOsapiFile_puts(FILE *f, const char *str);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Copy a file.
 *
 * This API copy a file to a new one. If the destination file already exist its
 * content will be erased.
 *
 * @param dstFileName The path to the destination file.
 * @param srcFileName The path to the file we want to copy.
 *
 * @return This function returns RTI_TRUE on success, RTI_FALSE otherwise.
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiFile_copy(const char *dstFileName, const char *srcFileName);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Check if the content of two files is equal.
 *
 * This API ignores differences between line endings on Windows and Linux (i.e.,
 * we ignore the difference between \r\n and \n).
 *
 * @param fileX file to compare
 * @param fileY file to compare
 *
 * @return RTI_TRUE if the two files have equal contents,
 * RTI_FALSE on failure preventing checking for equality, or if the two files
 * have different contents.
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiFile_equals(const char *fileX, const char *fileY);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Check if a file exists
 *
 * @param fileName name of the file to check for existence.
 *
 * @return RTI_TRUE if the file exists, RTI_FALSE on failure or if it does not
 * exist.
 */
extern RTIOsapiDllExport RTIBool RTIOsapiFile_exists(const char *fileName);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Removes a file
 *
 * @param fileName name of the file to remove.
 *
 * @return RTI_TRUE if the file exists, RTI_FALSE if it does not exist.
 */
extern RTIOsapiDllExport RTIBool RTIOsapiFile_remove(const char *fileName);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Search a string in the content of a file.
 *
 * @param f. File stream to find matches.
 * @param str. String to compare with the file content.
 *
 * @return RTI_TRUE if string appears in the file, RTI_FALSE otherwise.
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiFile_searchString(FILE *f, const char *str);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Count the number of occurrences of a string in the content of a file.
 *
 * @param f. File stream to find matches.
 * @param str. String to compare with the file content.
 *
 * @return The number of occurrences of the string in the file. If the string
 * does not appear in the file, the function returns 0.
 */
extern RTIOsapiDllExport RTI_UINT32
RTIOsapiFile_countStringOccurrences(FILE *f, const char *str);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Create a temporary directory.
 *
 * The directory will be created on the system's temporary directory folder, as
 * a subfolder built using a prefix, an optional suffix and with the possibility
 * to append the current timestamp at the time of the call.
 * So, for example, on Windows it will result in a directory called:
 *     %TEMP%\<prefix>_<process ID or timestamp>_<suffix>\
 *
 * If the `create` flag is RTI_TRUE but the directory already exists, this
 * function will return RTI_TRUE anyway.
 *
 * @param outDir. Output string where the path of the new temporary directory
 *                will be stored.
 * @param outDirSize The size of the outDir string. The resulting path should
 *                fit in this string, otherwise an error will be returned.
 * @param prefix. The prefix to prepend to the name of the subfolder to create.
 *                Required.
 * @param suffix. Optional. The suffix to append at the end of the subfolder
 *                name.
 * @param useProcessId. The new subfolder will contain the current process ID;
 *                if this is false, the subfolder will contain the timestamp at
 *                the moment of the call to this function after the prefix.
 * @param create. If RTI_TRUE, the function will attempt to create the
 *                directory. If RTI_FALSE, the function will only return the
 *                expected path.
 *
 * @return RTI_TRUE if the temporary path was calculated correctly and
 * if instructed to, if the directory was created successfully or if it
 * already existed. Otherwise it returns RTI_FALSE.
 */
extern RTIOsapiDllExport
RTIBool RTIOsapiFile_createOrGetTempDirectory(
        char *outDir,
        const size_t outDirSize,
        const char *prefix,
        const char *suffix,
        RTIBool useProcessId,
        RTIBool create);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Check if a directory exists.
 *
 * This API checks if a directory with the specified name exists in the specified
 * path.
 *
 * @param path The directory to check.
 * @return RTI_TRUE if the directory exists, RTI_FALSE otherwise.
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiFile_directoryExists(const char *path);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Create a directory.
 *
 * This API creates a new directory with the specified name in the specified
 * path.
 *
 * @param path The directory to create.
 * @param createParents If RTI_TRUE, the function will create all parent
 * directories that do not exist.
 *
 * @return RTI_TRUE if the directory was created successfully or if it
 * already exists, RTI_FALSE otherwise.
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiFile_createDirectory(const char *path, RTIBool createParents);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 * @brief Removes a file or directory at the specified path.
 *
 * This function removes the file or directory located at the given path. On
 * Windows, if the path is a directory and is not empty, the contents are
 * deleted and then the directory is removed.
 *
 * @param path The path of the file or directory to be removed. Cannot be null.

 * @return Returns RTI_TRUE if the file or directory was successfully removed,
 *         RTI_FALSE otherwise.
 */
extern RTIOsapiDllExport
RTIBool RTIOsapiFile_removeFileOrDirectory(const char *path);

#if defined(RTI_LINUX) || defined(RTI_DARWIN) || defined(RTI_AIX) \
        || defined(RTI_WIN32)
  #define RTI_SUPPORT_HIGH_RESOLUTION_FILE_TIMESTAMPS
#endif

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * @brief Retrieves the timestamps (with a resolution of seconds, or higher
 * if RTI_SUPPORT_HIGH_RESOLUTION_FILE_TIMESTAMPS is defined for the arch.)
 * for the following file events: last access, last modification,
 * and last status change.
 *
 * @param fileName name of the file to get the timestamps for.
 * @param accessTs Timestamp for the last access to the file. Can be NULL if
 * the caller is not interested in retrieving this timestamp.
 * @param modificationTs Timestamp for the last modification of the file.
 * @param statusChangeTs Timestamp for the last status change of the file.
 * The nature of the status triggering a change in this timestamp is OS
 * dependent. For non-Windows architectures, this one is updated upon writing or
 * by setting inode information (i.e., owner, group, link count, mode, etc.);
 * for windows architectures, this one is updated upon creating the file.
 *
 * @return RTI_TRUE if able to retrieve the timestamps for the file, RTI_FALSE
 * otherwise.
 */
extern RTIOsapiDllExport RTIBool RTIOsapiFile_getTimestamps(
        const char *fileName,
        struct RTINtpTime *accessTs,
        struct RTINtpTime *modificationTs,
        struct RTINtpTime *statusChangeTs);

/** @internal
 * \ingroup RTIOsapiUtilityClass
 * @brief Gets a line (terminated with '\n' character) from a file.
 *
 * @note: This function discards '\r' characters.
 *
 * @pre The stream has to be opened as a binary file:
 *      inStream = fopen("myfile", "rb");
 * @pre sizeMax value must be > 1.
 *
 * @param[inout] outLine A pointer to the buffer that will store the line. The
 * buffer must be preallocated.
 * @param[in] sizeMax The maximum number of characters that can be written to
 * outLine. If the limit is reached but the function has not encountered '\n',
 * the function will return successfully but the buffer will not contain the
 * full line as it is in the file.
 * @param[in] inStream The FILE structure that the function reads from.
 *
 * @return The pointer to the buffer (outLine) upon success, or NULL on failure.
 */
extern RTIOsapiDllExport char *RTIOsapiFile_getline(
        char *outLine,
        size_t sizeMax,
        FILE *inStream);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 *
 * @brief Read the contents of the text file passed as an argument into a
 * dynamically-allocated string.
 *
 * @param filePath[in] The path to the file to read.
 *
 * @return A pointer to the dynamically-allocated string containing the
 * contents of the file, or null if there was an error while reading the
 * contents from the file. The caller is responsible for calling
 * RTIOsapiHeap_freeString when the string is not needed any more.
 * If the file is empty, a pointer to an empty string is returned.
 */
extern RTIOsapiDllExport char *RTIOsapiFile_readFile(const char *filePath);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 *
 * @brief Read the contents of the binary file passed as an argument into a
 * dynamically-allocated buffer.
 *
 * @param filePath[in] The path to the file to read.
 * @param outBufferSize[out] The size of the buffer allocated to hold the
 * contents of the file. Cannot be NULL.
 *
 * @return A pointer to the dynamically-allocated buffer containing the
 * contents of the file, or null if there was an error while reading the
 * contents from the file or when the file is empty. The caller is responsible
 * for calling RTIOsapiHeap_freeBuffer when the buffer is not needed any more.
 */
extern RTIOsapiDllExport char *RTIOsapiFile_readBinaryFile(
        const char *filePath,
        size_t *outBufferSize);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 *
 * @brief Write the contents of a string to a text file.
 *
 * This function creates or overwrites the file specified by filePath with the
 * contents of the null-terminated string.
 *
 * @param filePath[in] The path to the file to write.
 * @param content[in] The null-terminated string to write to the file. Cannot be
 * NULL.
 *
 * @return RTI_TRUE if the file was written successfully, RTI_FALSE if there was
 * an error while writing to the file.
 */
extern RTIOsapiDllExport RTIBool
RTIOsapiFile_writeFile(const char *filePath, const char *content);

/** @internal
 * @ingroup RTIOsapiUtilityClass
 *
 * @brief Write the contents of a buffer to a binary file.
 *
 * This function creates or overwrites the file specified by filePath with the
 * contents of the buffer.
 *
 * @param filePath[in] The path to the file to write.
 * @param content[in] The buffer containing the data to write to the file.
 * Cannot be NULL.
 * @param contentSize[in] The size in bytes of the buffer to write.
 *
 * @return RTI_TRUE if the file was written successfully, RTI_FALSE if there was
 * an error while writing to the file.
 */
extern RTIOsapiDllExport RTIBool RTIOsapiFile_writeBinaryFile(
        const char *filePath,
        const char *content,
        size_t contentSize);

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

#endif /* osapi_file_h */