/* Copyright (C) 2014, 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. */ /** @file dk4app.h Header file for the dk4app module. */ #ifndef DK4APP_H_INCLUDED /** Avoid multiple inclusions. */ #define DK4APP_H_INCLUDED 1 #ifndef DK4CONF_H_INCLUDED #include "dk4conf.h" #endif #ifndef DK4TYPES_H_INCLUDED #include "dk4types.h" #endif #ifndef DK4CONST_H_INCLUDED #include "dk4const.h" #endif #ifndef DK4ERROR_H_INCLUDED #include "dk4error.h" #endif #ifndef DK4OPT_H_INCLUDED #include "dk4opt.h" #endif #ifndef DK4STO_H_INCLUDED #include "dk4sto.h" #endif #ifndef DK4DIR_H_INCLUDED #include "dk4dir.h" #endif #ifndef DK4TIME_H_INCLUDED #include "dk4time.h" #endif /** Application structure. */ typedef struct { /** Storage containing all options. */ dk4_sto_t *s_opt_all; /** Iterator for storage containing all options. */ dk4_sto_it_t *i_opt_all; /** Storage containing only short options. */ dk4_sto_t *s_opt_short; /** Iterator for storage containing short options. */ dk4_sto_it_t *i_opt_short; /** Storage containing only long options. */ dk4_sto_t *s_opt_long; /** Storage for self-set preferences. */ dk4_sto_t *s_pref_self; /** Storage for preferences on the command line. */ dk4_sto_t *s_pref_cmd; /** Storage for user preferences. */ dk4_sto_t *s_pref_user; /** Storage for system preferences. */ dk4_sto_t *s_pref_sys; /** Storage for string tables. */ dk4_sto_t *s_stt; /** Storage iterator for self-set preferences. */ dk4_sto_it_t *i_pref_self; /** Storage iterator for preferences on the command line. */ dk4_sto_it_t *i_pref_cmd; /** Storage iterator for user preferences. */ dk4_sto_it_t *i_pref_user; /** Storage iterator for system preferences. */ dk4_sto_it_t *i_pref_sys; /** Iterator for storage containing only long options. */ dk4_sto_it_t *i_opt_long; /** Iterator for string table storage. */ dk4_sto_it_t *i_stt; /** Message texts for the base log domain. */ const dkChar * const *msg_base; /** Message texts for debug logging. */ const dkChar * const *msg_debug; /** Help text shown if no help file found. */ const dkChar * const *help_text; /** License text. */ const dkChar * const *lic_text; /** Unprocessed command line arguments, my_argc below is the number. */ dkChar **my_argv; /** Text to show as version information. */ dkChar *vers_text; /** Help file name. */ dkChar *help_file_name; /** Users login name. */ dkChar *user_name; /** Users home directory. */ dkChar *user_home; /** Host name. */ dkChar *host_name; /** Users preferred language or NULL (dynamically allocated). */ dkChar *language; /** Users region or NULL (dynamically allocated). */ dkChar *region; /** Program name (dynamically allocated). */ dkChar *prog_name; /** Program group name (dynamically allocated). */ dkChar *group_name; /** Directory in which the executable file resides (dynamically allocated). */ dkChar *dir_bin; /** System configuration directory (dynamically allocated). */ dkChar *dir_etc; /** Data directory (dynamically allocated). */ dkChar *dir_share; /** Library directory (dynamically allocated). */ dkChar *dir_lib; /** Local state directory (dynamically allocated). */ dkChar *dir_var; /** Directory for temporary files. */ dkChar *dir_tmp; /** Log file name (dynamically allocated). */ dkChar *log_file_name; /** Current source file name, used in diagnostic messages. */ const dkChar *source_file_name; /** Current source line number, used in diagnostic messages. */ dk4_um_t source_file_line; /** Timestamp: Previous message to stderr. */ dk4_time_t timer_stderr; /** Timestamp: Previous message to file. */ dk4_time_t timer_file; /** Number of message texts for the base log domain. */ size_t sz_msg_base; /** Number of message texts for the debug log domain. */ size_t sz_msg_debug; /** Flag: Have timestamp in timer_stderr. */ int have_stderr_time; /** Flag: Have timestamp in timer_file. */ int have_file_time; /** Flag: The log file was already opened at least once. */ int have_file_opened; /** Flag: stderr was initialized for logging. */ int have_stderr_init; /** Number of unprocessed command line arguments. */ int my_argc; /** Required log level for stderr logging. */ int ll_stderr; /** Required log level for file logging. */ int ll_file; /** Log level required to keep the log file after closing the application. */ int ll_file_keep; /** Worst log level found so far. */ int ll_found; /** Flag: Write timestamp when logging to stderr. */ int log_stderr_time; /** Flag: Write timestamp when logging to file. */ int log_file_time; /** Flag: Logging possible at this time. This flag is turned on after bringing up the application completely and turned off before shutting down the application. */ int log_enabled; /** Encoding used in memory and for dk4fputs() and dk4fputc(). */ int encoding; /** Expected encoding on standard input. */ int enc_in_std; /** Expected encoding on file input. */ int enc_in_file; /** Encoding to use when writing to standard output. */ int enc_out_std; /** Encoding to use when writing to file. */ int enc_out_file; /** Help, version or license. */ int hvl_cmd; /** Flag: Have self-set preferences to save. */ int have_self_pref; /** Flag: Fast application shutdown required due to signal. */ int fast_close; /** Flag: dir_tmp was used. */ int tmp_dir_used; } dk4_app_t; /** Errors found during application startup. */ typedef struct { /** Errors occured during opening the application. */ int error_found; /** Error with long option. */ const dkChar *longopt; /** Short option. */ dkChar shortopt; } dk4_app_error_t; /** Command line options for help, version, and license. */ enum { /** The --help option was used or there were wrong options. Show help text. */ DK4_APP_CMD_HELP = 1, /** The --version option was used, show version. */ DK4_APP_CMD_VERSION = 2, /** The --license option was used, show license. */ DK4_APP_CMD_LICENSE = 4, /** Show full manual instead of short help text. */ DK4_APP_CMD_MANUAL = 8, /** Help text shown due to wrong options. */ DK4_APP_CMD_ERROR = 16, }; /** Preferences sources. */ enum { DK4_APP_PREF_SRC_SYSTEM = 1, /**< System preferences. */ DK4_APP_PREF_SRC_USER = 2, /**< User preferences. */ DK4_APP_PREF_SRC_CMD = 4, /**< Preferences from command line. */ DK4_APP_PREF_SRC_SELF = 8 /**< Self-set preferences. */ }; #ifdef __cplusplus extern "C" { #endif /** Open an application structure for a command line program. @param argc Number of command line arguments. @param argv Command line arguments array. @param optspec Option specification, may be NULL. @param szoptspec Number of elements in optspec. @param groupname Program group name. @param version Version number string. @param helpfile Help file name. @param helptext Default help text. @param lictext License conditions text. @return Pointer to dk4_app_t structure on success, NULL on error. */ dk4_app_t * dk4app_open_cmd( int argc, dkChar **argv, const dk4_option_specification_t *optspec, size_t szoptspec, const dkChar *groupname, const dkChar *version, const dkChar *helpfile, const dkChar * const *helptext, const dkChar * const *lictext ); /** Open an application structure for a silent command line program. No logging to stderr or log file. @param argc Number of command line arguments. @param argv Command line arguments array. @param optspec Option specification, may be NULL. @param szoptspec Number of elements in optspec. @param groupname Program group name. @param version Version number string. @param helpfile Help file name. @param helptext Default help text. @param lictext License conditions text. @return Pointer to dk4_app_t structure on success, NULL on error. */ dk4_app_t * dk4app_open_silent( int argc, dkChar **argv, const dk4_option_specification_t *optspec, size_t szoptspec, const dkChar *groupname, const dkChar *version, const dkChar *helpfile, const dkChar * const *helptext, const dkChar * const *lictext ); /** Close an application structure. @param app Application structure to close. @return 1 on success, 0 on error. */ int dk4app_close(dk4_app_t *app); /** Set flag for fast application shutdown. @param app Application structure. */ void dk4app_set_fast_close(dk4_app_t *app); /** Check whether the application can run normally (help, version, license not required). CRT on Windows: Not used. @param app Application to check. @return 1 for normal run, 0 if dk4app_can_run_normally() should be run. */ int dk4app_can_run_normally(dk4_app_t *app); /** Respond to --help, --version, or --license. CRT on Windows: Required. @param app Application structure. @return 1 on success, 0 on error. */ int dk4app_help_version_license(dk4_app_t *app); /** Check whether or not to produce log output for a given log level. CRT on Windows: Not used. Disabling CRT use on Windows disables logging completely. @param app Application to check. @param ll Log level. @return 1 if the log level requires processing, 0 otherwise. */ int dk4app_log_do(dk4_app_t *app, int ll); /** Log multi part message. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure, may be NULL. @param priority Log priority. @param msg Pointer to message parts array. @param sz Number of message parts. */ void dk4app_log_msg( dk4_app_t *app, int priority, const dkChar * const *msg, size_t sz ); /** Write log message from a log-domain-specific message text array. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure. @param msg Pointer to array of message texts. @param sz_msg Array size (number of elements). @param priority Log priority. @param msgind Index of text in array. */ void dk4app_log_1( dk4_app_t *app, const dkChar * const *msg, size_t sz_msg, int priority, size_t msgind ); /** Write log message from a log-domain-specific message text array. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure. @param msg Pointer to array of message texts. @param sz_msg Array size (number of elements). @param priority Log priority. @param i1 Index of text in array. @param t1 Variable text surrounded by fixed texts. */ void dk4app_log_2( dk4_app_t *app, const dkChar * const *msg, size_t sz_msg, int priority, size_t i1, const dkChar *t1 ); /** Write log message from a log-domain-specific message text array. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure. @param msg Pointer to array of message texts. @param sz_msg Array size (number of elements). @param priority Log priority. @param i1 Index of text in array. @param i2 Index of trailing fixed text. @param t1 Variable text surrounded by fixed texts. */ void dk4app_log_3( dk4_app_t *app, const dkChar * const *msg, size_t sz_msg, int priority, size_t i1, size_t i2, const dkChar *t1 ); /** Write log message from a log-domain-specific message text array. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure. @param msg Pointer to array of message texts. @param sz_msg Array size (number of elements). @param priority Log priority. @param i1 Index of text in array. @param i2 Index of second fixed text. @param i3 Index of third fixed text. @param t1 First variable text. @param t2 Second variable text. */ void dk4app_log_5( dk4_app_t *app, const dkChar * const *msg, size_t sz_msg, int priority, size_t i1, size_t i2, size_t i3, const dkChar *t1, const dkChar *t2 ); /** Write log message from a log-domain-specific message text array. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure. @param msg Pointer to array of message texts. @param sz_msg Array size (number of elements). @param priority Log priority. @param i1 Index of text in array. @param i2 Index of second fixed text. @param i3 Index of third fixed text. @param i4 Index of fourth fixed text. @param t1 First variable text. @param t2 Second variable text. @param t3 Third variable text. */ void dk4app_log_7( dk4_app_t *app, const dkChar * const *msg, size_t sz_msg, int priority, size_t i1, size_t i2, size_t i3, size_t i4, const dkChar *t1, const dkChar *t2, const dkChar *t3 ); /** Write a one string log message. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure, may be NULL. @param priority Priority (ie DK4_LL_ERROR). @param msgind Index of message text within the domain. */ void dk4app_log_base1( dk4_app_t *app, int priority, size_t msgind ); /** Write a two string log message (one constant and one variable part). CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure, may be NULL. @param priority Priority (ie DK4_LL_ERROR). @param i1 Index of message text within the domain. @param t1 First variable text. */ void dk4app_log_base2( dk4_app_t *app, int priority, size_t i1, const dkChar *t1 ); /** Write a two string log message (two constant parts). CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure, may be NULL. @param priority Priority (ie DK4_LL_ERROR). @param i1 Index of message text within the domain. @param i2 Second texts index. */ void dk4app_log_base2c( dk4_app_t *app, int priority, size_t i1, size_t i2 ); /** Write a three string log message. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure, may be NULL. @param priority Priority (ie DK4_LL_ERROR). @param i1 Index of message text within the domain. @param i2 Index of second fixed text. @param t1 First variable text. */ void dk4app_log_base3( dk4_app_t *app, int priority, size_t i1, size_t i2, const dkChar *t1 ); /** Write a one string log message. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure, may be NULL. @param priority Priority (ie DK4_LL_ERROR). @param i1 Index of message text within the domain. @param i2 Index of second fixed text. @param i3 Index of third fixed text. @param t1 First variable text. @param t2 Second variable text. */ void dk4app_log_base5( dk4_app_t *app, int priority, size_t i1, size_t i2, size_t i3, const dkChar *t1, const dkChar *t2 ); /** Write a one string log message. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure, may be NULL. @param priority Priority (ie DK4_LL_ERROR). @param i1 Index of message text within the domain. @param i2 Index of second fixed text. @param i3 Index of third fixed text. @param i4 Index of fourth fixed text. @param t1 First variable text. @param t2 Second variable text. @param t3 Third variable text. */ void dk4app_log_base7( dk4_app_t *app, int priority, size_t i1, size_t i2, size_t i3, size_t i4, const dkChar *t1, const dkChar *t2, const dkChar *t3 ); /** Log a message, attempt to print errno value. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param app Application structure, may be NULL. @param priority Priority (ie DK4_LL_ERROR). @param i1 Index of fixed text 1 with errno. @param i2 Index of fixed text 2 with errno. @param i3 Index of fixed text 3 with errno. @param i4 Index of fixed text 1 without errno. @param i5 Index of fixed text 2 without errno. @param t1 Variable text. @param errn Value from errno. */ void dk4app_log_with_errno( dk4_app_t *app, int priority, size_t i1, size_t i2, size_t i3, size_t i4, size_t i5, const dkChar *t1, int errn ); /** Apply a preference. @param app Application structure to set up. @param ae Application open error structure. @param pn Preference name. @param pv Preference value. */ void dk4app_pref_apply( dk4_app_t *app, dk4_app_error_t *ae, const dkChar *pn, const dkChar *pv ); /** Retrieve preference value. @param dptr Destionation buffer. @param szdptr Size of destination buffer (number of dkChar). @param app Application structure. @param name Preference name. @param excl Sources to exclude. @return 1 on success, 0 on error. */ int dk4app_pref_get( dkChar *dptr, size_t szdptr, dk4_app_t *app, const dkChar *name, int excl ); /** Retrieve integer value from preferences. @param dptr Destination pointer (address of result variable). @param app Application structure. @param name Preference name. @param excl Preference sources to exclude. @return 1 on success, 0 on error. */ int dk4app_pref_get_int( dk4_im_t *dptr, dk4_app_t *app, const dkChar *name, int excl ); /** Retrieve unsigned integer value from preferences. @param dptr Destination pointer (address of result variable). @param app Application structure. @param name Preference name. @param excl Preference sources to exclude. @return 1 on success, 0 on error. */ int dk4app_pref_get_unsigned( dk4_um_t *dptr, dk4_app_t *app, const dkChar *name, int excl ); /** Retrieve boolean value from preferences. @param dptr Destination pointer (address of result variable). @param app Application structure. @param name Preference name. @param excl Preference sources to exclude. @return 1 on success, 0 on error. */ int dk4app_pref_get_bool( int *dptr, dk4_app_t *app, const dkChar *name, int excl ); /** Retrieve size_t value from preferences. @param dptr Destination pointer (address of result variable). @param app Application structure. @param name Preference name. @param excl Preference sources to exclude. @return 1 on success, 0 on error. */ int dk4app_pref_get_size( size_t *dptr, dk4_app_t *app, const dkChar *name, int excl ); /** Set one preference value. @param app Application structure. @param name Preference name. @param value Preference value. @return 1 on success, 0 on error. */ int dk4app_pref_set( dk4_app_t *app, const dkChar *name, const dkChar *value ); /** Save integer value to preference. @param app Application structure. @param name Preference name. @param value Value to save. @return 1 on success, 0 on error. */ int dk4app_pref_set_int(dk4_app_t *app, const dkChar *name, dk4_im_t value); /** Save unsigned integer value to preference. @param app Application structure. @param name Preference name. @param value Value to save. @return 1 on success, 0 on error. */ int dk4app_pref_set_unsigned(dk4_app_t *app, const dkChar *name, dk4_um_t value); /** Search for one configuration file. @param dptr Destination file name buffer. @param szdptr Size of dptr (number of dkChar). @param app Application structure. @param shortname Short file name (without leading directory). @param passno Pass number (0 to DK4_FS_CONF_SYS_MAX). @param compressed Flag: Allow compressed file versions. @param erp Error report, may be NULL. @return 1 on success (file found), 0 otherwise. 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_SYSTEM
with iDetails1 set to errno if stat() fails. */ int dk4app_search_one_config_file( dkChar *dptr, size_t szdptr, dk4_app_t *app, const dkChar *shortname, int passno, int compressed, dk4_er_t *erp ); /** Search for one data file. @param dptr Destination file name buffer. @param szdptr Size of dptr (number of dkChar). @param app Application structure. @param shortname Short file name (without leading directory). @param passno Pass number (0 to DK4_FS_DATA_MAX). @param compressed Flag: Allow compressed file versions. @param erp Error report, may be NULL. @return 1 on success (file found), 0 otherwise. 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_SYSTEM
with iDetails1 set to errno if stat() fails. */ int dk4app_search_one_data_file( dkChar *dptr, size_t szdptr, dk4_app_t *app, const dkChar *shortname, int passno, int compressed, dk4_er_t *erp ); /** Search for configuration file. @param dptr Destination file name buffer. @param szdptr Size of dptr (number of dkChar). @param app Application structure. @param shortname Short file name (without leading directory). @param maxpass Maximum pass number. @param compressed Flag: Allow compressed file versions. @param erp Error report, may be NULL. @return 1 on success (file found), 0 otherwise. 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_SYSTEM
with iDetails1 set to errno if stat() fails. */ int dk4app_search_config_file( dkChar *dptr, size_t szdptr, dk4_app_t *app, const dkChar *shortname, int maxpass, int compressed, dk4_er_t *erp ); /** Search for data file. @param dptr Destination file name buffer. @param szdptr Size of dptr (number of dkChar). @param app Application structure. @param shortname Short file name (without leading directory). @param maxpass Pass number (0 to DK4_FS_DATA_MAX). @param compressed Flag: Allow compressed file versions. @param erp Error report, may be NULL. @return 1 on success (file found), 0 otherwise. 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_SYSTEM
with iDetails1 set to errno if stat() fails. */ int dk4app_search_data_file( dkChar *dptr, size_t szdptr, dk4_app_t *app, const dkChar *shortname, int maxpass, int compressed, dk4_er_t *erp ); /** Find text array size. @param texts Array of texts, NULL pointer used as finalizer. @return Number of array elements without NULL finalizer. */ size_t dk4app_string_table_size(const dkChar * const *texts); /** Read text array from string table. @param app Application structure. @param shortname Short file name (without leading directory). @param deftexts Default texts (used if no file found or file unusable. @return Pointer to array of texts, either obtained from file or the default texts. */ const dkChar * const * dk4app_string_table( dk4_app_t *app, const dkChar *shortname, const dkChar * const *deftexts ); /** Retrieve internal encoding. @param app Application structure. @return Encoding used in memory and by the dk4fputs() and dk4fputc() functions. */ int dk4app_get_encoding(dk4_app_t *app); /** Retrieve encoding expected on stdin. @param app Application structure. @return Encoding expected on stdin. */ int dk4app_get_stdin_encoding(dk4_app_t *app); /** Retrieve encoding expected when reading files. @param app Application structure. @return Encoding expected when reading files. */ int dk4app_get_file_in_encoding(dk4_app_t *app); /** Retrieve encoding to use on stdout. @param app Application structure. @return Encoding to use when writing to stdout. */ int dk4app_get_stdout_encoding(dk4_app_t *app); /** Retrieve encoding to use when writing to files. @param app Application structure. @return Encoding to use when writing to files. */ int dk4app_get_file_out_encoding(dk4_app_t *app); /** Retrieve number of command line arguments. @param app Application structure. @return Number of command line arguments (program name not included). */ int dk4app_get_argc(dk4_app_t *app); /** Retrieve n-th command line argument. @param app Application structure. @param n Index of command line argument (0 for the first argument after program name). @return Pointer to command line argument on succes, NULL on error. */ const dkChar * dk4app_get_argv(dk4_app_t *app, int n); /** Remove file. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param fn File name. @param app Application structure for diagnostics, may be NULL. @return 1 on success, 0 on error. */ int dk4app_del_file(const dkChar *fn, dk4_app_t *app); /** Report problems from deleting a file. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param fn File name. @param erp Error report, filled by dk4delete_file(). @param app Application structure for diagnostics, may be NULL. */ void dk4app_del_file_report(const dkChar *fn, const dk4_er_t *erp, dk4_app_t *app); /** Remove empty directory. @param fn File name. @param app Application structure for diagnostics, may be NULL. @return 1 on success, 0 on error. */ int dk4app_del_dir(const dkChar *fn, dk4_app_t *app); /** Report problems from deleting a directory. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param fn File name. @param erp Error report, filled by dk4delete_directory(). @param app Application structure for diagnostics, may be NULL. */ void dk4app_del_dir_report(const dkChar *fn, const dk4_er_t *erp, dk4_app_t *app); /** Remove directory with all contents. CRT on Windows: Optional, disabling CRT use on Windows disables logging completely. @param fn File name. @param app Application structure for diagnostics, may be NULL. @return 1 on success, 0 on error. */ int dk4app_del_tree(const dkChar *fn, dk4_app_t *app); /** Open file name expander for pattern. @param pattern Pattern to match. @param app Application structure for diagnostics, may be NULL. @return Pointer to new file name expander on success, NULL on error. */ dk4_dir_t * dk4app_fne_open(const dkChar *pattern, dk4_app_t *app); /** Retrieve exactly one file name from file name expander. @param dptr Buffer for file name. @param szdptr Size of dptr (number of dkChar). @param fne File name expander. @param pattern Pattern for file name expander. @param app Application structure for diagnostics, may be NULL. @return 1 on success, 0 on error. */ int dk4app_fne_one_file( dkChar *dptr, size_t szdptr, dk4_dir_t *fne, const dkChar *pattern, dk4_app_t *app ); /** Retrieve preference value. CRT on Windows: Optional. @param dptr Result buffer address. @param szdptr Buffer size (number of dkChar). @param app Application structure. @param name Preference name. @param excl Preference sources to exclude, one from DK4_APP_PREF_SRC_SELF, DK4_APP_PREF_SRC_CMD, DK4_APP_PREF_SRC_USER, DK4_APP_PREF_SRC_SYSTEM or bitwise or-combination. @return 1 on success, 0 on error. */ int dk4app_pref_get( dkChar *dptr, size_t szdptr, dk4_app_t *app, const dkChar *name, int excl ); /** Retrieve integer value from preferences. CRT on Windows: Optional. @param dptr Pointer to result variable. @param app Application structure. @param name Preference name. @param excl Preference sources to exclude, one from DK4_APP_PREF_SRC_SELF, DK4_APP_PREF_SRC_CMD, DK4_APP_PREF_SRC_USER, DK4_APP_PREF_SRC_SYSTEM or bitwise or-combination. @return 1 on success, 0 on error. */ int dk4app_pref_get_int( dk4_im_t *dptr, dk4_app_t *app, const dkChar *name, int excl ); /** Retrieve unsigned integer value from preferences. CRT on Windows: Optional. @param dptr Pointer to result variable. @param app Application structure. @param name Preference name. @param excl Preference sources to exclude, one from DK4_APP_PREF_SRC_SELF, DK4_APP_PREF_SRC_CMD, DK4_APP_PREF_SRC_USER, DK4_APP_PREF_SRC_SYSTEM or bitwise or-combination. @return 1 on success, 0 on error. */ int dk4app_pref_get_unsigned( dk4_um_t *dptr, dk4_app_t *app, const dkChar *name, int excl ); /** Retrieve boolean value from preferences. CRT on Windows: Optional. @param dptr Pointer to result variable. @param app Application structure. @param name Preference name. @param excl Preference sources to exclude, one from DK4_APP_PREF_SRC_SELF, DK4_APP_PREF_SRC_CMD, DK4_APP_PREF_SRC_USER, DK4_APP_PREF_SRC_SYSTEM or bitwise or-combination. @return 1 on success, 0 on error. */ int dk4app_pref_get_bool( int *dptr, dk4_app_t *app, const dkChar *name, int excl ); /** Retrieve size value from preferences. CRT on Windows: Optional. @param dptr Pointer to result variable. @param app Application structure. @param name Preference name. @param excl Preference sources to exclude, one from DK4_APP_PREF_SRC_SELF, DK4_APP_PREF_SRC_CMD, DK4_APP_PREF_SRC_USER, DK4_APP_PREF_SRC_SYSTEM or bitwise or-combination. @return 1 on success, 0 on error. */ int dk4app_pref_get_size( size_t *dptr, dk4_app_t *app, const dkChar *name, int excl ); /** Set preferences value. CRT on Windows: Optional. @param app Application structure. @param name Preference name. @param value Preference value. @return 1 on success, 0 on error. */ int dk4app_pref_set( dk4_app_t *app, const dkChar *name, const dkChar *value ); /** Set preferences integer value. CRT on Windows: Optional. @param app Application structure. @param name Preference name. @param value Preference value. @return 1 on success, 0 on error. */ int dk4app_pref_set_int(dk4_app_t *app, const dkChar *name, dk4_im_t value); /** Set preferences unsigned integer value. CRT on Windows: Optional. @param app Application structure. @param name Preference name. @param value Preference value. @return 1 on success, 0 on error. */ int dk4app_pref_set_unsigned(dk4_app_t *app, const dkChar *name, dk4_um_t value); /** Retrieve source file name. @param app Application structure. @return Source file name if defined, NULL otherwise. */ const dkChar * dk4app_get_log_source_file(dk4_app_t *app); /** Retrieve source line number. @param app Application structure. @return Source line number if defined, 0 otherwise. */ dk4_um_t dk4app_get_log_source_line(dk4_app_t *app); /** Set source file name, reported in diagnostic messages. The structure does not keep a private copy of the name, it just stores the pointer provided. Make sure not to modify the file name afterwards. @param app Application structure. @param fn File name, may be NULL. */ void dk4app_set_log_source_file(dk4_app_t *app, const dkChar *fn); /** Set source line number, reported in diagnostic messages. @param app Application structure. @param lineno Line number, may be 0. */ void dk4app_set_log_source_line(dk4_app_t *app, dk4_um_t lineno); /** Retrieve localized texts for debug messages. @param app Application structure. @param szptr Address of variable to store array size, may be NULL. @return Pointer to localized texts on success, non-localized texts on error. */ const dkChar * const * dk4app_log_debug_texts(dk4_app_t *app, size_t *szptr); #ifdef __cplusplus } #endif #endif