XFLib 0.1.7 | XF management library |
XFLib | Основы | Анализ | Модификация | Локализация | Безопасность | Конфигурирование | Ссылки |
Содержание |
XFLib |
Это руководство является документацией к библиотеке XFLib, позволяющей работать с данными в новом универсальном и легком формате XF.
XF (eXtensible Format) - универсальный, легкий и переносимый формат для хранения данных в текстовом виде, который просто воспринимается человеком и обрабатывается программами.
XF переносим и не зависит от программного и аппаратного обеспечения. Документы XF могут быть прочитаны программой на любом языке программирования, поддерживающем эту технологию.
В отличие от XML, XF не предназначен для разметки текстовых документов. XF - это универсальный формат для хранения данных с произвольной структурой. Текущая версия формата - 1.0.
XFLib - это библиотека для чтения, модификации и генерирования XF-документов, написанная на ANSI C. XFLib компактна и быстра, легко переносима, работает в Windows и Linux, полностью поддерживает стандарт Unicode. XFLib бесплатна и открыта, распространяется под лицензией LGPL.
XFLib уже достаточно быстра и стабильна для практического применения. Если вы можете сделать что-либо для развития XF и XFLib, свяжитесь с автором.
Основные возможности XFLib:
Ваше приложение использует XF или XFLib? Напишите нам, и ваше приложение появится в списке проектов, использующих XF/XFLib.
Контакты: Волков Максим mailto:max@xfhome.org
Компиляция и сборка |
Для компиляции и сборки XFLib под Linux используется компилятор GCC, который есть в любом дистрибутиве Linux. Распакуйте архив с исходными текстами XFLib. Для сборки библиотеки (xflib.so) необходимо зайти в каталог lib и набрать команду make:
# cd lib # make
Для сборки примеров в каталоге с отдельным примером (samples/*) набирается команда make.
Проект для сборки динамической библиотеки (xflib.dll) находится в папке win32/vc6/xflib. Проекты для сборки примеров - в папках win32/vc6/*.
Проект для сборки динамической библиотеки (xflib.dll) находится в папке win32/bcb5/xflib. Проекты для сборки примеров - в папках win32/bcb5/*. Результаты сборки (exe, dll) будут помещены в папку win32/bcb5/build. Перед запуском примеров необходимо собрать XFLib (xflib.dll).
Скрипт для сборки динамической библиотеки (xflib.dll) и примеров находится в папке win32/gcc (make.bat). Для его работы необходимо чтобы в системе был установлен путь до компилятора (gcc.exe).
Замечание!!! В текущей версии DLL, скомпилированная при помощи Visual C++, не работает с приложениями, написаннами в Borland C++.
Основы |
Основной объект работы с XF - это документ. Документ - это файл XF. Его можно загрузить в память (при помощи парсера), модифицировать, сохранить. В XFLib документ называется картой. Каждая карта состоит из элементов (нодов, nodes). Карта представлена структурой типа xfMap, элемент - структурой типа xfNode. XFLib работает с этими структурами данных по указателю.
Основные типы данных XFLib:
Обратите внимание на то, что xfChar - это 16-битный "широкий" символ (аналог wchar_t). XFLib повсеместно использует строки широких символов (кроме имён файлов в функциях xfReadFile/xfWriterFile), потому строки необходимо записывать с префиксом L: L"test", L"xf document", либо используя специальный макрос XFS(): XFS("test"), XFS("xf document").
Коды завершения функций (код 1 зарезервирован):
Макросы для логических констант:
Основные макросы XFLib:
Основные определения, связанные с XFLib, находятся в файле "xf.h", находящемся в каталоге с исходными текстами XFLib ("lib"). Функции API XFLib, используемые в приложениях, объявлены в "xf_api.h". Таим образом, в приложениях, использующих XFLib, требуется включать "xf.h" и "xf_api.h".
xfInt xfStart();
Инициализирует XFLib. Возвращает XFE_OK. Коды ошибок возможно будут использоваться со временем.
xfVoid xfStop();
Завершает работу XFLib.
xfInt xfVersion();
Получает номер версии XFLib. Формат номера версии: 32-битное целое число - [1 байт - номер версии] [1 байт - номер подверсии] [1 байт - номер релиза] [1 байт - ноль для стабильной версии, ненулевое значение для тестовой версии]. Номер релиза имеет особое значение: нечётные релизы - тестовые, а чётные - стабильные и рекоммендуемые к использованию.
xfChar* xfInfo();
Возвращает строку с номером версии XFLib, например: "XFLib 0.1.1".
xfMap* xfCreate();
Создаёт новую карту XF. Возвращает указатель на созданную карту. Если недостаточно памяти для создания - возвращает XF_NULL.
xfVoid xfDestroy(xfMap *map);
Освобождает карту map. Освобождаемая карта должна быть выделена через xfCreate().
xfInt xfReadFile(xfMap *map,xfNChar *filename);
Считывает документ XF из файла в карту. Если карта не пуста, то считываемый документ и содержимое карты объединяются. Возвращает значение:
В случае ошибки документ может быть не разобран, либо разобран частично (и частично занесён в карту).
Обратите внимание: filename - строка обычных 8-битных символов.
xfInt xfReadString(xfMap *map,xfChar *string);
Считывает документ XF из строки в карту. Если карта не пуста, то считываемый документ и содержимое карты объединяются. Возвращает значение:
В случае ошибки документ может быть не разобран, либо разобран частично (и частично занесён в карту).
xfInt xfWriteFile(xfMap *map,xfNChar *filename);
Записывает в файл filename карту map. Возвращает значения:
По умолчанию файлы записываются в 8-битной кодировке Unicode (UTF-8). Для выбора других поддерживаемых кодировок (UTF-8, UTF-16) предварительно необохдимо выбрать кодироваку функцией xfSetDocEncoding().
Обратите внимание: filename - строка обычных 8-битных символов.
ВНИМАНИЕ!!! Если вы хотите сохранять документы в кодировке ASCII, ознакомьтесь с замечанием во избежании проблем.
xfInt xfWriteString(xfMap *map,xfChar *string,xfInt maxSize);
Записывает в строку string карту map. При этом будет записано не более MaxSize символов.
xfChar* xfGetError(xfMap *map);
Возвращает указатель строку с текстом сообщения об ошибке, произошедшем при парсинге документа в карту map. Используется совместно с xfReadFile() и xfReadString().
xfChar* xfSetError(xfMap *map,xfChar *error);
Устанавливает строку error как сообщение об ошибке для карты map. Возвращает указатель на созданную строку с сообщением.
xfInt xfGetErrorLine(xfMap *map);
Возвращает номер строки файла исходного текста, в которой произошла ошибка. Используется совместно с xfReadFile() и xfReadString().
xfInt xfGetErrorLine(xfMap *map,xfInt line);
Устанавливает номер строки файла исходного текста, в которой произошла ошибка. Возвращает заданный номер строки.
xfInt xfGetErrorCol(xfMap *map);
Возвращает номер символа в строке файла исходного текста, в которой произошла ошибка. Используется совместно с xfReadFile() и xfReadString().
xfInt xfGetErrorCol(xfMap *map,xfInt col);
Устанавливает номер символа в строке файла исходного текста, в которой произошла ошибка. Возвращает заданный номер символа.
Анализ данных |
xfNode* xfEnter(xfNode *parent,xfChar *name);
Возвращает указатель на элемент с именем name, находящийся внутри элемента parent.
xfNode* xfEnterPath(xfNode *node,xfChar *path);
Возвращает указатель на элемент, путь до которого начиная с элемента node указан в path. Пусть записывается в виду, подобном синтаксису XF: возможно заключать имена со специальными символами (отличными от A..Z, a..z, _ и -) в двойные кавычки, использовать escape-последовательности. Для задания абсолютного пути в карте можно исопльзовать указатель на корень дерева: node = xfEnterPath(map->root,"xf version"); node2 = xfEnterPath(element,"price currency").
xfNode* xfParent(xfNode *node);
Возвращает указатель на родителя элемента node. Если элемент node глобальный (т.е. не имеет родителя), то возвращает XF_NULL (нулевой указатель).
xfNode* xfChild(xfNode *node);
Возвращает указатель первый дочерний элемент элемента node. Если элемент node пуст (не содержит потомков), функция возвращает XF_NULL (нулевой указатель).
xfNode* xfLastChild(xfNode *node);
Возвращает указатель последний дочерний элемент элемента node. Если элемент node пуст (не содержит потомков), функция возвращает XF_NULL (нулевой указатель).
xfNode* xfNext(xfNode *node);
Возвращает указатель на следующий элемент по предыдущему node. Используется совместно в xfChild() - xfChild() получает указатель на первого потомка, xfNext - на следующего (который определяется по указателю на предыдущий node). Если предыдущий элемент оказался последним, функция возвращает XF_NULL (нулевой указатель).
xfNode* xfPrev(xfNode *node);
Возвращает указатель на элемент, находящийся перед node. Используется совместно в xfLastChild() для обхода потомков в обратном порядке - xfLastChild() получает указатель на последнего потомка, xfPrev - на каждого очередного. Если элемент node оказался первым, функция возвращает XF_NULL (нулевой указатель).
xfInt xfIsRoot(xfNode *node);
Проверяет, ввляется ли элемент node глобальным. Возвращает:
xfChar* xfGet(xfNode *node);
Возвращает указатель на строку, содержащую значение элемента node. Если элемент не содержит значение, возвращает XF_NULL (нулевой указатель).
xfChar* xfGetClass(xfNode *node);
Возвращает указатель на строку, содержащую название класса элемента node. Если элемент не содержит значение, возвращает XF_NULL (нулевой указатель).
xfInt xfNumChildren(xfNode *node);
Возвращает число потомков элемента node.
Пример. Имеется документ XF (countries.xf):
xf version = "1.0"; xf class = "Test"; country { "Russia" { language = "Russian"; population = "140"; } "Ukraine" { language = "Ukrainian"; population = "50"; } }
Получим список государств в документе:
#include <stdio.h> #include "xflib/lib/xf.h" #include "xflib/lib/xf_api.h" int main(int argc, char* argv[]) { xfMap *m; xfNode *n; m = xfCreate(); xfReadFile(m,"countries.xf"); // загружаем XF из файла n = xfEnter(m->root,L"country"); // входим в элемент country n = xfChild(n); // получаем указатель первое государство while (n) { printf("%S\n",xfName(n)); // выводим название государства n = xfNext(n); // получаем указатель на следующее государство } xfDestroy(m); return 0; }
Обратите внимание: для корректного вывода строк в printf() используется спецификатор %S (вместо %s) для широких строк (xfChar*).
Программа выведет на экран:
Russia Ukraine
А теперь выведем информацию о каждом государстве
#include <stdio.h> #include "xflib/lib/xf.h" #include "xflib/lib/xf_api.h" int main(int argc, char* argv[]) { xfMap *m; xfNode *n; m = xfCreate(); xfReadFile(m,"countries.xf"); n = xfEnter(m->root,L"country"); n = xfChild(n); while (n) { printf("--- %S ---\n",xfName(n)); printf("language: %S\n",xfGet(xfEnter(n,L"language"))); printf("population: %S millions\n\n",xfGet(xfEnter(n,L"population"))); n = xfNext(n); } xfDestroy(m); return 0; }
Программа выведет на экран:
--- Russia --- Language: Russian Population: 150 millions --- Ukraine --- Language: Ukrainian Population: 50 millions
Модификация данных |
xfNode* xfAdd(xfNode *parent,xfChar *name,xfChar *value,xfChar *Class);
Добавляет к элементу parent дочерний элемент с именем name, устанавливая значение создаваемого элемента (value) и его класс. Если такой элемент с таким именем уже существует среди непосредственных потомков parent, просто меняет его значение на value и класс на Class. Возвращает: указатель на созданный или существующий элемент (в случае успеха) или XF_NULL - нулевой указатель (в случае нехватки памяти).
xfNode* xfAddPath(xfNode *node,xfChar *path);
Создаёт путь path, начиная с элемента. Пусть записывается в виде, идентичном применяемом в функции xfEnterPath(). Возвращает указатель на созданный путь (элемент по созданному пути) либо указатель на существовавший ранее путь (если такой уже существовал). В случае нехватки памяти возвращает XF_NULL (нулевой указатель).
xfVoid xfRemove(xfNode *node);
Удаляет элемент xfRemove и все его потомки, освобождая память. Если node - нулевой указатель, ничего не делает.
xfVoid xfRemove(xfNode *node);
Удаляет элемент xfRemove и все его потомки, освобождая память.
xfChar* xfSet(xfNode *node,xfChar *value);
Устанавливает значение элемента node в value. Возвращает указатель на значение элемента (в случае успеха), либо XF_NULL (в случае нехватки памяти).
xfChar* xfSetClass(xfNode *node,xfChar *value);
Устанавливает класс элемента node в Class. Возвращает указатель на название класса класс элемента (в случае успеха), либо XF_NULL (в случае нехватки памяти).
Сериализация |
Сериализация - это возможность, позволяющая в одном цикле обходить древовидные структуры данных. Сериализация существенно упрощает обработку сложных структур данных. В качестве средства сериализации в XFLib используются итераторы. Итератор имеет указатель на элемент, начиная с которого будет произведена сериализация (итерация). Итератор будет обрабатывать элементы внутри заданного элемент, причём обработка может быть как рекурсивной, там и обычной.
Пример сериализации документа:
element { 1 { a; b; c; } 2 { a; b; c; } 3 { x; y; z; } 4 { aaa { bbb; ccc; ddd; } zzz; } }
Простая сериализация элемента "element" выдаёт последовательность элементов: 1 2 3 4.
Рекурсивная сериализация элемента "element" выдаёт последовательность элементов: 1 a b c 2 a b c 3 x y z 4 aaa bbb ccc ddd zzz.
xfIterator* xfCreateIterator();
Создаёт новый итератор. Возвращает указатель на созданный итератор (в случае успеха), либо XF_NULL (недостаточно памяти).
xfVoid xfDestroyIterator(xfIterator *iterator);
Уничтожает ранее созданный итератор iterator и освобождает всю используемую им память.
xfVoid xfSetIteration(xfIterator *iterator,xfNode *node,xfInt recursive);
Устанавливает элемент, начиная с которого будет производиться итерация. При установке обнуляются счётчики итераций и уровня. Если recursive - ненулевое значение, то итерации будут производиться рекурсивно.
xfNode* xfNextIteration(xfIterator *iterator);
Возвращает указатель на очередной элемент итерации, производимой итератором iterator. Если итерация окончена (нет больше элементов), возвращает XF_NULL.
xfInt xfIterationCounter(xfIterator *iterator);
Возвращает номер очередной итерации (аналог счётчика цикла). Изначально номер итерации - ноль, он сбрасывается функциями xfCreateItеrator() и xfSetIteration().
xfInt xfIterationLevel(xfIterator *iterator);
Возвращает уровень очередной итерации (аналог счётчика цикла). Изначально номер итерации - ноль, он сбрасывается функциями xfCreateItеrator() и xfSetIteration(). Для простой (нерекурсивной) итерации уровень всегда равен нулю.
Атрибуты документа |
Каждый документ XF может иметь набор атрибутов, характеризующих его.
Атрибут | Значение | Функция получения | Функция изменения |
xf version | Версия формата XF | xfInt xfGetDocVersion(xfMap *map); | xfChar* xfSetDocVersion(xfMap *map,xfChar *value); |
xf class | Класс документа | xfChar *xfGetDocClass(xfMap *map); | xfChar* xfSetDocClass(xfMap *map,xfChar *value); |
xf comment | Комментарий к документу | xfChar *xfGetDocComment(xfMap *map); | xfChar* xfSetDocComment(xfMap *map,xfChar *value); |
кодировка документа | Название кодировки документа | xfInt xfGetDocEncoding(xfMap *map); | xfVoid xfSetDocEncoding(xfMap *map,xfInt encoding); |
текстовый комментарий к документу | Текстовый комментарий к документу | xfChar *xfGetDocHeader(xfMap *map); | xfxfChar* xfSetDocHeader(xfMap *map,xfChar *header); |
Функции получения аттрибутов возвращают 0 (XF_NULL) если аттрибут не задан. Функции установки аттрибутов возвращают XFE_OK (в случае успеха), XFE_MEMORY (недостаточно памяти), XFE_LIMIT (слишком много элементов в карте).
Возможные кодировки для функций xfGetDocEncoding()/xfSetDocEncoding():
ВНИМАНИЕ!!! Не рекоммендуется сохранять документы, содержащие не-ASCII символы (нестандартные, символы различных языков) в кодировке ASCII. Если всё таки необходимо использовать формат ASCII, для таких документов НЕОБХОДИМО установить опцию сохранения xfOptionCharCodes (сохранение нестандартных символов в шестнадцатеричном виде). В противном случае нестандартные символы превратятся в знаки вопроса!!!
Для добавления в документ XF текстового комментария произвольной формы используется две последние функции. Комментарий заключается в /* и */ .
xfVoid xfOptionAddInfo(xfMap *map,xfInt option);
Включает/выключает вывод в файлы, сгенерированные из карты map, комментария с номером версии XFLib. Ненулевое значение option включает, нулевое выключает.
xfVoid xfOptionAddComment(xfMap *map,xfInt option);
Включает/выключает вывод в файлы, сгенерированные из карты map, комментария, установленного функцией xfSetDocHeader(). Ненулевое значение option включает, нулевое выключает.
xfVoid xfOptionCharCodes(xfMap *map,xfInt option);
Включает/выключает режим отображения кодов не-ASCII символов в сгенерированных файлах. В слечае, если опция установлена, символы, с кодом выше 127, отображаются в сгенерированных документах в шестнадцатеричном виде (\xxxx;). Ненулевое значение option включает, нулевое выключает.
Специальные функции |
xfVoid *xfAlloc(xfInt size);
Выделяет size байт памяти (аналог malloc). Возвращает указатель на выделенную область памяти, если недостаточно памяти - возвращает 0.
xfVoid xfFree(xfVoid *pointer);
Освобождает область памяти pointer, выделенную через xfAlloc().
xfChar* xfIntToDec(xfInt n,xfChar *str);
Преобразует целое знаковое число n в десятичную строку (например, 0, 10, -333). Результат записывается в str.
xfChar* xfIntToDec(xfInt n,xfChar *str);
Преобразует целое знаковое число n в шестнадцатеричную строку (например, 0xA, 0x335, 0xFFFFFFFF). Результат записывается в str.
xfInt xfDecToInt(xfChar *str);
Преобразует знаковую строку с десятичным числом в целое число.
xfInt xfHexToInt(xfChar *str);
Преобразует знаковую строку с шестнадцатеричным числом (вида 0x... или 0X...) в целое число.
xfInt xfBigEndian();
Возвращает true, если архитектура машины с прямым порядком байт (big endian), иначе - false.
xfInt xfLittleEndian();
Возвращает true, если архитектура машины с обратным порядком байт (little endian), иначе - false.
xfInt xfStrlen(xfChar *s);
xfInt xfNStrlen(xfNChar *s);
Возвращает длин строки s (аналог strlen, но для строк из символов типа xfChar). Первая функция работает со 16-битным строками (стандартные для XFLib), вторая - с 8-битными.
xfInt xfStrcpy(xfChar *dst,xfChar *src);
xfInt xfNStrcpy(xfNChar *dst,xfNChar *src);
Копирует строку src в dst (аналог strcpy, но для строк из символов типа xfChar). Первая функция работает со 16-битным строками (стандартные для XFLib), вторая - с 8-битными.
xfInt xfStrcmp(xfChar *s1,xfChar *s2);
xfInt xfNStrcmp(xfNChar *s1,xfNChar *s2);
Сравнивает строки s1 и s2 (аналог strcmp, но для строк из символов типа xfChar). Первая функция работает со 16-битным строками (стандартные для XFLib), вторая - с 8-битными.
xfChar* xfStrstr(xfChar *s1,xfChar *s2);
xfNChar* xfNStrstr(xfNChar *s1,xfNChar *s2);
Ищет подстроку s2 в строе s1. Возвращает указатель на первое вхождение подстроки в строке, а если вхождение не обнаружено - XF_NULL. Первая функция работает со 16-битным строками (стандартные для XFLib), вторая - с 8-битными.
xfChar* xfStrdup(xfChar *s);
xfNChar* xfNStrdup(xfNChar *s);
Дублирует строку s. Возвращает указатель на строку-дубликат. Не следует забывать освобождать строку дубликат функцией xfFree (аналог strdup, но для строк из символов типа xfChar). Первая функция работает со 16-битным строками (стандартные для XFLib), вторая - с 8-битными.
xfChar* xfConvertToASCII(xfChar *src,xfNChar *dst);
Преобразует строку src в кодировке UTF-16 в строку в кодировке ASCII, указатель на которую - dst. Символы с кодами выше 0x0080 (не входяшие в набор ASCII) превращаются в вопросительные знаки. Для полоной уверенности в том, что преобразованная строка поместится в выделенную память, для неё необходимо выделить xfStrlen(src) + 1 байт памяти. Возвращает указатель на преобразованную строку (т.е. dst).
xfWChar* xfConvertFromASCII(xfNChar *src,xfChar *dst);
Преобразует строку src в кодировке ASCII в строку в кодировке UTF-16, указатель на которую - dst. Для полоной уверенности в том, что преобразованная строка поместится в выделенную память, для неё необходимо выделить 2 * (xfNStrlen(src) + 1) байт памяти. Возвращает указатель на преобразованную строку (т.е. dst).
xfChar* xfConvertToUTF8(xfChar *src,xfNChar *dst);
Преобразует строку src в кодировке UTF-16 в строку в кодировке UTF-8, указатель на которую - dst. Для полоной уверенности в том, что преобразованная строка поместится в выделенную память, для неё необходимо выделить 4 * (xfStrlen(src) + 1) байт памяти. Возвращает указатель на преобразованную строку (т.е. dst).
xfWChar* xfConvertFromUTF8(xfNChar *src,xfChar *dst);
Преобразует строку src в кодировке UTF-8 в строку в кодировке UTF-16, указатель на которую - dst. Для полоной уверенности в том, что преобразованная строка поместится в выделенную память, для неё необходимо выделить 2 * (xfNStrlen(dst) + 1) байт памяти. Возвращает указатель на преобразованную строку (т.е. dst).
xfWChar xfWCharByteSwap(xfWChar c);
Меняет местами 2 байта в 16-битном символе c. Возвращает преобразованный символ.
xfHash* xfCreateHash(xfInt hashSize);
Создаёт пустую хэш-таблицу с числом входов. Рекоммендуется для наибольшей производительности устанавливать число входов таблицы большим или равным максимальному предполагаемому числу элементов в ней. Возвращает указатель на созданную хэш-таблицу (случае успеха), либо XF_NULL (недостаточно памяти для создания).
xfVoid xfDestroyHash(xfHash *hash);
Уничтожает созданную ранее хэш-таблицу hash, освобождая также всю память, выделенную под её элементы.
xfHash* xfHashAdd(xfHash *hash,xfVoid *key,xfInt keySize,xfVoid *data,xfInt dataSize,xfInt attr);
Добавляет пару вида ключ-значение в хэш-таблицу. Ключ key имеет размер keySize байт, данные data имеют размер dataSize байт. Аттрибуты attr могут быть побитовой суммой следующих аттрибутов:
Возвращает указатель на хэш-таблицу (вслучае успеха), либо XF_NULL (неудача - недостаточно памяти для добавления или дублирование ключа без опции HASH_REPLACE_KEY).
xfHash* xfHashRemove(xfHash *hash,xfVoid *key,xfInt keySize);
Удаляет из хэш-таблицы элемент с ключом key размером keySize байт. Возвращает: указатель на хэш-таблицы hash (в случае успеха), либо XF_NULL (ключ не найден).
xfVoid* xfHashFind(xfHash *hash,xfVoid *key,xfInt keySize,xfInt *dataSize);
Ищет в хэш-таблице запись с ключом key размером keySize. В случае успеха (запись найдена), копирует из таблицы данные записи в область памяти data, а если dataSize - ненулевой указатель, то записывает по адресу dataSize размер данных найденной записи. Возвращает: указатель на хэш-таблицы hash (в случае успеха), либо XF_NULL (ключ не найден).
xfHash* xfResizeHash(xfHash *hash,xfInt hashSize);
Изменяет число входов хэш-таблицы hash на hashSize. В случае успешного изменения размера, возарвщает переданный её указатель (hash), при нехватке памяти - XF_NULL.
Локализация |
xfInt xfLoadMsgList(xfNChar *filename);
Загружает список сообщений на определённом языке XFLib из файла filename. Сообщения хранятся в формате XF, примеры файлов сообщений находятся в папке lib/locale. В настоящий момент поддерживаются языки:
Возвращает:
Безопасность |
XFLib позволяет контроллировать разбор документов XF тамим образом, чтобы он не расходовал слишком много ресурсов. Это позволяет обезопасить программное обеспечение, поддерживающее XF от атак типа "отказ в обслуживании", связанных с большой загрузкой приложения (большой расход времени процессора, памяти).
XFLib позволяет создавать системы безопасности. Один или несколько документов могут наследовать систему безопасности. Система безопасности может включать различные ограничения на разбираемый документ (например, максимальное число элементов).
Система безопасности впервые включена в XFLib 0.1.3, и в перспективе добавление в неё дополнительных ограничений.
xfSecurity* xfCreateSecurity();
Создаёт систему безопасности. Созданная система безопасности пуста, т.е. не накладывает никаких ограничений на документы. Возвращает указатель на созданную систему безопасности (в случае успеха), либо XF_NULL (недостаточно памяти).
xfVoid xfDestroySecurity(xfSecurity *security);
Освобождает ранее созданную систему безопасности. ВНИМАНИЕ! Нельзя освобождать систему безопасности, которая в данный момент используется при разборе какого либо документа. Это может привести к краху приложения.
xfSecurity* xfGetDocSecurity(xfMap *map);
Возвращает указатель на систему безопасности, применяемую в документе map. Если документ не использует систем безопасности, возвращает XF_NULL.
xfVoid xfSetDocSecurity(xfMap *map,xfSecurity *security);
Привязывает к документу map ранее созданную систему безопасности security (при помощи функции xfCreateSecurity()).
xfInt xfSecurityGetNodeLimit(xfSecurity *security);
Возвращает ограничение на максимальное число элементов, установленное в системе безопасности security. Если ограничение не установлено, возвращает XF_NULL.
xfVoid xfSecuritySetNodeLimit(xfSecurity *security,xfInt nodeLimit);
Устанавливает в системе безопасности ограничение на максимальное число элементов равным nodeLimit. Для того чтобы отменить ограничение, следует установить значение nodeLimit в XF_NULL (0). Это ограничение будет применено ко всем документам, использующим эту систему безоасности.
Конфигурирование |
ВНИМАНИЕ!!! Не следует изменять эти параментры без хорошего понимания того, как они работают. В противном случае изменения могут привести значительному замедлению работы приложений, использующих XFLib, либо к их некорректной работе.
Конфигурация библиотеки XFLib задаётся в файле "lib/xf_conf.h". Для конфигурирования используются следующие определения:
Макрос | Назначение |
XF_NODESIZE | Максимальная длина названия/класса/значения элемента (в символах). Не влияет на расход памяти документом, но используется функциями типа xfReadFile. Рекоммендуется устанавливать большое значение (порядка тысяч), особенно в документах, где кодируется двоичная информация. В случен обнаружения в документе названия/класса/значения элемента с длинной более XF_NODESIZE символов, строка будет обрезана до длины XF_NODESIZE символов. |
XF_STACKSIZE | Максимальный размер стека (в элементах) для чтения и записи документов. Каждая пара скобок { } в документе соответствует одному значению в стеке. Рекомендуется устанавливать значение 4096 (по стандарту). |
XF_64BIT | Определяется для поддержки 64-битных типов данных (в основном целочисленные индексы). При установке флага 64-битным становится тип xfInt. |
XF_HASH_SIZE | Изначальное число входов хэш-таблицы потомков каждого элемента. Рекоммендует устанавливать в значение 80-100 (чем больше, тем быстрее работа с большими документами, но требует больше памяти). |
XF_HASH_NODE_SIZE | Число потомков, при достижении которого для элемента будет автоматически создана хэш-таблица. Рекоммендуется значение 10 - 20. |
XF_AUTOHASH | Коэффициент автоматического расширения хэш-таблицы. Если установлено нулевое значение - автоматическое расширение отключено. В случае если число потомков некоторого элемента превышает число входов его хэш-таблицы, будет происходить автоматическое увеличение числа входов хэш-таблицы. Число входов будет увеличино в XF_AUTOHASH раз. Рекоммендуемое значение - 8-10. Установка меньшего значения может привести к слишком частому расширению хэш-таблиц, что приводит к значительному замедлению работы. Установка большего значеиня приводит к большему расходу памяти. |
Ссылки |
Волков Максим mailto:max@xfhome.org XFHome.org (разработка формата и XFLib)