/* WARNING: This file was generated by dkct. Changes you make here will be lost if dkct is run again! You should modify the original source and run dkct on it. Original source: dk4fs.ctr */ /* Copyright (C) 2015-2017, Dirk Krause Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above opyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the author nor the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #ifndef DK4FS_H_INCLUDED /** Avoid multiple inclusions. */ #define DK4FS_H_INCLUDED 1 #line 9 "dk4fs.ctr" /** @file File search for configuration and data files. Specify short file name and a number of directories: - shared data directory (i.e. /usr/share) or system configuration directory (i.e. /etc), - users home directory, - program name, - program group name, - language, - region Use dk4fs_config_one() or dk4fs_data_one() multiple times to find the file best matching program name, group name, language and region. See below. CRT on Windows: Optional. */ #ifndef DK4CONF_H_INCLUDED #include "dk4conf.h" #endif #ifndef DK4TYPES_H_INCLUDED #include "dk4types.h" #endif #ifndef DK4ERROR_H_INCLUDED #include "dk4error.h" #endif /** Pass numbers for configuration file search. The group name passed as name_group is used instead of group, the program name passed as name_prog is used instead of prog. */ enum { DK4_FS_CONF_SHARE_LIB = 0, /**< /usr/share/dk4app */ DK4_FS_CONF_ETC_LIB , /**< /etc/dk4app */ DK4_FS_CONF_SHARE_LIB_SITE , /**< /usr/share/dk4app-site */ DK4_FS_CONF_ETC_LIB_SITE , /**< /etc/dk4app-site */ DK4_FS_CONF_SHARE_GROUP , /**< /usr/share/group */ DK4_FS_CONF_ETC_GROUP , /**< /etc/group */ DK4_FS_CONF_SHARE_GROUP_SITE , /**< /usr/share/group-site */ DK4_FS_CONF_ETC_GROUP_SITE , /**< /etc/group-site */ DK4_FS_CONF_SHARE_APP , /**< /usr/share/prog */ DK4_FS_CONF_ETC_APP , /**< /etc/prog */ DK4_FS_CONF_SHARE_APP_SITE , /**< /usr/share/prog-site */ DK4_FS_CONF_ETC_APP_SITE , /**< /etc/prog-site */ DK4_FS_CONF_HOME_LIB , /**< HOME/.dk4app */ DK4_FS_CONF_HOME_GROUP , /**< HOME/.dk4app/group */ DK4_FS_CONF_HOME_APP , /**< HOME/.dk4app/prog */ DK4_FS_CONF_CURRENT_DIR , /**< Current directory */ /** Maximum value. */ DK4_FS_CONF_MAX = DK4_FS_CONF_CURRENT_DIR , /** Maximum value to search system directories only. */ DK4_FS_CONF_SYS_MAX = DK4_FS_CONF_ETC_APP_SITE }; /** Pass numbers for data file search. The group name passed as name_group is used instead of group, the program name passed as name_prog is used instead of prog. */ enum { DK4_FS_DATA_SHARE_LIB = 0, /**< /usr/share/dk4app */ DK4_FS_DATA_SHARE_LIB_SITE , /**< /usr/share/dk4app-site */ DK4_FS_DATA_SHARE_GROUP , /**< /usr/share/group */ DK4_FS_DATA_SHARE_GROUP_SITE , /**< /usr/share/group-site */ DK4_FS_DATA_SHARE_APP , /**< /usr/share/prog */ DK4_FS_DATA_SHARE_APP_SITE , /**< /usr/share/prog-site */ DK4_FS_DATA_SHARE_LIB_LANG , /**< /usr/share/dk4app/l */ DK4_FS_DATA_SHARE_LIB_SITE_LANG , /**< /usr/share/dk4app-site/l */ DK4_FS_DATA_SHARE_GROUP_LANG , /**< /usr/share/group/l */ DK4_FS_DATA_SHARE_GROUP_SITE_LANG , /**< /usr/share/group-site/l */ DK4_FS_DATA_SHARE_APP_LANG , /**< /usr/share/prog/l */ DK4_FS_DATA_SHARE_APP_SITE_LANG , /**< /usr/share/prog-site/l */ DK4_FS_DATA_SHARE_LIB_REG , /**< /usr/share/dk4app */ DK4_FS_DATA_SHARE_LIB_SITE_REG , /**< /usr/share/dk4app-site */ DK4_FS_DATA_SHARE_GROUP_REG , /**< /usr/share/group */ DK4_FS_DATA_SHARE_GROUP_SITE_REG , /**< /usr/share/group-site */ DK4_FS_DATA_SHARE_APP_REG , /**< /usr/share/prog/no-language/r */ DK4_FS_DATA_SHARE_APP_SITE_REG , /**< /usr/share/prog-site/no-language/r */ DK4_FS_DATA_SHARE_LIB_LANG_REG , /**< /usr/share/dk4app/l/r */ DK4_FS_DATA_SHARE_LIB_SITE_LANG_REG , /**< /usr/share/dk4app-site/l/r */ DK4_FS_DATA_SHARE_GROUP_LANG_REG , /**< /usr/share/group/l/r */ DK4_FS_DATA_SHARE_GROUP_SITE_LANG_REG , /**< /usr/share/group-site/l/r */ DK4_FS_DATA_SHARE_APP_LANG_REG , /**< /usr/share/prog/l/r */ DK4_FS_DATA_SHARE_APP_SITE_LANG_REG , /**< /usr/share/prog-site/l/r */ DK4_FS_DATA_HOME_LIB , /**< HOME/.dk4app */ DK4_FS_DATA_HOME_GROUP , /**< HOME/.dk4app/group */ DK4_FS_DATA_HOME_APP , /**< HOME/.dk4app/prog */ DK4_FS_DATA_CURRENT_DIR , /**< Current directory */ /** Maximum system data file. */ DK4_FS_DATA_MAX_SYS = DK4_FS_DATA_SHARE_APP_SITE_LANG_REG, /** Maximum data file. */ DK4_FS_DATA_MAX = DK4_FS_DATA_CURRENT_DIR }; #ifdef __cplusplus extern "C" { #endif /** Check presence of one file, optionally with compression suffixes. CRT on Windows: Optional. @param dptr Buffer containing file name. @param szdptr Buffer size. @param compressed Flag: Search for compressed files too. @param erp Error report, may be NULL. @return 1 if file or optionally compressed file found, 0 otherwise. Error codes: - DK4_E_INVALID_ARGUMENTS
if dptr is NULL or szdptr is 0, - DK4_E_NOT_SUPPORTED
if wchar_t are used as dkChar on non-Windows systems, - DK4_E_NOT_FOUND
if the file was not found. */ int dk4fs_attempt_file_name( dkChar *dptr, size_t szdptr, int compressed, dk4_er_t *erp ); /** Attempt to construct one file name from multiple parts. CRT on Windows: Optional. @param dptr Destination buffer address. @param szdptr Destination buffer size (number of dkChar). @param comp Components array. @param ncomp Number of components. @param site Flag: Add -site after second component. @param erp Error report, may be NULL. @return 1 on success (path constructed and file exists), 0 otherwise. Error codes: - DK4_E_INVALID_ARGUMENTS
if dptr or comp is NULL or szdptr or ncomp is 0, - DK4_E_BUFFER_TOO_SMALL
if the dptr buffer is too small, - DK4_E_MATH_OVERFLOW
if a mathematical overflow happened during a size calculation. */ int dk4fs_construct_from_parts( dkChar *dptr, size_t szdptr, const dkChar **comp, size_t ncomp, int site, dk4_er_t *erp ); /** Attempt to construct one path name for a configuration file. CRT on Windows: Optional. @param dptr Buffer for result file name. @param szdptr Size of buffer (number of dkChar). @param shortname Short configuration file name. @param dir_share The data directory. @param dir_etc The system configuration directory. @param dir_home Users home directory. @param name_prog Application name. @param name_group Application group name. @param passno Number of current pass. @param co3 Flag: Compatible to DK tools 3. @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if dptr or shortname is NULL or szdptr is 0 or passno is an invalid number or one of the used strings (dir_share, dir_etc, dir_home, name_prog, or name_group) is NULL, - DK4_E_BUFFER_TOO_SMALL
if the dptr buffer is too small, - DK4_E_MATH_OVERFLOW
if a mathematical overflow happened during a size calculation. */ int dk4fs_config_construct_compat_one( dkChar *dptr, size_t szdptr, const dkChar *shortname, const dkChar *dir_share, const dkChar *dir_etc, const dkChar *dir_home, const dkChar *name_prog, const dkChar *name_group, int passno, int co3, dk4_er_t *erp ); /** Attempt to construct one path name for a configuration file. CRT on Windows: Optional. @param dptr Buffer for result file name. @param szdptr Size of buffer (number of dkChar). @param shortname Short configuration file name. @param dir_share The data directory. @param dir_etc The system configuration directory. @param dir_home Users home directory. @param name_prog Application name. @param name_group Application group name. @param passno Number of current pass. @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if dptr or shortname is NULL or szdptr is 0 or passno is an invalid number or one of the used strings (dir_share, dir_etc, dir_home, name_prog, or name_group) is NULL, - DK4_E_BUFFER_TOO_SMALL
if the dptr buffer is too small, - DK4_E_MATH_OVERFLOW
if a mathematical overflow happened during a size calculation. */ int dk4fs_config_construct_one( dkChar *dptr, size_t szdptr, const dkChar *shortname, const dkChar *dir_share, const dkChar *dir_etc, const dkChar *dir_home, const dkChar *name_prog, const dkChar *name_group, int passno, dk4_er_t *erp ); /** Check one path candidate for configuration file name (construct name and check presence of file). To search for a file matching your needs run this function multiple times with differenct passno values. - To search for one file best matching: - Start with pass number DK4_FS_CONF_MAX or DK4_FS_CONF_SYS_MAX and decrease the number down to DK4_FS_CONF_SHARE_LIB, use the first file found. - Start with pass number DK4_FS_CONF_MAX to allow both user and system configuration files. - Start with pass number DK4_FS_CONF_SYS_MAX to process system configuration files only. - To process multiple files, each file may overwrite settings made by previous files: - Start with pass number DK4_FS_CONF_SHARE_LIB (0) and increase the pass number up to DK4_FS_CONF_SYS_MAX or DK4_FS_CONF_MAX. - Stopping after DK4_FS_CONF_SYS_MAX will process system configuration files only, stopping after DK4_FS_CONF_MAX processes both system and user configuration files. CRT on Windows: Optional. @param dptr Buffer for result file name. @param szdptr Size of buffer (number of dkChar). @param shortname Short configuration file name. @param dir_share The data directory. @param dir_etc The system configuration directory. @param dir_home Users home directory. @param name_prog Application name. @param name_group Application group name. @param passno Number of current pass. @param co3 Flag: Compatible mode to DK tools 3. @param compressed Flag: Allow gzip and bzip2 compressed files too, if the library was build with gzip and/or bzip2 support. @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if dptr or shortname is NULL or szdptr is 0 or passno is an invalid number or one of the used strings (dir_share, dir_etc, dir_home, name_prog, or name_group) is NULL, - DK4_E_BUFFER_TOO_SMALL
if the dptr buffer is too small, - DK4_E_MATH_OVERFLOW
if a mathematical overflow happened during a size calculation, - DK4_E_NOT_FOUND
if no file was found, - DK4_E_NOT_SUPPORTED
if wchar_t are used as dkChar on non-Windows systems. */ int dk4fs_config_compat_one( dkChar *dptr, size_t szdptr, const dkChar *shortname, const dkChar *dir_share, const dkChar *dir_etc, const dkChar *dir_home, const dkChar *name_prog, const dkChar *name_group, int passno, int co3, int compressed, dk4_er_t *erp ); /** Check one path candidate for configuration file name (construct name and check presence of file). To search for a file matching your needs run this function multiple times with differenct passno values. - To search for one file best matching: - Start with pass number DK4_FS_CONF_MAX or DK4_FS_CONF_SYS_MAX and decrease the number down to DK4_FS_CONF_SHARE_LIB, use the first file found. - Start with pass number DK4_FS_CONF_MAX to allow both user and system configuration files. - Start with pass number DK4_FS_CONF_SYS_MAX to process system configuration files only. - To process multiple files, each file may overwrite settings made by previous files: - Start with pass number DK4_FS_CONF_SHARE_LIB (0) and increase the pass number up to DK4_FS_CONF_SYS_MAX or DK4_FS_CONF_MAX. - Stopping after DK4_FS_CONF_SYS_MAX will process system configuration files only, stopping after DK4_FS_CONF_MAX processes both system and user configuration files. CRT on Windows: Optional. @param dptr Buffer for result file name. @param szdptr Size of buffer (number of dkChar). @param shortname Short configuration file name. @param dir_share The data directory. @param dir_etc The system configuration directory. @param dir_home Users home directory. @param name_prog Application name. @param name_group Application group name. @param passno Number of current pass. @param compressed Flag: Allow gzip and bzip2 compressed files too, if the library was build with gzip and/or bzip2 support. @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if dptr or shortname is NULL or szdptr is 0 or passno is an invalid number or one of the used strings (dir_share, dir_etc, dir_home, name_prog, or name_group) is NULL, - DK4_E_BUFFER_TOO_SMALL
if the dptr buffer is too small, - DK4_E_MATH_OVERFLOW
if a mathematical overflow happened during a size calculation, - DK4_E_NOT_FOUND
if no file was found, - DK4_E_NOT_SUPPORTED
if wchar_t are used as dkChar on non-Windows systems. */ int dk4fs_config_one( dkChar *dptr, size_t szdptr, const dkChar *shortname, const dkChar *dir_share, const dkChar *dir_etc, const dkChar *dir_home, const dkChar *name_prog, const dkChar *name_group, int passno, int compressed, dk4_er_t *erp ); /** Attempt to construct one path name for a data file. CRT on Windows: Optional. @param dptr Buffer for result file name. @param szdptr Size of buffer (number of dkChar). @param shortname Short configuration file name. @param dir_share The data directory. @param language Users language. @param region Users region. @param dir_home Users home directory. @param name_prog Application name. @param name_group Application group name. @param passno Number of current pass. @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if dptr or shortname is NULL or szdptr is 0 or passno is an invalid number or one of the used strings (dir_share, dir_home, language, region, name_prog, or name_group) is NULL, - DK4_E_BUFFER_TOO_SMALL
if the dptr buffer is too small, - DK4_E_MATH_OVERFLOW
if a mathematical overflow happened during a size calculation. */ int dk4fs_data_construct_one( dkChar *dptr, size_t szdptr, const dkChar *shortname, const dkChar *dir_share, const dkChar *language, const dkChar *region, const dkChar *dir_home, const dkChar *name_prog, const dkChar *name_group, int passno, dk4_er_t *erp ); /** Check one path candidate for data file name (construct file name and check presence). To search for a file, use this function multiple times with different passno values: - Start with DK4_F_DATA_MAX, DK4_FS_DATA_CURRENT_DIR, DK4_FS_DATA_HOME_APP or DK4_FS_DATA_MAX_SYS. - Decrease the pass number down to DK4_FS_DATA_SHARE_LIB. - Use the first file found. CRT on Windows: Optional. @param dptr Buffer for result file name. @param szdptr Size of buffer (number of dkChar). @param shortname Short configuration file name. @param dir_share The data directory. @param dir_home Users home directory. @param name_prog Application name. @param name_group Application group name. @param language Users preferred language. @param region Users region (country code). @param passno Number of current pass. @param compressed Flag: Allow compressed files too. @param erp Error report, may be NULL. @return 1 on success, 0 on error. Error codes: - DK4_E_INVALID_ARGUMENTS
if dptr or shortname is NULL or szdptr is 0 or passno is an invalid number or one of the used strings (dir_share, dir_home, language, region, name_prog, or name_group) is NULL, - DK4_E_BUFFER_TOO_SMALL
if the dptr buffer is too small, - DK4_E_MATH_OVERFLOW
if a mathematical overflow happened during a size calculation, - DK4_E_NOT_FOUND
if no file was found, - DK4_E_NOT_SUPPORTED
if wchar_t are used as dkChar on non-Windows systems. */ int dk4fs_data_one( dkChar *dptr, size_t szdptr, const dkChar *shortname, const dkChar *dir_share, const dkChar *dir_home, const dkChar *name_prog, const dkChar *name_group, const dkChar *language, const dkChar *region, int passno, int compressed, dk4_er_t *erp ); #ifdef __cplusplus } #endif #endif