diff options
Diffstat (limited to 'src/librcc.h')
| -rw-r--r-- | src/librcc.h | 891 |
1 files changed, 833 insertions, 58 deletions
diff --git a/src/librcc.h b/src/librcc.h index 2032330..7f3c823 100644 --- a/src/librcc.h +++ b/src/librcc.h @@ -19,37 +19,136 @@ /* ID's */ +/** + * Language ID. + * - 0 is default language + * - -1 is error + * - 1 usually represents "LibRCC off" language + * - >1 is some language + */ typedef unsigned char rcc_language_id; +/** + * Alias ID + */ typedef unsigned char rcc_alias_id; +/** + * Charset ID. + * - 0 is default charset + * - -1 is error + * - >0 is some charset + */ typedef unsigned char rcc_charset_id; +/** + * Autocharset ID. + * - -1 is error + * - >0 is some encoding + */ typedef unsigned char rcc_autocharset_id; +/** + * Engine ID. + * - -1 is non configured (first available will be used if any) + * - 0 autodetection is switched off + * - >0 is some auto-engine + */ typedef unsigned char rcc_engine_id; - +/** + * Class ID. + */ typedef int rcc_class_id; /* Opaque Pointer's */ -typedef struct rcc_context_t *rcc_context; -typedef struct rcc_engine_context_t *rcc_engine_context; -typedef struct rcc_language_config_t *rcc_language_config; -typedef const struct rcc_class_t *rcc_class_ptr; +typedef struct rcc_context_t *rcc_context; /**< Current Working Context */ +/** + * Encoding Detection Engine Context. Containes considered information about + * engine, which can be extracted using API functions. + * @see rccEngineGetInternal + * @see rccEngineGetLanguage + * @see rccEngineGetRccContext + */ +typedef struct rcc_engine_context_t *rcc_engine_context; +/** + * Current Language Configuration: + * Information about current 'class encodings', and selected 'Encoding Detection + * Engine' + */ +typedef struct rcc_language_config_t *rcc_language_config; +typedef const struct rcc_class_t *rcc_class_ptr; #ifdef __cplusplus extern "C" { #endif +/** + * Library Initialization function. Should be called prior to all + * any library manipulation. + */ int rccInit(); + +/** + * Library Cleanup function. + */ void rccFree(); /******************************************************************************* **************************** Initialization ************************************ *******************************************************************************/ +/** + * RCC context initialization flags + */ typedef unsigned int rcc_init_flags; -#define RCC_NO_DEFAULT_CONFIGURATION 1 + +/** + * Do not load default language configuration + */ +#define RCC_FLAG_NO_DEFAULT_CONFIGURATION 1 + +/** + * Initialize working context. + * + * @param locale_variable is variable to get locale from (Default: LC_CTYPE). + * @param max_languages is maximal number of languages supported by context. (Default: detect) + * @param max_classes is maximal number of classes (Default: detect) + * @param defclasses is list of encoding classes (Default: will add later) + * @param flags is option flag (Default: nothing) + * @see RCC_FLAG_NO_DEFAULT_CONFIGURATION + * @return working context or NULL in case of error + */ rcc_context rccCreateContext(const char *locale_variable, unsigned int max_languages, unsigned int max_classes, rcc_class_ptr defclasses, rcc_init_flags flags); +/** + * Initialize default working context (used then no context supplied). Previously + * opened default context will be freed. + * + * @param locale_variable is variable to get locale from (Default: LC_CTYPE). + * @param max_languages is maximal number of languages supported by context. (Default: detect) + * @param max_classes is maximal number of classes (Default: detect) + * @param defclasses is list of encoding classes (Default: will add later) + * @param flags is option flag (Default: nothing) + * @see RCC_FLAG_NO_DEFAULT_CONFIGURATION + * @return non-zero value in case of error + */ int rccInitDefaultContext(const char *locale_variable, unsigned int max_languages, unsigned int max_classes, rcc_class_ptr defclasses, rcc_init_flags flags); + +/** + * Free all memory used by working context and destroy it. + * + * @param ctx is working context to be destroyed. + */ void rccFreeContext(rcc_context ctx); + +/** + * Berkeley DB initialization flags + */ typedef unsigned int rcc_db4_flags; + +/** + * Enables Berkeley DB recodings caching for specified working context. + * + * @param ctx is working context + * @param name is database name (can be shared between different applications) + * @param flags are reserved for future. + * @return non-zero value in case of error + */ int rccInitDb4(rcc_context ctx, const char *name, rcc_db4_flags flags); int rccLockConfiguration(rcc_context ctx, unsigned int lock_code); @@ -58,81 +157,194 @@ int rccUnlockConfiguration(rcc_context ctx, unsigned int lock_code); /******************************************************************************* ******************* Altering Language Configuaration *************************** *******************************************************************************/ +/** + * Encoding name. + */ typedef const char *rcc_charset; +/** + * List of Encoding names + */ typedef rcc_charset rcc_charset_list[RCC_MAX_CHARSETS+1]; /* Engines */ +/** + * Engine internal data + */ typedef void *rcc_engine_internal; +/** + * Engine constructor function + * @param ctx is engine context + * @see rccEngineGetInternal + * @see rccEngineGetLanguage + * @see rccEngineGetRccContext + * @return pointer on desired internal data to be stored in engine_context. + */ typedef rcc_engine_internal (*rcc_engine_init_function)(rcc_engine_context ctx); +/** + * Engine encoding detection function. + * @param ctx is engine context + * @param buf is string encoded in unknow encoding + * @param len is exact size of string or 0 (size will be detected with strlen) + * @return the #rcc_autocharset_id of the detected encoding or -1 in case of error + */ typedef rcc_autocharset_id (*rcc_engine_function)(rcc_engine_context ctx, const char *buf, int len); +/** + * Engine destructor function + */ typedef void (*rcc_engine_free_function)(rcc_engine_context ctx); +/** + * Encoding detection engine description. Init and Free functions can be omited. + * 'func' should analyze string and return position in the encodings list + * coresponding to string encoding. + */ struct rcc_engine_t { - const char *title; - rcc_engine_init_function init_func; - rcc_engine_free_function free_func; - rcc_engine_function func; - rcc_charset_list charsets; + const char *title; /**< Short title*/ + rcc_engine_init_function init_func; /**< Constructor function */ + rcc_engine_free_function free_func; /**< Destructor function */ + rcc_engine_function func; /**< Function performing encoding detection */ + rcc_charset_list charsets; /**< List of supported encodings */ }; typedef struct rcc_engine_t rcc_engine; typedef rcc_engine *rcc_engine_ptr; typedef rcc_engine_ptr rcc_engine_list[RCC_MAX_ENGINES+1]; -/* Language */ +/** + * Language description. + */ struct rcc_language_t { - const char *sn; - rcc_charset_list charsets; - rcc_engine_list engines; + const char *sn; /**< Language ISO-639-1 (2 symbol) name */ + rcc_charset_list charsets; /**< List of language encodings */ + rcc_engine_list engines; /**< List of encoding detection engines supported by language */ }; typedef struct rcc_language_t rcc_language; typedef rcc_language *rcc_language_ptr; typedef rcc_language_ptr rcc_language_list[RCC_MAX_LANGUAGES+1]; -/* Alias */ +/** + * Language Aliases. + * For example (ru_UA = uk, cs_SK = sk ) + */ struct rcc_language_alias_t { - const char *alias; - const char *lang; + const char *alias; /**< Long locale name */ + const char *lang; /* Coresponded language ISO-639-1 name */ }; typedef struct rcc_language_alias_t rcc_language_alias; typedef rcc_language_alias *rcc_language_alias_ptr; typedef rcc_language_alias_ptr rcc_language_alias_list[RCC_MAX_ALIASES+1]; +/** + * Register new language in supplied working context + * @param ctx is working context ( or default one if NULL supplied ) + * @language is pointer on language description (shouldn't be freed before library deinitialization). + * @return registered language id or -1 in case of a error. + */ rcc_language_id rccRegisterLanguage(rcc_context ctx, rcc_language *language); +/** + * Register new encoding belonging to language in supplied working context + * @param ctx is working context ( or default one if NULL supplied ) + * @charset is pointer on charset name (shouldn't be freed before library deinitialization). + * @return registered charset id or -1 in case of a error. + */ rcc_charset_id rccLanguageRegisterCharset(rcc_language *language, rcc_charset charset); +/** + * Register new Engine in supplied working context + * @param ctx is working context ( or default one if NULL supplied ) + * @engine is pointer on engine description (shouldn't be freed before library deinitialization). + * @return registered engine id or -1 in case of a error. + */ rcc_engine_id rccLanguageRegisterEngine(rcc_language *language, rcc_engine *engine); +/** + * Register new language alias in supplied working context + * @param ctx is working context ( or default one if NULL supplied ) + * @alias is pointer on alias description (shouldn't be freed before library deinitialization). + * @return registered alias id or -1 in case of a error. + */ rcc_alias_id rccRegisterLanguageAlias(rcc_context ctx, rcc_language_alias *alias); /******************************************************************************* ************************ Altering Configuaration ******************************* *******************************************************************************/ +/** + * Enumeration represents type of class. + */ typedef enum rcc_class_type_t { - RCC_CLASS_INVALID = 0, - RCC_CLASS_STANDARD, - RCC_CLASS_KNOWN, - RCC_CLASS_FS + RCC_CLASS_INVALID = 0, /**< Invalid value */ + RCC_CLASS_STANDARD, /**< Standard class */ + RCC_CLASS_KNOWN, /**< Class encoding is known and no autodetection should be performed */ + RCC_CLASS_FS /**< Class strings are representing file names */ } rcc_class_type; +/** + * Provides information about default encoding for specific language + */ struct rcc_class_default_charset_t { - const char *lang; - const char *charset; + const char *lang; /**< Language */ + const char *charset; /**< Default encoding for #lang */ }; typedef const struct rcc_class_default_charset_t rcc_class_default_charset; +/** Forbid change class value using Library API */ #define RCC_CLASS_FLAG_CONST 0x01 +/** Forbid saving and loading of class value */ #define RCC_CLASS_FLAG_SKIP_SAVELOAD 0x02 +/** Encoding class description. Encoding classes are main concept of LibRCC library. + * The strings are recoded between different classes (for example in RusXMMS2 project + * ID3 titles are recoded between ID3 and Output classes). The current encoding of + * each class can be set using configuration file or API call, otherwise it will + * be detected automatically using current locale or default encoding. + * + * If the #defvalue is not NULL, it provides information about detection of + * the default encoding. The are following possibilities for that value: + * - Detect default encoding using specified locale variable (LC_CTYPE for example). + * . - The current encoding of the another class will be used instead of default encodings. Short name of considered class should be specified. + * - Just use specified multibyte encoding for all languages. + * In case of detection failure using all these methods, the #defcharset will + * be examined if default encoding for current language is available. If not, + * the first encoding in the list will be used as current. + * + * Additionaly it is possible to set special flags to prevent user from + * modifying class value. It is possible to protect class from changing + * ether using API, or configuration files. + * + * @see rcc_class_default_charset_t + * @see RCC_CLASS_FLAG_CONST + * @see RCC_CLASS_FLAG_SKIP_SAVELOAD + * + * The class type provides information for recoding functions about + * automatic detection of the class chrset. The encodings of the + * #RCC_CLASS_STANDARD classes will be detected using autoengine (if available + * for current language. The #RCC_CLASS_FS classes are associated with files + * and encoding will be guessed using find_file. + * + * @see rcc_class_type_t + * + */ struct rcc_class_t { - const char *name; - const rcc_class_type class_type; - const char *defvalue; /* locale variable name or parrent name or multibyte charset */ - rcc_class_default_charset *defcharset; - const char *fullname; - const unsigned long flags; + const char *name; /**< Short class name */ + const rcc_class_type class_type; /**< specifies type of class (Standard, File System, Known) */ + const char *defvalue; /**< locale variable name or parrent name or multibyte encoding name */ + rcc_class_default_charset *defcharset; /**< default class encodings. Should be specified on per-language basys */ + const char *fullname; /**< Full name of the class */ + const unsigned long flags; /**< Class flags. (CONST, SKIP_SAVELOAD) */ }; typedef const struct rcc_class_t rcc_class; typedef rcc_class_ptr rcc_class_list[RCC_MAX_CLASSES+1]; +/** + * Register additional class + * @param ctx is working context ( or default one if NULL supplied ) + * @cl is pointer on the class description (shouldn't be freed before library deinitialization). + * @return registered class id or -1 in case of a error. + */ rcc_class_id rccRegisterClass(rcc_context ctx, rcc_class *cl); +/** + * Determines 'class type' of supplied class. + * @param ctx is working context ( or default one if NULL supplied ) + * @class_id is class id + * @return class type or -1 in case of a error. + */ rcc_class_type rccGetClassType(rcc_context ctx, rcc_class_id class_id); /******************************************************************************* @@ -140,102 +352,441 @@ rcc_class_type rccGetClassType(rcc_context ctx, rcc_class_id class_id); *******************************************************************************/ typedef int rcc_option_value; +/** + * Use BerkeleyDB recodings cache for encoding detection + */ #define RCC_OPTION_LEARNING_FLAG_USE 1 +/** + * Cache recodings in BerkeleyDB recoding cache for future use + */ #define RCC_OPTION_LEARNING_FLAG_LEARN 2 + +/** + * List of options available + */ typedef enum rcc_option_t { - RCC_OPTION_LEARNING_MODE = 0, - RCC_OPTION_AUTODETECT_FS_TITLES, - RCC_OPTION_AUTODETECT_FS_NAMES, - RCC_OPTION_CONFIGURED_LANGUAGES_ONLY, + RCC_OPTION_LEARNING_MODE = 0, /**< Recoding Caching mode (OFF/ON/RELEARN/LEARN) */ + RCC_OPTION_AUTODETECT_FS_TITLES, /**< Detect titles of #RCC_CLASS_FS classes */ + RCC_OPTION_AUTODETECT_FS_NAMES, /**< Try to find encoding of #RCC_CLASS_FS by accessing fs */ + RCC_OPTION_CONFIGURED_LANGUAGES_ONLY, /**< Use only configured languages or languages with auto-engines */ RCC_MAX_OPTIONS } rcc_option; +/** + * List of option types + */ typedef enum rcc_option_type_t { - RCC_OPTION_TYPE_INVISIBLE = 0, - RCC_OPTION_TYPE_STANDARD, + RCC_OPTION_TYPE_INVISIBLE = 0, /**< Invisible option. Wouldn't be represented in UI menu */ + RCC_OPTION_TYPE_STANDARD, /**< Standard option. */ RCC_OPTION_TYPE_MAX } rcc_option_type; +/** + * Description of option values range type + */ typedef enum rcc_option_range_type_t { - RCC_OPTION_RANGE_TYPE_BOOLEAN = 0, - RCC_OPTION_RANGE_TYPE_RANGE, - RCC_OPTION_RANGE_TYPE_FLAGS, - RCC_OPTION_RANGE_TYPE_MENU, + RCC_OPTION_RANGE_TYPE_BOOLEAN = 0, /**< Boolean option */ + RCC_OPTION_RANGE_TYPE_RANGE, /**< Range of integer values */ + RCC_OPTION_RANGE_TYPE_FLAGS, /**< Set of boolean flags */ + RCC_OPTION_RANGE_TYPE_MENU, /**< Enumeration */ RCC_OPTION_RANGE_TYPE_MAX } rcc_option_range_type; -struct rcc_option_range_t { - rcc_option_range_type type; - rcc_option_value min; - rcc_option_value max; - rcc_option_value step; -}; -typedef struct rcc_option_range_t rcc_option_range; +/** + * Descriptionm of value range + */ +typedef struct rcc_option_range_t { + rcc_option_range_type type; /**< Value range type */ + rcc_option_value min; /**< Minimal acceptable option value */ + rcc_option_value max; /**< Maximal acceptable option value */ + rcc_option_value step; /**< Preccision step */ +}rcc_option_range; /* lng.c */ +/** + * Determines name of the supplied language. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @language_id is 'language id' of desired language. For default language the 'default' value will be returned. + * @return language name or NULL in case of a error. + */ const char *rccGetLanguageName(rcc_context ctx, rcc_language_id language_id); +/** + * Finds language id by the supplied name. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @parm is language name + * @return language id [0-n] or -1 if not found. + */ rcc_language_id rccGetLanguageByName(rcc_context ctx, const char *name); +/** + * This function resolves default languages. If positive language id is supplied + * it will be returned back unchanged. The default language (0 is supplied as + * language id) will be resolved to some particular language. + * The following procedure will be used: + * - 1. Detect Language by locale + * - 2. Check if language intialized if RCC_OPTION_CONFIGURED_LANGUAGES_ONLY is set + * - 3. If one of the previous steps is failed, select first available language (id=1). Usually it should be 'LibRCC off'. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @language_id is language id + * @return resolved language id [1-n] or -1 in case of error. + */ rcc_language_id rccGetRealLanguage(rcc_context ctx, rcc_language_id language_id); +/** + * Return considered language name, resolving default language if necessary. + * @see rccGetRealLanguage + * + * @param ctx is working context ( or default one if NULL supplied ) + * @language_id is language id + * @return resolved language name or NULL in case of error. + */ const char *rccGetRealLanguageName(rcc_context ctx, rcc_language_id language_id); +/** + * Return selected language id. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @return selected language id [0-n] or -1 in case of error + */ rcc_language_id rccGetSelectedLanguage(rcc_context ctx); +/** + * Return selected language name. + * @see rccGetSelectedLanguage + * + * @param ctx is working context ( or default one if NULL supplied ) + * @return selected language name or NULL in case of error. + */ const char *rccGetSelectedLanguageName(rcc_context ctx); +/** + * Return current language id, resolving default language to particular one if necessary. + * See more details how default language is resolved: @see rccGetRealLanguage + * + * @param ctx is working context ( or default one if NULL supplied ) + * @return current language id [1-n] or -1 in case of error + */ rcc_language_id rccGetCurrentLanguage(rcc_context ctx); +/** + * Return current language name. + # @see rccGetCurrentLanguage + * + * @param ctx is working context ( or default one if NULL supplied ) + * @return current language id [1-n] or -1 in case of error + */ const char *rccGetCurrentLanguageName(rcc_context ctx); + +/** + * Set current language. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param language_id is new language id [0-n]. Set to default state is Ok. + * @return non-zero value in case of error + */ int rccSetLanguage(rcc_context ctx, rcc_language_id language_id); +/** + * Set current language by name. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param name is the short name of new language. + * @return non-zero value in case of error + */ int rccSetLanguageByName(rcc_context ctx, const char *name); /* opt.c */ +/** + * Return option value. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param option is option + * @return current option value or -1 in case of error + */ rcc_option_value rccGetOption(rcc_context ctx, rcc_option option); +/** + * Tests if option have unchanged default value. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param option is option + * @return current option value or -1 in case of error + */ int rccOptionIsDefault(rcc_context ctx, rcc_option option); +/** + * Sets option to its default value. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param option is option + * @return non-zero value in case of error + */ int rccOptionSetDefault(rcc_context ctx, rcc_option option); +/** + * Set option value. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param option is option + * @param is option value + * @return non-zero value in case of erros + */ int rccSetOption(rcc_context ctx, rcc_option option, rcc_option_value value); +/** + * Get current option type. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param option is option + * @return current option type or -1 in case of error + */ rcc_option_type rccOptionGetType(rcc_context ctx, rcc_option option); +/** + * Return range description for specified option + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param option is option + * @return option range or -1 in case of error + */ rcc_option_range *rccOptionGetRange(rcc_context ctx, rcc_option option); +/** + * Get short name of supplied option. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param option is option + * @return option range or NULL in case of error + */ const char *rccGetOptionName(rcc_option option); + +/** + * Get short name of supplied option value. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param option is option + * @param value is value of #option + * @return option value name or NULL in case of error + */ const char *rccGetOptionValueName(rcc_option option, rcc_option_value value); +/** + * Get option by short name. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @parm is option name + * @return option or -1 in case of error + */ rcc_option rccGetOptionByName(const char *name); +/** + * Get option value by short name. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param option is option + * @param name is value name + * @return option value or -1 in case of error + */ rcc_option_value rccGetOptionValueByName(rcc_option option, const char *name); + /* lngconfig.c */ +/** + * Check if configuration is initialized for supplied language. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param language_id is concerned language id + * @return configuration context if: + * - language_id is particular language, not default one + * - language already intialized + * - language is not dummy (Disable LibRCC) language + * otherwise NULL is returned + */ +rcc_language_config rccCheckConfig(rcc_context ctx, rcc_language_id language_id); +/** + * Initializes language configuration if not yet configured and returns pointer on + * that configuration. If default language is supplied (language_id = 0), the + * language id will be resolved to particular language and config of that language + * will be returned. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param language_id is concerned language id + * @return configuration context. The NULL is returned in the case of errors or + * dummy (Dissable LibRCC) language is selected. + */ +rcc_language_config rccGetConfig(rcc_context ctx, rcc_language_id language_id); +/** + * Initializes language configuration if not yet configured and returns pointer on + * that configuration. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param name is concerned language name + * @return configuration context or NULL in case of error + */ +rcc_language_config rccGetConfigByName(rcc_context ctx, const char *name); +/** + * Returns pointer on the current language configuration (Initializes it as well + * if required) + * + * @param ctx is working context ( or default one if NULL supplied ) + * @return configuration context or NULL in case of error + */ +rcc_language_config rccGetCurrentConfig(rcc_context ctx); +/** + * Return supplied engine name + * + * @param config is language configuration + * @param engine_id is desired engine + * @return selected engine name or NULL in case of error. + */ const char *rccConfigGetEngineName(rcc_language_config config, rcc_engine_id engine_id); +/** + * Return supplied encoding name + * + * @param config is language configuration + * @param charset_id is desired charset + * @return selected encoding name or NULL in case of error. + */ const char *rccConfigGetCharsetName(rcc_language_config config, rcc_charset_id charset_id); -const char *rccConfigGetAutoCharsetName(rcc_language_config config, rcc_autocharset_id charset_id); +/** + * Function finds engine id by the supplied name. + * + * @param config is language configuration + * @parm is engine name + * @return engine id [0-n] or -1 if not found + */ rcc_engine_id rccConfigGetEngineByName(rcc_language_config config, const char *name); +/** + * Function finds encoding id by the supplied name. + * + * @param config is language configuration + * @parm is encoding name + * @return encoding id [0-n] or -1 if not found. + */ rcc_charset_id rccConfigGetCharsetByName(rcc_language_config config, const char *name); -rcc_autocharset_id rccConfigGetAutoCharsetByName(rcc_language_config config, const char *name); - -rcc_language_config rccCheckConfig(rcc_context ctx, rcc_language_id language_id); -rcc_language_config rccGetConfig(rcc_context ctx, rcc_language_id language_id); -rcc_language_config rccGetConfigByName(rcc_context ctx, const char *name); -rcc_language_config rccGetCurrentConfig(rcc_context ctx); +/** + * Return selected engin id. + * + * @param config is language configuration + * @return selected engine id [-1-n] + * - -1 engine is not configured and first available will be used + * - 0 engines are dissabled + * - >0 paticular engine id + */ rcc_engine_id rccConfigGetSelectedEngine(rcc_language_config config); +/** + * Return selected engine name. + * @see rccConfigGetSelectedEngine + * + * @param config is language configuration + * @return selected engine name ('default' will be returned if engine not configured) or NULL in case of error. + */ const char *rccConfigGetSelectedEngineName(rcc_language_config config); +/** + * Return current engine_id. The default value will be resolved to paticular engine id. Normally, + * the id of the first available engine will be returned. If no engines registered for supplied + * language the 0 will be returned, indicating id of dummy(dissabled) engine. + * + * @param config is language configuration + * @return selected engine id [0-n] or -1 in case of error + * - 0 engines are dissabled + * - >0 paticular engine id + */ rcc_engine_id rccConfigGetCurrentEngine(rcc_language_config config); +/** + * Return current engine name. + * @see rccConfigGetCurrentEngine + * + * @param config is language configuration + * @return current engine name or NULL in case of error. + */ const char *rccConfigGetCurrentEngineName(rcc_language_config config); + +/** + * Return selected encoding id. + * + * @param config is language configuration + * @param class_id is encoding class + * @return selected encoding id [0-n] or -1 in case of error + * - 0 default encoding + * - >0 paticular encoding id + */ rcc_charset_id rccConfigGetSelectedCharset(rcc_language_config config, rcc_class_id class_id); +/** + * Return selected encoding name. + * @see rccConfigGetSelectedCharset + * + * @param config is language configuration + * @param class_id is charset encodings + * @return selected encodings name ('default' will be returned if engine not configured) or NULL in case of error. + */ const char *rccConfigGetSelectedCharsetName(rcc_language_config config, rcc_class_id class_id); +/** + * Return current encoding_id. The default value will be resolved to paticular encoding id. + * The following procedure is used to detect default encoding: + * - If the parrent class is defined in #defcharset, - return current encoding of parrent class. + * - If the locale variable is defined in #defcharset and config language coincide with locale language, use locale encoding. + * - If the default value for config language is defined in #defvalue return that default value. + * - Return language with id 0. Normally this should be dummy language which indicates that RCC library is not used. + * + * @param config is language configuration + * @param class_id is encoding class + * @return selected charset id [1-n] or -1 in case of error + */ rcc_charset_id rccConfigGetCurrentCharset(rcc_language_config config, rcc_class_id class_id); +/** + * Return current encoding name. + * @see rccConfigGetCurrentCharset + * + * @param config is language configuration + * @param class_id is encoding class + * @return current charset name or NULL in case of error. + */ const char *rccConfigGetCurrentCharsetName(rcc_language_config config, rcc_class_id class_id); +/** + * Set current engine. + * + * @param config is language configuration + * @param engine_id is new language id [-1-n]. If -1 supplied the engine will go in non-configured state. + * @return non-zero value in case of error + */ int rccConfigSetEngine(rcc_language_config config, rcc_engine_id engine_id); +/** + * Set current encoding. + * + * @param config is language configuration + * @param class_id is encoding class + * @param charset_id is new charset id [0-n]. The 0 will switch charset to encoding state. + * @return non-zero value in case of error + */ int rccConfigSetCharset(rcc_language_config config, rcc_class_id class_id, rcc_charset_id charset_id); +/** + * Set current engine by name. + * + * @param config is language configuration + * @param name is the short name of new engine ("default" is okey). + * @return non-zero value in case of error + */ int rccConfigSetEngineByName(rcc_language_config config, const char *name); +/** + * Set current encoding by name. + * + * @param config is language configuration + * @param class_id is encoding class + * @param name is the short name of new encoding ("default" is okey). + * @return non-zero value in case of error + */ int rccConfigSetCharsetByName(rcc_language_config config, rcc_class_id class_id, const char *name); +/** + * Function will return encoding id of charset specified by locale configuration. + * + * @param config is language configuration + * @param locale_variable is locale variable (Default(NULL) is LC_CTYPE) + * @return encoding id + */ rcc_charset_id rccConfigGetLocaleCharset(rcc_language_config config, const char *locale_variable); + /* curconfig.c */ const char *rccGetEngineName(rcc_context ctx, rcc_engine_id engine_id); const char *rccGetCharsetName(rcc_context ctx, rcc_charset_id charset_id); -const char *rccGetAutoCharsetName(rcc_context ctx, rcc_autocharset_id charset_id); rcc_engine_id rccGetEngineByName(rcc_context ctx, const char *name); rcc_charset_id rccGetCharsetByName(rcc_context ctx, const char *name); -rcc_autocharset_id rccGetAutoCharsetByName(rcc_context ctx, const char *name); rcc_engine_id rccGetSelectedEngine(rcc_context ctx); const char *rccGetSelectedEngineName(rcc_context ctx); @@ -269,17 +820,72 @@ rcc_class_ptr *rccGetClassList(rcc_context ctx); ************************ RCC_STRING Manipulations ****************************** *******************************************************************************/ /* string.c */ +/** + * Intermediate string format. RCC_string can be manipulated as standard NULL terminated string. + * However it contains small header with information about string language. All strings are + * encoded using UTF-8 encoding. + */ typedef char *rcc_string; +/** + * Intermediate string format. RCC_string can be manipulated as standard NULL terminated string. + * However it contains small header with information about string language. All strings are + * encoded using UTF-8 encoding. + */ typedef const char *rcc_const_string; +/** + * Check string header and verify if it is really correct #rcc_string. + * + * @param str is verifying string + */ size_t rccStringCheck(const char *str); +/** + * Check string header and verify if it is really correct #rcc_string. + * + * @param str is verifying string + * @param len is preciese size of str. + * @return size of string in bytes or -1 if check failed + */ size_t rccStringSizedCheck(const char *str, size_t len); +/** + * Extract language from #rcc_string. + * + * @param str is #rcc_string + * @return size of string in bytes or -1 if check failed + */ rcc_language_id rccStringGetLanguage(rcc_const_string str); +/** + * Returns pointer on UTF-8 string kept inside of #rcc_string. + * + * @param str is #rcc_string + * @return pointer on constant string or NULL in the case of error + */ const char *rccStringGetString(rcc_const_string str); +/** + * Extract UTF-8 string from #rcc_string. + * + * @param str is #rcc_string + * @return pointer on string or NULL in the case of error. The string should be freed by the caller. + */ char *rccStringExtractString(rcc_const_string str); +/** + * If str is #rcc_string function will return pointer on UTF-8 string kept inside, otherwise + * pointer on the passed string is returned. + * + * @param str is null-terminated string + * @return pointer on constant string + */ const char *rccGetString(const char *str); +/** + * If str is #rcc_string function will return pointer on UTF-8 string kept inside, otherwise + * pointer on the passed string is returned. + * + * @param str is string (perhaps not zero terminated) + * @param len is exact length of string or 0 (in this case length will be computed using 'strlen' + * @return pointer on constant string + */ const char *rccSizedGetString(const char *str, size_t len); int rccStringCmp(const char *str1, const char *str2); @@ -290,23 +896,160 @@ int rccStringNCaseCmp(const char *str1, const char *str2, size_t n); /******************************************************************************* ******************************** Recoding ************************************** *******************************************************************************/ +/** + * recoding context + */ typedef struct rcc_iconv_t *rcc_iconv; /* rcciconv.c */ +/** + * Open recoding context. + * + * @param from is source encoding + * @param to is destination encoding + * @result + * - NULL if no recoding is required + * - Pointer on initialized context if successful + * - Pointer on errnous context in the case of error + */ rcc_iconv rccIConvOpen(const char *from, const char *to); +/** + * Close recoding context. + * + * @param icnv is recoding context */ void rccIConvClose(rcc_iconv icnv); +/** + * Recodes chunk of data. + * + * @param icnv is recoding context + * @param outbuf is preallocated output buffer + * @param outsize is size of output buffer (striped string will be returned if buffer to small) + * @param buf is data for recoding + * @param len is size of data + * @return number of recoded bytes in output buffer or -1 in the case of error + */ size_t rccIConvRecode(rcc_iconv icnv, char *outbuf, size_t outsize, const char *buf, size_t size); /* recode.c */ +/** + * Recode string from specified encoding class to #rcc_string. Encoding detection engines and + * recoding cache are used (if possible) to detect original 'buf' encoding. Otherwise the + * preconfigured encoding of class is assumed. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param class_id is encoding class + * @param buf is original string (perhaps not zero terminated) + * @param len is exact size of string or 0. In the last case the size is determined using 'strlen' function. + * @result is recoded string or NULL if recoding is not required or failed. It is up to the caller to free memory. + */ rcc_string rccSizedFrom(rcc_context ctx, rcc_class_id class_id, const char *buf, size_t len); +/** + * Recode string from #rcc_string to specified encoding class. If encoding class is of + * 'File System' type, the autoprobing for file names can be performed. In the other cases + * the rcc_string will be recoded in preconfigured class encoding. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param class_id is encoding class + * @param buf is original zero terminated string + * @param rlen in rlen the size of recoded string will be returned. + * @result is recoded string or NULL if recoding is not required or failed. It is up to the caller to free memory. + */ char *rccSizedTo(rcc_context ctx, rcc_class_id class_id, const rcc_string buf, size_t *rlen); +/** + * Recode string between different encoding classes. The conversion is relays on rccSizedFrom + * and rccSizedTo functions. + * @see rccSizedFrom + * @see rccSizedTo + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param from is source encoding class + * @param to is destination encoding class + * @param buf is original string (perhaps not zero terminated) + * @param len is exact size of string or 0. In the last case the size is determined using 'strlen' function. + * @param rlen in rlen the size of recoded string will be returned. + * @result is recoded string or NULL if recoding is not required or failed. It is up to the caller to free memory. + */ char *rccSizedRecode(rcc_context ctx, rcc_class_id from, rcc_class_id to, const char *buf, size_t len, size_t *rlen); +/** + * Recode file name between different encoding classes. Normally, should be used to convert + * string from the file list to real file system names. The autoprobing of names is enabled + * depending on the output encoding class configuration and current options. + * @see rcc_class_t + * @see rcc_class_type_t + * @see rcc_option_t + + * The conversion is partly relays on rccSizedFrom. + * @see rccSizedFrom + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param from is source encoding class + * @param to is destination encoding class + * @param buf is original file name + * @result is recoded file name or NULL if recoding is not required or failed. It is up to the caller to free memory. + */ char *rccFS(rcc_context ctx, rcc_class_id from, rcc_class_id to, const char *fspath, const char *path, const char *filename); +/** + * Recode string from specified encoding to #rcc_string. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param charset is source encoding + * @param buf is original string (perhaps not zero terminated) + * @param len is exact size of string or 0. In the last case the size is determined using 'strlen' function. + * @result is recoded string or NULL if recoding is not required or failed. It is up to the caller to free memory. + */ rcc_string rccSizedFromCharset(rcc_context ctx, const char *charset, const char *buf, size_t len); +/** + * Recode string from #rcc_string to specified encoding. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param charset is destination encoding + * @param buf is original zero terminated string + * @param rlen in rlen the size of recoded string will be returned. + * @result is recoded string or NULL if recoding is not required or failed. It is up to the caller to free memory. + */ char *rccSizedToCharset(rcc_context ctx, const char *charset, const rcc_string buf, size_t *rlen); +/** + * Recode string between specified encoding class and encoding. + * + * The conversion is partly relays on rccSizedFrom. + * @see rccSizedFrom + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param class_id is source encoding class + * @param charset is destination encoding + * @param buf is original string (perhaps not zero terminated) + * @param len is exact size of string or 0. In the last case the size is determined using 'strlen' function. + * @param rlen in rlen the size of recoded string will be returned. + * @result is recoded string or NULL if recoding is not required or failed. It is up to the caller to free memory. + */ char *rccSizedRecodeToCharset(rcc_context ctx, rcc_class_id class_id, const char *charset, const rcc_string buf, size_t len, size_t *rlen); +/** + * Recode string between specified encoding and encoding class. + * + * The conversion is partly relays on rccSizedTo + * @see rccSizedTo + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param class_id is destination encoding class + * @param charset is source encoding + * @param buf is original string (perhaps not zero terminated) + * @param len is exact size of string or 0. In the last case the size is determined using 'strlen' function. + * @param rlen in rlen the size of recoded string will be returned. + * @result is recoded string or NULL if recoding is not required or failed. It is up to the caller to free memory. + */ char *rccSizedRecodeFromCharset(rcc_context ctx, rcc_class_id class_id, const char *charset, const char *buf, size_t len, size_t *rlen); +/** + * Recode string between specified encodings. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param from is source encoding + * @param to is destination encoding + * @param buf is original string (perhaps not zero terminated) + * @param len is exact size of string or 0. In the last case the size is determined using 'strlen' function. + * @param rlen in rlen the size of recoded string will be returned. + * @result is recoded string or NULL if recoding is not required or failed. It is up to the caller to free memory. + */ char *rccSizedRecodeCharsets(rcc_context ctx, const char *from, const char *to, const char *buf, size_t len, size_t *rlen); @@ -326,9 +1069,23 @@ char *rccSizedRecodeCharsets(rcc_context ctx, const char *from, const char *to, /* xml.c */ typedef void *rcc_config; - rcc_config rccGetConfiguration(); + +/** + * Save Configuration. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param name is configuration file name ( can be shared between multiple applications! ) + * @return non-zero in the case of errors. + */ int rccSave(rcc_context ctx, const char *name); +/** + * Load Configuration. + * + * @param ctx is working context ( or default one if NULL supplied ) + * @param name is configuration file name ( can be shared between multiple applications! ) + * @return non-zero in the case of errors. + */ int rccLoad(rcc_context ctx, const char *name); /******************************************************************************* @@ -345,16 +1102,34 @@ rcc_context rccEngineGetRccContext(rcc_engine_context ctx); **************************** Configuration ************************************* *******************************************************************************/ +/** + * The Berkley DB support is compiled in + */ #define RCC_CC_FLAG_HAVE_BERKLEY_DB 0x01 +/** + * The dynamic engine plugins support is compiled in + */ #define RCC_CC_FLAG_HAVE_DYNAMIC_ENGINES 0x02 +/** + * Enca engine is compiled in + */ #define RCC_CC_FLAG_HAVE_ENCA 0x04 +/** + * LibRCD engine is compiled in + */ #define RCC_CC_FLAG_HAVE_RCD 0x08 +/** + * The library build environment is represented by this structure + */ struct rcc_compiled_configuration_t { - unsigned long flags; + unsigned long flags; /**< compilation flags */ }; typedef struct rcc_compiled_configuration_t rcc_compiled_configuration_s; typedef const struct rcc_compiled_configuration_t *rcc_compiled_configuration; +/** + * Get information about library compilation environment + */ rcc_compiled_configuration rccGetCompiledConfiguration(); int rccLocaleGetClassByName(const char *locale); |