Как использовать simple_xml

Какие интерфейсы использовать

Большинство анализаторов XML используют объекты XML-узлов и на их основе создают основные функциональные интерфейсы. Главная особенность этого анализатора — он основан на объектах XML-элементов, производных от объектов XML-узлов, что упрощает работу с функциями, связанными с XML-элементами. Поэтому при использовании simple_xml основное внимание уделяется соответствующим интерфейсам для объектов XML-элементов.

1. Импорт и экспорт файлов XML
   Simple_xml включает функции для чтения и сохранения файлов, в отличие от библиотеки cJSON, которая может только анализировать строки.
   Основные функции интерфейса:

• Функция загрузки:

/**
 * @brief   Загрузка файла XML
 * 
 * @param   path Путь к файлу XML
 * 
 * @return Возвращает объект элемента XML корня
 * */
struct xmlelement * xml_load( char * path );

Объект элемента корня XML, возвращаемый функцией xml_load, представляет собой уже проанализированный файл XML, и вся информация в файле XML связана с объектом элемента корня. Пример использования можно найти в функции xml_example_run в файле xml_test.c.

• Функция сохранения:

/**
 * @brief   Сохранение объекта элемента XML (корня) в указанный файл XML
 *
 * @param   tree Объект элемента XML (корень)
 * @param   path Путь файла XML
 *
 * @return 1 : Успех, иначе неудача
 * */
int xml_save(struct xmlelement *tree, char *path);

Если вы хотите сохранить изменения, внесённые в дочерние элементы или атрибуты объекта элемента корня, необходимо вызвать функцию xml_save. В противном случае изменения будут потеряны. После сохранения объект элемента корня всё ещё существует. Если он больше не нужен, освободите память, чтобы предотвратить утечку памяти. Пример использования можно найти в функции xml_example_run в файле xml_test.c.

2. XML-элемент
   XML-элемент состоит из тега, атрибута, текста и списка дочерних элементов. После получения объекта элемента корня основная работа заключается в использовании следующих интерфейсов для настройки и чтения.

• Создание объекта элемента XML:

/**
 * @brief   Создание узла элемента
 *
 * @param   string  Тег элемента XML и атрибут
 * @param   text    Текст элемента XML
 * @param   type    Тип узла XML
 *
 * @return Успех: возвращает объект узла элемента, иначе NULL
 */
struct xmlelement *xmlelement_create( char *string, char *text, enum xmlnode_type type );

Например:

struct xmeleme

nt *tree = xmlelement_create("name", "test create", ELEMENT_NODE);

test create

* Уничтожение объекта элемента XML:

/**

• @brief Удаление узла элемента, освобождение текстового узла элемента, списка атрибутов и дочерних списков, а затем освобождение собственной памяти. При наличии дочерних узлов существует возможность рекурсивного вызова.
• @param this Объект элемента
• @return Успех: 1, неудача: иное */ int xmlelement_delete( void *this );

При освобождении списка дочерних элементов также проверяется, есть ли у каждого дочернего элемента дочерний элемент. Если да, то они удаляются вместе.  
* Получение тега элемента XML:

/**

• @brief Получение метки узла элемента
• @param this Элементный объект сам по себе
• @param buffer Текстовый узел элемента
• @return Метка длины символа */ int xmlelement_gettag( void *this, char *buffer );

* Получение атрибута элемента XML:  
Объекты элементов XML могут иметь несколько атрибутов. Следующие функции используются для получения всех атрибутов.  

/**

• @brief Количество атрибутов элемента
• @param element Элементный объект
• @return Количество атрибутов */ int xmlelement_getattrnum(struct xmlelement *element);

Получение строки атрибута:

/**

• @brief Получить строку атрибута узла элемента
• @param this Элементный объект сам по себе
• @param name Имя узла атрибута элемента
• @param buffer Строка значения атрибута
• @return Длина строки значения атрибута */ int xmlelement_getattribute( void *this, char *name, char *buffer );

Получить атрибут элемента по индексу:

/**

• @brief Получает атрибут узла элемента через индекс
• @param this Объект элемента сам по себе
• @param index Индекс атрибута
• @param buffer Значение атрибута в виде строки
• @return Успех: > 0, неудача: 0 */ int xmlelement_indexofattr(void *this, int index, char *buffer);

Получает значение атрибута как целое число:

/**

• @brief Получить значение атрибута узла элемента как целое число
• @param this Объект элемента сам по себе
• @param name Название атрибута узла
• @param value Указатель на целочисленное значение
• @return Успех: 1, неудача: иное */ int xmlelement_getattrbyint(void *this, char *name, int *value);

Получает значение атрибута как число с плавающей точкой:

/**

• @brief Получить значение атрибута узла элемента как число с плавающей точкой
• @param this Объект элемента сам по себе
• @param name Название атрибута узла
• @param value Указатель на значение числа с плавающей точкой
• @return Успех: 1, неудача: иное */ int xmlelement_getattrbyfloat(void *this, char *name, float *value);

Проверяет, равно ли значение атрибута целевому значению строки:

/**

• @brief Проверяет, совпадает ли значение атрибута узла элемента со входной строкой
• @param this Объект элемента сам по себе
• @param name Название атрибута узла
• @param buffer Целевая строка
• @return Успех: 1, неудача: иное */ int xmlelement_checkattribute(void *this, char *name, char *buffer);

* Установка атрибута элемента XML:  
Установка значения атрибута в строковом формате:

/**

• @brief Установка значения атрибута узла элемента
• @param this Объект элемента сам по себе
• @param name Название узла атрибута элемента
• @param buffer Значение атрибута
• @return Успех: > 0, неудача: 0 */ int xmlelement_setattribute(void *this, char *name, char *buffer);

Установка значения атрибута в десятичном целочисленном формате:

/**

• @brief Устанавливает значение атрибута узла элемента в десятичное целое число
• @param this Объект элемента сам по себе
• @param name Название узла атрибута элемента
• @param value Десятичное целочисленное значение
• @return Успех: > 0, неудача: 0 */ int xmlelement_setattrbyint(void *this, char *name, int value);

Устанавливает значение атрибута в шестнадцатеричном целочисленном формате:

/**

• @brief Установить значение атрибута узла элемента в шестнадцатеричное целое число
• @param this Объект элемента сам по себе
• @param name Название узла атрибута элемента
• @param value Шестнадцатеричное целочисленное значение
• @return Успех: > 0, неудача: 0 */ int xmlelement_setattrbyhex(void *this, char *name, int value);

Устанавливает значение атрибута в формате числа с плавающей точкой:

/**

• @brief Устаналивает значение атрибута узла элемента в число с плавающей точкой
• @param this Объект элемента сам по себе
• @param

**Получение и установка атрибута элемента объекта с плавающей точкой**

int xmlelement_setattrbyfloat(void *this, char *name, float value);

*Получение текстового содержимого элемента XML-объекта*

/**

• @brief 得到元素节点的文本
• @param this 元素对象自身
• @param buffer 字符串属性值的buffer
• @return 文本的长度 */ int xmelelement_gettext(void *this, char *buffer);

*Установка текстового содержимого элемента XML-объекта*  

/**

• @brief 设置元素节点的文本
• @param this элемента объект самоё
• @param buffer строка свойства значения buffer
• @return успех: 1, неудача: другое */ int xmelement_settext( void *this, char *buffer );

*Перебор списка дочерних элементов XML-объекта*  
Способ 1. Непосредственное получение списка дочерних узлов элемента, пользователь сам использует цикл for для перебора каждого дочернего узла.

/**

• @brief получение списка дочерних элементов узла
• @param this элемент объекта самоё
• @param tag тип метки дочернего элемента
• @param list возвращаемый список дочерних элементов
• @param list_size длина списка дочерних элементов
• @return длина списка дочерних элементов */ int xmelelement_getchildlist(void *this, char *tag, struct xmelelement **list, int list_size);

Способ 2. Получение первого дочернего элемента узла через тег, а затем использование функции xmlnode_getnext() для обхода каждого дочернего узла. Рекомендуется использовать этот способ, так как он не требует дополнительного выделения памяти.

/**

• @brief получение дочернего элемента узла, когда tag равен NULL, непосредственно возвращает первый дочерний узел элемента
• @param this элемент объекта самоё
• @param tag тип метки дочернего элемента
• @return первый дочерний элемент списка */ struct xmelelement * xmelelement_getchild(void *this, char *tag);

Способ 3. Получение количества дочерних узлов через функцию xmelelement_getchildnum, а затем использование функции xmelelement_indexofchild для обхода каждого дочернего узла.  

/**

• @brief получение количества дочерних элементов узла
• @param this элемент объекта самоё
• @return количество дочерних элементов объекта */ int xmelelement_getchildnum(void *this);

/**

• @brief индекс дочернего элемента узла
• @param this элемент объекта самоё
• @param index индекс
• @return дочерний элемент объекта */ struct xmelelement * xmelelement_indexofchild( void *this, int index )

*Добавление дочернего элемента*  

/**

• @brief добавление дочернего элемента
• @param this элемент объекта самоё
• @param child дочерний элемент
• @return успех: 1, неудача: 0 */ int xmelelement_addchild( void *this, struct xmelelement *child );

*Удаление дочернего элемента*  
Дочерний элемент также является обычным элементом, и его можно удалить с помощью функции xmelelement_delete. Если необходимо удалить все дочерние элементы, можно использовать следующую функцию:  

/**

• @brief удаление списка дочерних элементов, при вызове этой функции из xmelelement_delete существует возможность рекурсивного вызова
• @param this элемент объекта самоё
• @return успех: 1, неудача: 0 */ int xmelelement_deletechilds(void *this);

## Как расширить файловую систему  
На примере системы Linux реализуем функции open, gets, puts, close.

#include <stdio.h> void *local_open(char *file_name, char *mode) { FILE *file = fopen(file_name, mode); return file; }

char *local_gets(char *buf, int size, void *file) { return fgets(buf, size, file); }

int local_puts(char *buf, void *file) { return fputs(buf, file); }

void local_close(void *file) { fclose(file); }

Определим структуру xmlfileops:

static struct xmlfileops ops = { .open = local_open, .gets = local_gets, .puts = local_puts, .close = local_close};

Перед использованием функций другого программного стека XML используем функцию xml_fconfig для передачи структуры xmlfileops в программный стек XML.

xml_fconfig(&ops);

## Как расширить динамическое управление памятью  
На примере системы Linux реализуем функции malloc, free, memset. Здесь используются макроопределения, но также можно использовать функции.

#include <memory.h> #define local_malloc malloc #define local_free free #define local_memset memset

Определим структуру xmlmemops:

static struct xmlmemops ops = { .malloc = local_malloc, .free = local_free, .memset = local_memset, };

Прежде чем использовать функции другого программного стека XML, используем функцию xml_mconfig для передачи структуры xmlmemops в программный стек XML.  

xml_mconfig(&ops);

## Функция проверки памяти  
Программный стек simple_xml использует динамическую память, что может привести к утечке памяти и снижению качества программного обеспечения. Поэтому мы добавили функцию проверки памяти.  
*Использование*  
В параметрах компиляции добавьте макрос XML_MEM_CHECK, чтобы включить функцию проверки памяти, и используйте функцию xml_memory_show для вывода информации об использовании памяти. Например:

Memory in xml stack total : 0 blocks : 0

*Принцип проверки*  
Сохраняем адреса и размеры блоков памяти, выделенных в xml_malloc, в списке. Обновляем количество блоков памяти и объём используемой памяти.  
Удаляем блоки памяти из списка в xml_free и обновляем количество блоков и объём памяти.  
*Риски*  
Стратегия проверки также использует динамическую память. Использование этой функции может повлиять на требования к максимальной памяти. Рекомендуется включать эту функцию только в модульных тестах.