/* 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: dk3app.ctr */ /* Copyright (C) 2011-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 DK3APP_H_INCLUDED /** Avoid multiple inclusions. */ #define DK3APP_H_INCLUDED 1 #line 10 "dk3app.ctr" /** @file dk3app.h Application support. */ #include "dk3conf.h" #include "dk3types.h" #ifdef __cplusplus extern "C" { #endif /** Open application structure for command line application. * Diagnostic messages are written to stderr and to the log file. * The log file $HOME/log/application-pid.log * is removed automatically by dk3app_close() unless there was an * error message. * @param argc Number of command line arguments. * @param argv Command line arguments array. * @param gn Application group name. * @return Pointer to new application on success, NULL on error. */ dk3_app_t * dk3app_open_command(int argc, dkChar const * const * argv, dkChar const *gn); /** Open application structure for GUI application. * Diagnostic messages are written to the log file only. * The log file is removed automatically by dk3app_open() unless * there were error messages. * Typically this function is invoked from a DkWxAppHelper constructor. * @param argc Number of command line arguments. * @param argv Command line arguments array. * @param gn Application group name. * @return Pointer to new application on success, NULL on error. */ dk3_app_t * dk3app_open_gui(int argc, dkChar const * const * argv, dkChar const *gn); /** First silence check to correct the type if necessary. Do not report errors directly, set app->de instead. @param app Application structure. @param argc Number of command line arguments. @param argv Command line arguments array. */ int dk3app_first_silence_check(dk3_app_t *app,int argc,dkChar const * const *argv); /** Open application structure for a daemon. * Log messages are appended to * ${localstatedir}/log/applicationname/applicationname.log. * @param wd Working directory when starting the program. * @param argc Number of command line arguments. * @param argv Command line arguments array. * @param gn Application group name. * @return Pointer to new application on success, NULL on error. */ dk3_app_t * dk3app_open_daemon(dkChar const *wd, int argc, dkChar const * const * argv, dkChar const *gn); /** Open application structure for a silent application (no diagnostics). * @param argc Number of command line arguments. * @param argv Command line arguments array. * @param gn Application group name. * @return Pointer to new application on success, NULL on error. */ dk3_app_t * dk3app_open_silent(int argc, dkChar const * const * argv, dkChar const *gn); /** Close application structure, release dynamic memory and resources * assigned to the object. * @param app Application to close. */ void dk3app_close(dk3_app_t *app); /** Log a message consisting of multiple parts. * @param app Application structure. * @param ll Log level. * @param msg Message parts array. Pointer to an array * of string pointers, all array elements are concatenated to * create the message text. * @param nmsg Number of elements in the array. */ void dk3app_log_msg(dk3_app_t *app, int ll, dkChar const * const * msg, size_t nmsg); /** Log message consisting of one part. * @param app Application structure. * @param ll Log level. * @param msg Message texts array, typically localized, obtained * from dk3app_messages(). * @param i1 Index of message text in \a msg. */ void dk3app_log_1(dk3_app_t *app, int ll, dkChar const * const * msg, size_t i1); /** Log message consisting of two parts. * @param app Application structure. * @param ll Log level. * @param msg Message texts array, typically localized, obtained * from dk3app_messages(). * @param i Index of message text in \a msg. * @param st String to write as second part. */ void dk3app_log_2( dk3_app_t *app, int ll, dkChar const * const * msg, size_t i, dkChar const *st ); /** Log message consisting of three parts. * @param app Application structure. * @param ll Log level. * @param msg Message string array. * @param i1 Index of first message text in \a msg. * @param i2 Index of third message text in \a msg. * @param st Second message text. */ void dk3app_log_3( dk3_app_t *app, int ll, dkChar const * const * msg, size_t i1, size_t i2, dkChar const *st ); /** Log message consisting of five parts. * @param app Application structure. * @param ll Log level. * @param msg Message string array. * @param i1 Index of first message text in \a msg. * @param i2 Index of third message text in \a msg. * @param i3 Index of fifth message text in \a msg. * @param st1 Second message text. * @param st2 Fourth message text. */ void dk3app_log_5( dk3_app_t *app, int ll, dkChar const * const * msg, size_t i1, size_t i2, size_t i3, dkChar const *st1, dkChar const *st2 ); /** Log message consisting of one part. * @param app Application structure. * @param ll Log level. * @param i1 Index of message text in messages array. */ void dk3app_log_i1(dk3_app_t *app, int ll, size_t i1); /** Log message consisting of two parts. * @param app Application structure. * @param ll Log level. * @param i Index of first message text in messages array. * @param st Second message text. */ void dk3app_log_i2(dk3_app_t *app, int ll, size_t i, dkChar const * st); /** Log message consisting of three parts. * @param app Application structure. * @param ll Log level. * @param i1 Index of first message text in messages array. * @param i2 Index of third message text in messages array. * @param st Second message text. */ void dk3app_log_i3( dk3_app_t *app, int ll, size_t i1, size_t i2, dkChar const *st ); /** Log message consisting of five parts. * @param app Application structure. * @param ll Log level. * @param i1 Index of first message text in messages array. * @param i2 Index of third message text in messages array. * @param i3 Index of fifth message text in messages array. * @param st1 Second message text. * @param st2 Fourth message text. */ void dk3app_log_i5( dk3_app_t *app, int ll, size_t i1, size_t i2, size_t i3, dkChar const *st1, dkChar const *st2 ); /** Set file name for current source file position. The source file position is used when writing diagnostic messages. @param app Application structure. @param fn Source file name. Use NULL to disable printing the file name. */ void dk3app_set_source_file(dk3_app_t *app, dkChar const *fn); /** Set source line number for current source file position. The source file position is used when writing diagnostic messages. @param app Application structure. @param li Line number. Use 0UL to disable printing the line number. */ void dk3app_set_source_line(dk3_app_t *app, unsigned long li); /** Get current source file name. @param app Application structure. @return Current source file name, may be NULL. */ dkChar const * dk3app_get_source_file(dk3_app_t const *app); /** Get current source line number. @param app Application structure. @return Current source file line number, may be 0UL. */ unsigned long dk3app_get_source_line(dk3_app_t const *app); /** Get number of command line arguments. @param app Application structure. @return Number of command line arguments. */ int dk3app_get_argc(dk3_app_t const *app); /** Get command line arguments array. @param app Application structure. @return Command line arguments array. */ dkChar const * const * dk3app_get_argv(dk3_app_t const *app); /** Retrieve application name. @param app Application structure. @return Application name on success, NULL on error. */ dkChar const * dk3app_get_appname(dk3_app_t const *app); /** Retrieve name of executable file. * @param app Application structure. * @return Executable file name on success, NULL on error. */ dkChar const * dk3app_get_execfilename(dk3_app_t const *app); /** Retrieve binary directory name. @param app Application structure. @return Name of bin directory on success, NULL on error. */ dkChar const * dk3app_get_bindir(dk3_app_t const *app); /** Get system configuration directory (/etc or /usr/local/etc). @param app Application structure. @return Directory name on success, NULL on error. */ dkChar const * dk3app_get_etcdir(dk3_app_t const *app); /** Get data root directory (/usr/share or /usr/local/share). @param app Application structure. @return Directory name on success, NULL on error. */ dkChar const * dk3app_get_sharedir(dk3_app_t const *app); /** Get local state directory (/var or /usr/local/var). @param app Application structure. @return Directory name on success, NULL on error. */ dkChar const * dk3app_get_vardir(dk3_app_t const *app); /** Get user login name. @param app Application structure. @return Login name on success, NULL on error. */ dkChar const * dk3app_get_logname(dk3_app_t const *app); /** Get host name. @param app Application structure. @return Host name on success, NULL on error. */ dkChar const * dk3app_get_hostname(dk3_app_t const *app); /** Get users home directory. @param app Application structure. @return Home directory on success, NULL on error. */ dkChar const * dk3app_get_homedir(dk3_app_t const *app); /** Get application group name. @param app Application structure. @return Group name on success, NULL on error. */ dkChar const * dk3app_get_appgroup(dk3_app_t const *app); /** Retrieve users language. @param app Application structure. @return Pointer to users language or NULL if no language is defined. */ dkChar const * dk3app_get_language(dk3_app_t const *app); /** Retrieve users region. @param app Application structure. @return Pointer to users region or NULL if no region is defined. */ dkChar const * dk3app_get_region(dk3_app_t const *app); /** Retrieve internal encoding. @param app Application structure. @return Internal (in-memory) encoding. */ int dk3app_get_encoding(dk3_app_t const *app); /** Retrieve output file encoding. @param app Application structure. @return Output file encoding. */ int dk3app_get_output_encoding(dk3_app_t const *app); /** Retrieve default encoding expected on stdin. @param app Application structure. @return Expected input encoding (DK3_FILE_ENCODING_xxx). */ int dk3app_get_input_stdin_encoding(dk3_app_t const *app); /** Retrieve default encoding expected on files. @param app Application structure. @return Expected input encoding (DK3_FILE_ENCODING_xxx). */ int dk3app_get_input_file_encoding(dk3_app_t const *app); /** Get file name for temporary file. The file name is stored into the buffer @a db. @param app Application structure. @param db Destination buffer. @param sz Size of \a db (number of characters). @return 1 on success, 0 on error. */ int dk3app_get_temp_file_name(dk3_app_t *app, dkChar *db, size_t sz); /** Set a preference value. Preferences set by this function are written to the $HOME/.dk3app/application/dk3pref.conf file during dk3app_close(). @param app Application structure. @param k Key (preference name). @param v Value. @return 1 on success, 0 on error. */ int dk3app_set_pref(dk3_app_t *app, dkChar const *k, dkChar const *v); /** Get a preference value. On success the preference value is written to @a d. @param app Application structure. @param k Key (preference name). @param d Destination buffer. @param s Size of \a d (number of characters). @return 1 on success, 0 on error. */ int dk3app_get_pref(dk3_app_t *app, dkChar const *k, dkChar *d, size_t s); /** Get boolean preference value. @param app Application structure. @param name Preference name. @param dv Default value if preference not found. @return Preference value or default value. */ int dk3app_get_pref_bool(dk3_app_t *app, dkChar const *name, int dv); /** Get int preference value. @param app Application structure. @param name Preference name. @param dv Default value. @return Preference value or default value. */ int dk3app_get_pref_int(dk3_app_t *app, dkChar const * name, int dv); /** Get a system preference value. Command line and user-set preferences are ignored. @param app Application structure. @param k Key (preference name). @param d Destination buffer. @param s Size of \a d (number of characters). @return 1 on success, 0 on error. */ int dk3app_get_sys_pref(dk3_app_t *app, dkChar const *k, dkChar *d, size_t s); /** Unconfigure application. @param app Application structure. */ void dk3app_unconfigure(dk3_app_t *app); /** Find configuration file. On success the function returns a file name collection. Configuration files with low priority are at the start of the collection, files with higher priority are at the end. This allows higher priorized configuration files to overwrite settings made by the previously processed files. After you are done with the search results set, use dk3search_close() to close the set and release resources assigned to it. @param app Application structure. @param fn File name to search for (short filename without leading path). @param exclu Flag: Exclude users configuration file. @return Collection of file names (full path names including the leading directory), use dk3search_close() after use to destroy it. */ dk3_search_t * dk3app_find_config_file(dk3_app_t *app, dkChar const *fn, int exclu); /** Find configuration file in reverse search order (most significant file first). This function is typically used to process the first file from the set only which is the most significant file. After you are done with the search results set, use dk3search_close() to close the set and release resources assigned to it. @param app Application structure. @param fn File name to search for (short file name without leading directory). @param exclu Flag: Exclude users configuration files. @return Collection of file names (full path names with leading directory), use dk3search_close() after use to destroy it. */ dk3_search_t * dk3app_find_config_file_revers(dk3_app_t *app, dkChar const *fn, int exclu); /** Find data file. The full path name of the file found is written to @a db on success. @param app Application structure. @param fn File name to search for (short file name without leading directory). @param db Destination buffer. @param sz Size of \a db (number of characters). @return 1 on success, 0 on error. */ int dk3app_find_data_file(dk3_app_t *app, dkChar const *fn, dkChar *db, size_t sz); /** Get string table. @param app Application structure. @param fn Short file name of string table. @param dv Default value, used if file not found. @return New string table if found or \a dv on problems. */ dkChar const * const * dk3app_messages(dk3_app_t *app, dkChar const *fn, dkChar const * const *dv); /** Find and print help text. The function searches for a help text file in the users language. If no file is found the default text is printed. @param app Application structure. @param fn Help text file name (short name wih). @param dt Default text to use if file not found. */ void dk3app_help(dk3_app_t *app, dkChar const *fn, dkChar const * const *dt); /** Get log level used for stderr. @param app Application structure. @return Log level required for logging to stderr. */ int dk3app_get_stderr_log_level(dk3_app_t const *app); /** Set log level used for stderr. @param app Application structure. @param ll New log level. */ void dk3app_set_stderr_log_level(dk3_app_t *app, int ll); /** Report write error. @param app Application structure. @param ll Log level. @param wished Number of bytes wished to write. @param written Number of bytes written. */ void dk3app_log_write_error(dk3_app_t *app, int ll, size_t wished, size_t written); /** Report fwrite error. @param app Application structure. @param ll Log level. @param wished Number of elements wished to write. @param written Number of elements written. */ void dk3app_log_fwrite_error(dk3_app_t *app, int ll, size_t wished, size_t written); /** Get a localized text. @param app Application structure. @param num Index of string in array. @return Pointer to localized string on success, NULL on error. */ dkChar const * dk3app_localized(dk3_app_t const *app, size_t num); /** Get a non-localized text. @param num Index of string in array. @return Pointer to localized string on success, NULL on error. */ dkChar const * dk3app_not_localized(size_t num); /** Initialize random number generator. Set up allowed PRNG types and seed best PRNG found. If at least one of the PRNG types specified in @a il is available we attempt to seed this PRNG. The following preferences are used by this function: - /rand/types is used if il is NULL. - /rand/file/allowed configured whether or not usage o seed file in the users home directory is allowed - /rand/egd/name can be used to specify of the EDG socket if an EGD (entropy gathering daemon) is running on the system. By default /dev/urandom and/or /dev/random are used to seed a PRNG if available. @param app Application structure. @param il Text line to process, may be NULL. If this argument is NULL, the /rand/types preference is used to find the allowed PRNG types. @return 1 on success, 0 on error. */ int dk3app_rand_init(dk3_app_t *app, dkChar const *il); /** Retrieve list of allowed PRNG types from a text line. If the text line \a il pointer is NULL the /rand/types preference value is used. @param app Application structure. @param il Text line to process. @return Combination of DK3_PRNG_xxx. */ int dk3app_get_allowed_prng_types(dk3_app_t *app, dkChar const *il); /** Retrieve pseudo-random bytes. @param app Application structure. @param db Destination buffer. @param sz Size of \a db (number of bytes). @return Number of bytes found. */ size_t dk3app_rand_bytes(dk3_app_t *app, void *db, size_t sz); /** Retrieve pseudo-random bytes. The bytes will not be used for cryptographic or authentication purposes, so we can use a less unpredictive (less complicated und thus faster) generation mechanism. @param app Application structure. @param db Destination buffer. @param sz Size of \a db (number of bytes). @return Number of bytes found. */ size_t dk3app_rand_bytes_non_crypto(dk3_app_t *app, void *db, size_t sz); /** Attempt to save random seed to file when closing an application. @param app Application structure. */ void dk3app_rand_end(dk3_app_t *app); /** Get default input encoding for stdin ignoring preferences. @param app Application structure. @return Encoding (DK3_FILE_ENCODING_xxx). */ int dk3app_get_default_stdin_encoding(dk3_app_t const *app); /** Get default input encoding for files ignoring preferences. @param app Application structure. @return Encoding (DK3_FILE_ENCODING_xxx). */ int dk3app_get_default_file_encoding(dk3_app_t const *app); /** Process standard input character by character. Attempt to save stdin data to file so we can do a BOM check. @param app Application structure. @param obj Object to modify while processing data. @param hf Handler function. @param de Default encoding. */ int dk3app_process_stdin_chars( dk3_app_t *app, void *obj, dk3_char_handler_t *hf, int de ); /** Process standard input line by line. Attempt to save stdin data to file so we can do a BOM check. @param app Application structure. @param obj Object to modify while reading data. @param hf Handler function. @param buffer Line buffer. @param szbuffer Size of buffer. @param de Default encoding. */ int dk3app_process_stdin_lines( dk3_app_t *app, void *obj, dk3_line_handler_t *hf, dkChar *buffer, size_t szbuffer, int de ); /** Get maximum log level used by the application. @param app Application structure. @return Maximum log level used by the application. */ int dk3app_max_log_level(dk3_app_t const *app); /** Remove trailing newline and handle backslash escape sequences. This function is run on lines read from string table file. @param lb Line buffer. */ void dk3app_squeeze_line(char *lb); #if !DK3_ON_WINDOWS #if DK3_HAVE_SETUID && DK3_HAVE_SETGID && DK3_HAVE_CHOWN #if DK3_CHAR_SIZE == 1 /** Change ownership to writable files. This function is used by daemons before switching to a non-privileged user account. @param app Application structure. @param uid New user ID for process. @param gid New group ID for process. @return 1 on success, 0 on error. */ int dk3app_change_user(dk3_app_t *app, uid_t uid, gid_t gid); #endif #endif #endif /** Retrieve directory setting from preference. @param app Application structure. @param pn Preference name. @param buf Result buffer. @param bs Size of bs (number of dkChar). @param ch Flag: Check existance of directory. @return 1 on success, 0 on error. */ int dk3app_get_dir_from_pref( dk3_app_t *app, dkChar const *pn, dkChar *buf, size_t bs, int ch ); #ifdef __cplusplus } #endif #endif