/*
 * Copyright 2010 Vincent Sanders <vince@kyllikki.org>
 *
 * This file is part of NetSurf, http://www.netsurf-browser.org/
 *
 * NetSurf is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; version 2 of the License.
 *
 * NetSurf is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/**
 * @file utils/filepath.h
 * @brief Utility routines to obtain paths to file resources.
 */

#ifndef _NETSURF_UTILS_FILEPATH_H_
#define _NETSURF_UTILS_FILEPATH_H_

#include <stdarg.h>

#include "utils/errors.h"

/**
 * Create a normalised file name.
 *
 * If the file described by the format exists and is accessible the
 * normalised path is placed in str and a pointer to str returned
 * otherwise NULL is returned. The string in str is always modified.
 *
 * @param str A buffer to contain the normalised file name must be at
 *            least PATH_MAX bytes long.
 * @param format A printf format for the filename.
 * @param ap The list of arguments for the format.
 * @return A pointer to the expanded filename or NULL if the file is
 *         not present or accessible.
 */
char *filepath_vsfindfile(char *str, const char *format, va_list ap);


/**
 * Create a normalised file name.
 *
 * Similar to vsfindfile but takes variadic (printf like) parameters
 */
char *filepath_sfindfile(char *str, const char *format, ...);


/**
 * Create a normalised file name.
 *
 * Similar to sfindfile but allocates its own storage for the
 * returned string. The caller must free this sorage.
 */
char *filepath_findfile(const char *format, ...);


/**
 * Searches an array of resource paths for a file.
 *
 * Iterates through a vector of resource paths and returns the
 * normalised file name of the first acessible file or NULL if no file
 * can be found in any of the resource paths.
 *
 * \param respathv The resource path vector to iterate.
 * \param filepath The buffer to place the result in.
 * \param filename The filename of the resource to search for.
 * \return A pointer to filepath if a target is found or NULL if not.
 */
char *filepath_sfind(char **respathv, char *filepath, const char *filename);


/**
 * Searches an array of resource paths for a file.
 *
 * Similar to filepath_sfind except it allocates its own storage for
 * the returned string. The caller must free this sorage.
 */
char *filepath_find(char **respathv, const char *filename);


/**
 * Searches an array of resource paths for a file optionally forcing a default.
 *
 * Similar to filepath_sfind except if no resource is found the default
 * is used as an additional path element to search, if that still
 * fails the returned path is set to the concatination of the default
 * path and the filename.
 *
 * \param respathv The resource path vector to iterate.
 * \param filepath The buffer to place the result in. Must have space for PATH_MAX bytes.
 * \param filename The filename of the resource to search for.
 * \param def The default path to use
 * \return A pointer to filepath if a target is found or the default if not
 */
char *filepath_sfinddef(char **respathv, char *filepath, const char *filename,
		const char *def);


/**
 * Merge two string vectors into a resource search path vector.
 *
 * @param pathv A string vector containing path elemets to scan.
 * @param langv A string vector containing language names to enumerate.
 * @return A pointer to a NULL terminated string vector of valid
 *         resource directories.
 */
char **filepath_generate(char * const *pathv, const char * const *langv);


/**
 * Convert a colon separated list of path elements into a string vector. 
 *
 * @param path A colon separated path.
 * @return A pointer to a NULL terminated string vector of valid
 *         resource directories.
 */
char **filepath_path_to_strvec(const char *path);


/**
 * Free a string vector.
 *
 * Free a string vector allocated by filepath_path_to_strvec
 */
void filepath_free_strvec(char **pathv);



#endif /* _NETSURF_UTILS_FILEPATH_H_ */