/* Copyright (C) 2014 by Bundesamt für Sicherheit in der Informationstechnik
 * Software engineering by Intevation GmbH
 *
 * This file is Free Software under the GNU GPL (v>=2)
 * and comes with ABSOLUTELY NO WARRANTY!
 * See LICENSE.txt for details.
 */
#ifndef PORTPATH_H
#define PORTPATH_H

#include <stdbool.h>
#include <stdio.h>

/**
 * @file  portpath.h
 * @brief Platform independent functions for file and path handling.
 * @details portpath contains functions to handle file and path names
 * in a platform independent way.  The code unsing this functions
 * should be protable between GNU/Linux and Windows32 systems.
 */

/**
 * @brief portable version of dirname
 * @details return the directory component of the given path.
 * The argument path may be altered by the function.
 * @param[inout] path the pathname
 * @returns a pointer to the string containing the directory component
 */
char *port_dirname(char *path);

/**
 * @brief portable version of realpath
 * @details return the expanded absolute pathname for the given path.
 * The buffer for the resolved path is allocated by this function and
 * should be freed by the caller.
 * @param[in] path the original pathname
 * @returns a pointer to the resolved path or NULL on error
 */
char *port_realpath(const char *path);

/**
 * @brief test if a file exists
 * @details uses a platform specific stat call to test if the given
 * file exists.
 * @param[in] path the path to the file
 * @returns true if the file exists and false otherwise
 */
bool port_fileexits(char *path);

/**
 * @brief test if a file is a directory
 * @details uses a platform specific stat call to test if the given
 * file is an directory.
 * @param[in] path the path to the file
 * @returns true if the file is an directory and false otherwise
 */
bool port_isdir(const char *path);

/**
 * @brief create a directory
 * @details uses a platform specific mkdir / access rights setup
 * to create a directory that is world readable and
 * writable by the current user / group
 * @param[in] path the path to the directory
 * @param[in] propagate_acl weather or not objects should inherit
 * the ACL of this directory. Only has an effect on Windows.
 * @returns true if the directory was created
 */
bool port_mkdir(const char *path, bool propagate_acl);

/**
 * @brief create a directory and its parent directores
 *
 * On Windows the last directory will propagate it's ACL
 * to objects and subdirectories. The parent directories
 * will not.
 *
 * @param[in] propagate_acl weather or not the
 * last created directory should propagate it's acl.
 * Only has an effect on Windows.
 * @param[in] path the path to the directory
 * @returns true if the directory was created
 */
bool port_mkdir_p(const char *path, bool propagate_acl);

/**
 * @brief Open a file in read binary mode
 *
 * @param[in] path UTF-8 (or local 8 bit encoding)
 *                 encoded filename
 * @param[in] exclusive weather or not to open the file with
 *            a denywr lock. Ignored under linux.
 * @returns the same as fopen.
 */
FILE* port_fopen_rb(const char *path, bool exclusive);

#endif