/* Copyright (C) 2015-2020, Dirk Krause SPDX-License-Identifier: BSD-3-Clause */ /* WARNING: This file was generated by the dkct program (see http://dktools.sourceforge.net/ for details). 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 */ #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 #if DK4_BUILDING_DKTOOLS4 #include "dk4conf.h" #else #include #endif #endif #ifndef DK4TYPES_H_INCLUDED #if DK4_BUILDING_DKTOOLS4 #include "dk4types.h" #else #include #endif #endif #ifndef DK4ERROR_H_INCLUDED #if DK4_BUILDING_DKTOOLS4 #include "dk4error.h" #else #include #endif #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 }; /** Pass numbers for documentation and help file search. */ enum { /** /usr/share/dktools/help/wxdkdraw/de/de. */ DK4_FS_DOC_GROUP_HELP_PROG_LANG_REG = 0, /** /usr/share/doc/dktools/help/wxdkdraw/de/de. */ DK4_FS_DOC_DOC_GROUP_PROG_LANG_REG , /** /usr/share/dktools/help/wxdkdraw/de. */ DK4_FS_DOC_GROUP_HELP_PROG_LANG , /** /usr/share/doc/dktools/help/wxdkdraw/de. */ DK4_FS_DOC_DOC_GROUP_PROG_LANG , /* The en subdirectory is used as fallback if no file in current language is available. */ /** /usr/share/dktools/help/wxdkdraw/en. */ DK4_FS_DOC_GROUP_HELP_PROG_EN , /** /usr/share/doc/dktools/help/wxdkdraw/en. */ DK4_FS_DOC_DOC_GROUP_PROG_EN , /** /usr/share/dktools/help/wxdkdraw. */ DK4_FS_DOC_GROUP_HELP_PROG , /** /usr/share/doc/dktools/help/wxdkdraw. */ DK4_FS_DOC_DOC_GROUP_PROG , /** /usr/share/dktools/help/de/de. */ DK4_FS_DOC_GROUP_HELP_LANG_REG , /** /usr/share/doc/dktools/help/de/de. */ DK4_FS_DOC_DOC_GROUP_LANG_REG , /** /usr/share/dktools/help/de. */ DK4_FS_DOC_GROUP_HELP_LANG , /** /usr/share/doc/dktools/help/de. */ DK4_FS_DOC_DOC_GROUP_LANG , /* The en subdirectory is used as fallback if no file in current language is available. */ /** /usr/share/dktools/help/en. */ DK4_FS_DOC_GROUP_HELP_EN , /** /usr/share/doc/dktools/help/en. */ DK4_FS_DOC_DOC_GROUP_EN , /** /usr/share/dktools/help. */ DK4_FS_DOC_GROUP_HELP , /** /usr/share/doc/dktools/help. */ DK4_FS_DOC_DOC_GROUP , DK4_FS_DOC_MAX = DK4_FS_DOC_DOC_GROUP /**< Maximum. */ }; #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 ); /** Attempt to construct one path name for a documentation or help 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 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_doc_construct_one( dkChar *dptr, size_t szdptr, const dkChar *shortname, const dkChar *dir_share, const dkChar *language, const dkChar *region, const dkChar *name_prog, const dkChar *name_group, int passno, dk4_er_t *erp ); /** Check one path candidate for documentation or help 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_FS_DOC_GROUP_HELP_PROG_LANG_REG. - Increase the pass number up to (including) DK4_FS_DOC_MAX. - 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 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 erp Error report, may be NULL. @return 1 on success, 0 on error. The function searches for the file shortname in the following directories, first file found is returned: - /usr/share/group/help/program/language/region - /usr/share/doc/group/help/program/language/region - /usr/share/group/help/program/language - /usr/share/doc/group/help/program/language - /usr/share/group/help/program/en - /usr/share/doc/group/help/program/en - /usr/share/group/help/program - /usr/share/doc/group/help/program For a relocated installation replace /usr/share by ${datadir}. 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_doc_one( dkChar *dptr, size_t szdptr, const dkChar *shortname, const dkChar *dir_share, const dkChar *name_prog, const dkChar *name_group, const dkChar *language, const dkChar *region, int passno, dk4_er_t *erp ); #ifdef __cplusplus } #endif #endif