From 055bdab4f515b1e93155fccbe03fac43a007aa0e Mon Sep 17 00:00:00 2001
From: "Suren A. Chilingaryan" <csa@dside.dyndns.org>
Date: Mon, 18 Jul 2005 22:00:54 +0000
Subject: Documentation - Some small doxygen descriptions are added
---
docs/LibRCC.sxd | Bin 0 -> 11575 bytes
docs/LibRCC.sxd.pdf | Bin 0 -> 54748 bytes
docs/api/Doxyfile | 210 +++++++++++++
src/librcc.c | 4 +-
src/librcc.h | 891 ++++++++++++++++++++++++++++++++++++++++++++++++----
src/lngconfig.h | 6 +
ui/librccui.h | 43 +++
7 files changed, 1094 insertions(+), 60 deletions(-)
create mode 100644 docs/LibRCC.sxd
create mode 100644 docs/LibRCC.sxd.pdf
create mode 100644 docs/api/Doxyfile
diff --git a/docs/LibRCC.sxd b/docs/LibRCC.sxd
new file mode 100644
index 0000000..4140f7e
Binary files /dev/null and b/docs/LibRCC.sxd differ
diff --git a/docs/LibRCC.sxd.pdf b/docs/LibRCC.sxd.pdf
new file mode 100644
index 0000000..bafee99
Binary files /dev/null and b/docs/LibRCC.sxd.pdf differ
diff --git a/docs/api/Doxyfile b/docs/api/Doxyfile
new file mode 100644
index 0000000..34552b1
--- /dev/null
+++ b/docs/api/Doxyfile
@@ -0,0 +1,210 @@
+# Doxyfile 1.3.3
+
+#---------------------------------------------------------------------------
+# General configuration options
+#---------------------------------------------------------------------------
+PROJECT_NAME = LibRCC
+PROJECT_NUMBER =
+OUTPUT_DIRECTORY = /root/xmms/librcc--main--0.1--patch-9/docs/api/
+OUTPUT_LANGUAGE = English
+USE_WINDOWS_ENCODING = NO
+EXTRACT_ALL = YES
+EXTRACT_PRIVATE = NO
+EXTRACT_STATIC = NO
+EXTRACT_LOCAL_CLASSES = YES
+HIDE_UNDOC_MEMBERS = NO
+HIDE_UNDOC_CLASSES = NO
+HIDE_FRIEND_COMPOUNDS = NO
+HIDE_IN_BODY_DOCS = NO
+BRIEF_MEMBER_DESC = YES
+REPEAT_BRIEF = YES
+ALWAYS_DETAILED_SEC = NO
+INLINE_INHERITED_MEMB = NO
+FULL_PATH_NAMES = NO
+STRIP_FROM_PATH =
+INTERNAL_DOCS = NO
+CASE_SENSE_NAMES = YES
+SHORT_NAMES = NO
+HIDE_SCOPE_NAMES = NO
+SHOW_INCLUDE_FILES = YES
+JAVADOC_AUTOBRIEF = NO
+MULTILINE_CPP_IS_BRIEF = NO
+DETAILS_AT_TOP = NO
+INHERIT_DOCS = YES
+INLINE_INFO = YES
+SORT_MEMBER_DOCS = YES
+DISTRIBUTE_GROUP_DOC = NO
+TAB_SIZE = 8
+GENERATE_TODOLIST = YES
+GENERATE_TESTLIST = YES
+GENERATE_BUGLIST = YES
+GENERATE_DEPRECATEDLIST= YES
+ALIASES =
+ENABLED_SECTIONS =
+MAX_INITIALIZER_LINES = 30
+OPTIMIZE_OUTPUT_FOR_C = NO
+OPTIMIZE_OUTPUT_JAVA = NO
+SHOW_USED_FILES = YES
+SUBGROUPING = YES
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET = NO
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_FORMAT = "$file:$line: $text"
+WARN_LOGFILE =
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT = /root/xmms/librcc--main--0.1--patch-9/src/ \
+ /root/xmms/librcc--main--0.1--patch-9/ui/
+FILE_PATTERNS = librcc.h \
+ librccui.h
+RECURSIVE = NO
+EXCLUDE =
+EXCLUDE_SYMLINKS = NO
+EXCLUDE_PATTERNS =
+EXAMPLE_PATH =
+EXAMPLE_PATTERNS =
+EXAMPLE_RECURSIVE = NO
+IMAGE_PATH =
+INPUT_FILTER =
+FILTER_SOURCE_FILES = NO
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER = NO
+INLINE_SOURCES = NO
+STRIP_CODE_COMMENTS = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION = YES
+VERBATIM_HEADERS = YES
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX = NO
+COLS_IN_ALPHA_INDEX = 5
+IGNORE_PREFIX =
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML = YES
+HTML_OUTPUT = html
+HTML_FILE_EXTENSION = .html
+HTML_HEADER =
+HTML_FOOTER =
+HTML_STYLESHEET =
+HTML_ALIGN_MEMBERS = YES
+GENERATE_HTMLHELP = NO
+CHM_FILE =
+HHC_LOCATION =
+GENERATE_CHI = NO
+BINARY_TOC = NO
+TOC_EXPAND = NO
+DISABLE_INDEX = NO
+ENUM_VALUES_PER_LINE = 4
+GENERATE_TREEVIEW = NO
+TREEVIEW_WIDTH = 250
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX = NO
+LATEX_OUTPUT = latex
+LATEX_CMD_NAME = latex
+MAKEINDEX_CMD_NAME = makeindex
+COMPACT_LATEX = NO
+PAPER_TYPE = a4wide
+EXTRA_PACKAGES =
+LATEX_HEADER =
+PDF_HYPERLINKS = NO
+USE_PDFLATEX = NO
+LATEX_BATCHMODE = NO
+LATEX_HIDE_INDICES = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF = NO
+RTF_OUTPUT = rtf
+COMPACT_RTF = NO
+RTF_HYPERLINKS = NO
+RTF_STYLESHEET_FILE =
+RTF_EXTENSIONS_FILE =
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN = NO
+MAN_OUTPUT = man
+MAN_EXTENSION = .3
+MAN_LINKS = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML = NO
+XML_OUTPUT = xml
+XML_SCHEMA =
+XML_DTD =
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD = NO
+PERLMOD_LATEX = NO
+PERLMOD_PRETTY = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = NO
+EXPAND_ONLY_PREDEF = NO
+SEARCH_INCLUDES = YES
+INCLUDE_PATH =
+INCLUDE_FILE_PATTERNS =
+PREDEFINED =
+EXPAND_AS_DEFINED =
+SKIP_FUNCTION_MACROS = YES
+#---------------------------------------------------------------------------
+# Configuration::addtions related to external references
+#---------------------------------------------------------------------------
+TAGFILES =
+GENERATE_TAGFILE =
+ALLEXTERNALS = NO
+EXTERNAL_GROUPS = YES
+PERL_PATH = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS = YES
+HIDE_UNDOC_RELATIONS = YES
+HAVE_DOT = NO
+CLASS_GRAPH = YES
+COLLABORATION_GRAPH = YES
+UML_LOOK = NO
+TEMPLATE_RELATIONS = NO
+INCLUDE_GRAPH = YES
+INCLUDED_BY_GRAPH = YES
+CALL_GRAPH = NO
+GRAPHICAL_HIERARCHY = YES
+DOT_IMAGE_FORMAT = png
+DOT_PATH =
+DOTFILE_DIRS =
+MAX_DOT_GRAPH_WIDTH = 1024
+MAX_DOT_GRAPH_HEIGHT = 1024
+MAX_DOT_GRAPH_DEPTH = 0
+GENERATE_LEGEND = YES
+DOT_CLEANUP = YES
+#---------------------------------------------------------------------------
+# Configuration::addtions related to the search engine
+#---------------------------------------------------------------------------
+SEARCHENGINE = NO
+CGI_NAME = search.cgi
+CGI_URL =
+DOC_URL =
+DOC_ABSPATH =
+BIN_ABSPATH = /usr/local/bin/
+EXT_DOC_PATHS =
diff --git a/src/librcc.c b/src/librcc.c
index 0a66e9a..ec2df39 100644
--- a/src/librcc.c
+++ b/src/librcc.c
@@ -117,7 +117,7 @@ rcc_context rccCreateContext(const char *locale_variable, unsigned int max_langu
if (!initialized) return NULL;
if (!max_languages) {
- if (flags&RCC_NO_DEFAULT_CONFIGURATION) max_languages = RCC_MAX_LANGUAGES;
+ if (flags&RCC_FLAG_NO_DEFAULT_CONFIGURATION) max_languages = RCC_MAX_LANGUAGES;
else {
for (i=0;rcc_default_languages[i].sn;i++);
max_languages = i;
@@ -196,7 +196,7 @@ rcc_context rccCreateContext(const char *locale_variable, unsigned int max_langu
for (i=0;i<RCC_MAX_OPTIONS;i++) rccOptionSetDefault(ctx, (rcc_option)i);
- if (flags&RCC_NO_DEFAULT_CONFIGURATION) {
+ if (flags&RCC_FLAG_NO_DEFAULT_CONFIGURATION) {
rccRegisterLanguage(ctx, rcc_default_languages);
ctx->current_config = NULL;
} else {
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);
diff --git a/src/lngconfig.h b/src/lngconfig.h
index edfd1d1..b136905 100644
--- a/src/lngconfig.h
+++ b/src/lngconfig.h
@@ -33,4 +33,10 @@ int rccConfigConfigure(rcc_language_config config);
rcc_charset_id rccConfigGetLocaleUnicodeCharset(rcc_language_config config, const char *locale_variable);
+const char *rccConfigGetAutoCharsetName(rcc_language_config config, rcc_autocharset_id charset_id);
+rcc_autocharset_id rccConfigGetAutoCharsetByName(rcc_language_config config, const char *name);
+
+const char *rccGetAutoCharsetName(rcc_context ctx, rcc_autocharset_id charset_id);
+rcc_autocharset_id rccGetAutoCharsetByName(rcc_context ctx, const char *name);
+
#endif /* _RCC_LNGCONFIG_H */
diff --git a/ui/librccui.h b/ui/librccui.h
index e526c0a..cb17649 100644
--- a/ui/librccui.h
+++ b/ui/librccui.h
@@ -72,14 +72,49 @@ typedef void *rcc_ui_box;
typedef void *rcc_ui_frame;
typedef void *rcc_ui_page;
+/**
+ * Init RCC User Interface Library. This function should be called prior to any other UI functions
+ */
int rccUiInit();
+/**
+ * Free resources used by UI library.
+ *
+ * @return non-zero value in the case of error.
+ */
void rccUiFree();
+/**
+ * Create UI context and attach it to RCC working context. It isn't permited to attach to single
+ * working context several UI's.
+ *
+ * @param rccctx is pointer on the RCC working context.
+ * @return pointer on newly created UI context or NULL in the case of errors.
+ */
rcc_ui_context rccUiCreateContext(rcc_context rccctx);
+/**
+ * Destroy UI context and free all memory used.
+ *
+ * @param ctx is UI context to be destroyed.
+ */
void rccUiFreeContext(rcc_ui_context ctx);
+/**
+ * Restores current language UI menu values from #rcc_context.
+ *
+ * @param ctx is UI context.
+ */
int rccUiRestoreLanguage(rcc_ui_context ctx);
+/**
+ * Restores complete UI configuration from #rcc_context.
+ *
+ * @param ctx is UI context.
+ */
int rccUiRestore(rcc_ui_context ctx);
+/**
+ * Updates #rcc_context with user adjusted options from UI configuration.
+ *
+ * @param ctx is UI context.
+ */
int rccUiUpdate(rcc_ui_context ctx);
rcc_ui_widget rccUiGetLanguageMenu(rcc_ui_context ctx);
@@ -96,6 +131,14 @@ rcc_ui_frame rccUiGetLanguageFrame(rcc_ui_context ctx, rcc_ui_language_frame_nam
rcc_ui_frame rccUiGetCharsetsFrame(rcc_ui_context ctx, rcc_ui_charset_frame_name *name);
rcc_ui_frame rccUiGetEngineFrame(rcc_ui_context ctx, rcc_ui_engine_frame_name *name);
+/**
+ * Get UI option page which can be integrated in application GUI. It is up on the caller
+ * to use and destroy returned page.
+ *
+ * @param ctx is UI context.
+ * @param name provides titles which should be used on the page or NULL to use defaults.
+ * @result is created UI page or NULL in the case of errors.
+ */
rcc_ui_page rccUiGetPage(rcc_ui_context ctx, rcc_ui_page_name *name);
#ifdef __cplusplus
--
cgit v1.2.3