header for libroxml.so More...
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <pthread.h>
Go to the source code of this file.
Defines | |
#define | ROXML_API |
#define | ROXML_ATTR_NODE 0x08 |
#define | ROXML_STD_NODE 0x10 |
#define | ROXML_TXT_NODE 0x20 |
#define | ROXML_CMT_NODE 0x40 |
#define | ROXML_PI_NODE 0x80 |
#define | RELEASE_ALL (void*)-1 |
#define | RELEASE_LAST (void*)-2 |
Typedefs | |
typedef struct node | node_t |
node_t structure | |
Functions | |
node_t *ROXML_API | roxml_load_buf (char *buffer) |
load function for buffers | |
node_t *ROXML_API | roxml_load_doc (char *filename) |
load function for files | |
void ROXML_API | roxml_close (node_t *n) |
unload function | |
node_t *ROXML_API | roxml_get_parent (node_t *n) |
parent getter function | |
node_t *ROXML_API | roxml_get_chld (node_t *n, char *name, int nth) |
chld getter function | |
int ROXML_API | roxml_get_chld_nb (node_t *n) |
chlds number getter function | |
char *ROXML_API | roxml_get_name (node_t *n, char *buffer, int size) |
name getter function | |
char *ROXML_API | roxml_get_content (node_t *n, char *buffer, int bufsize, int *size) |
content getter function | |
int ROXML_API | roxml_get_attr_nb (node_t *n) |
number of attribute getter function | |
node_t *ROXML_API | roxml_get_attr (node_t *n, char *name, int nth) |
attribute getter function | |
node_t **ROXML_API | roxml_xpath (node_t *n, char *path, int *nb_ans) |
exec path function | |
int ROXML_API | roxml_get_type (node_t *n) |
node type function | |
int ROXML_API | roxml_get_node_position (node_t *n) |
node get position function | |
void ROXML_API | roxml_release (void *data) |
memory cleanning function | |
node_t *ROXML_API | roxml_add_node (node_t *parent, int position, int type, char *name, char *value) |
add a node to the tree | |
node_t *ROXML_API | roxml_get_text (node_t *n, int nth) |
text content getter function | |
int ROXML_API | roxml_get_text_nb (node_t *n) |
text node number getter function | |
void ROXML_API | roxml_del_node (node_t *n) |
node deletion function | |
void ROXML_API | roxml_commit_changes (node_t *n, char *dest, char **buffer, int human) |
sync function |
header for libroxml.so
This is the header file used to develop some softwares using the libroxml.so library.
Copyright (C) 2009 blunderer
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Definition in file roxml.h.
#define RELEASE_ALL (void*)-1 |
when used with roxml_release, release all allocated memory by current thread
#define RELEASE_LAST (void*)-2 |
when used with roxml_release, release last variable allocated
example:
#include <stdio.h> #include <roxml.h> int main(void) { int len; node_t * root = roxml_load_doc("/tmp/doc.xml"); // roxml_get_content allocate a buffer and store the content in it if no buffer was given printf("root content = '%s'\n", roxml_get_content(root, NULL, 0, &len)); // release the last allocated buffer even if no pointer is maintained by the user roxml_release(RELEASE_LAST); // here no memory leak can occur. roxml_close(root); return 0; }
#define ROXML_ATTR_NODE 0x08 |
#define ROXML_CMT_NODE 0x40 |
#define ROXML_PI_NODE 0x80 |
constant for processing_intruction nodes
#define ROXML_STD_NODE 0x10 |
#define ROXML_TXT_NODE 0x20 |
node_t* ROXML_API roxml_add_node | ( | node_t * | parent, | |
int | position, | |||
int | type, | |||
char * | name, | |||
char * | value | |||
) |
add a node to the tree
this function add a new node to the tree. This will not update de buffer or file, only the RAM loaded tree
parent | the parent node | |
position | the position as a child of parent (0 for auto position at the end of children list) | |
type | the type of node between ROXML_ATTR_NODE, ROXML_STD_NODE, ROXML_TXT_NODE, ROXML_PI_NODE, ROXML_CMT_NODE | |
name | the name of the node (for ROXML_ATTR_NODE and ROXML_STD_NODE only) | |
value | the text content (for ROXML_STD_NODE, ROXML_TXT_NODE, ROXML_CMT_NODE, ROXML_PI_NODE) or the attribute value (ROXML_ATTR_NODE) |
paramaters name and value depending on node type:
some examples to obtain this xml result file
<root> <!-- sample XML file --> <item id="42"> <price> 24 </price> </item> </root>
#include <roxml.h> int main(void) { node_t * root = roxml_add_node(NULL, 0, ROXML_STD_NODE, "xml", NULL); node_t * tmp = roxml_add_node(root, 0, ROXML_CMT_NODE, NULL, "sample XML file"); tmp = roxml_add_node(root, 0, ROXML_STD_NODE, "item", NULL); roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42"); tmp = roxml_add_node(tmp, 0, ROXML_STD_NODE, "price", "24"); roxml_commit_changes(root, "/tmp/test.xml", NULL, 1); return 0; }
Or also:
#include <roxml.h> int main(void) { node_t * root = roxml_add_node(NULL, 0, ROXML_STD_NODE, "xml", NULL); node_t * tmp = roxml_add_node(root, 0, ROXML_CMT_NODE, NULL, "sample XML file"); tmp = roxml_add_node(root, 0, ROXML_STD_NODE, "item", NULL); roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42"); tmp = roxml_add_node(tmp, 0, ROXML_STD_NODE, "price", NULL); tmp = roxml_add_node(tmp, 0, ROXML_TXT_NODE, NULL, "24"); roxml_commit_changes(root, "/tmp/test.xml", NULL, 1); return 0; }
void ROXML_API roxml_close | ( | node_t * | n | ) |
unload function
This function clear a document and all the corresponding nodes It release all memory allocated during roxml_load_doc or roxml_load_file. All nodes from the tree are not available anymore.
n | is any node of the tree to be cleaned |
void ROXML_API roxml_commit_changes | ( | node_t * | n, | |
char * | dest, | |||
char ** | buffer, | |||
int | human | |||
) |
sync function
this function sync changes to the given buffer or file in human or one-line format The tree will be processed starting with the root node 'n' and following with all its children. The tree will be dumped to a file if 'dest' is not null and contains a valid path. The tree will be dumped to a buffer if 'buffer' is not null the buffer is allocated by the library and a pointer to it will be stored into 'buffer'.
n | the root node of the tree to write | |
dest | the path to a file to write tree to | |
buffer | the adress of a buffer where tre will be written | |
human | 0 for one-line tree, or 1 for human format (using tabs, newlines...) |
One should do:
#include <roxml.h> int main(void) { node_t * root = roxml_add_node(NULL, 0, ROXML_STD_NODE, "xml", NULL); node_t * tmp = roxml_add_node(root, 0, ROXML_CMT_NODE, NULL, "sample XML file"); tmp = roxml_add_node(root, 0, ROXML_STD_NODE, "item", NULL); roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42"); tmp = roxml_add_node(tmp, 0, ROXML_STD_NODE, "price", "24"); roxml_commit_changes(root, "/tmp/test.xml", NULL, 1); return 0; }
to generate the following xml bloc:
<root> <!-- sample XML file --> <item id="42"> <price> 24 </price> </item> </root>
or also
#include <roxml.h> int main(void) { node_t * root = roxml_add_node(NULL, 0, ROXML_STD_NODE, "xml", NULL); node_t * tmp = roxml_add_node(root, 0, ROXML_CMT_NODE, NULL, "sample XML file"); tmp = roxml_add_node(root, 0, ROXML_STD_NODE, "item", NULL); roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42"); tmp = roxml_add_node(tmp, 0, ROXML_STD_NODE, "price", "24"); roxml_commit_changes(root, "/tmp/test.xml", NULL, 0); return 0; }
to generate the following xml bloc:
<root><!-- sample XML file --><item id="42"><price>24</price></item></root>
void ROXML_API roxml_del_node | ( | node_t * | n | ) |
attribute getter function
This function get the nth attribute of a node. User should roxml_release the returned buffer when no longer needed.
n | is one node of the tree | |
name | is the name of the child to get | |
nth | the id of attribute to read |
example: given the following xml file
<xml> <product id="42" class="item"/> </xml>
#include <stdio.h> #include <roxml.h> int main(void) { node_t * root = roxml_load_doc("/tmp/doc.xml"); node_t * item1 = roxml_get_chld(root, NULL, 0); node_t * item2 = roxml_get_chld(item1, NULL, 0); node_t * attr_by_name = roxml_get_attr(item2, "id", 0); node_t * attr_by_nth = roxml_get_attr(item2, NULL, 0); // here attr_by_name == attr_by_nth if(attr_by_name == attr_by_nth) { printf("Nodes are equal\n"); } roxml_close(root); return 0; }
int ROXML_API roxml_get_attr_nb | ( | node_t * | n | ) |
chld getter function
This function returns a given chld of a node etheir by name, or the nth child.
n | is one node of the tree | |
name | is the name of the child to get | |
nth | is the id of the chld to get |
example: given the following xml file
<xml> <item1/> <item2/> <item3/> </xml>
#include <stdio.h> #include <roxml.h> int main(void) { node_t * root = roxml_load_doc("/tmp/doc.xml"); node_t * child_by_name = roxml_get_chld(root, "item2", 0); node_t * child_by_nth = roxml_get_chld(root, NULL, 2); // here child_by_name == child_by_nth if(child_by_name == child_by_nth) { printf("Nodes are equal\n"); } roxml_close(root); return 0; }
int ROXML_API roxml_get_chld_nb | ( | node_t * | n | ) |
char* ROXML_API roxml_get_content | ( | node_t * | n, | |
char * | buffer, | |||
int | bufsize, | |||
int * | size | |||
) |
content getter function
This function returns a pointer with the concatenation of text content of a node (children are NOT included as text).; if the returned pointer is NULL then the node was empty. returned string should be freed using roxml_release when not used anymore
n | is one node of the tree | |
buffer | is the buffer where result will be written or NULL for internal allocation | |
bufsize | the size if using custom buffer | |
size | the actual size of result. if buffer was not NULL and size == buf_size, then given buffer was too small |
char* ROXML_API roxml_get_name | ( | node_t * | n, | |
char * | buffer, | |||
int | size | |||
) |
name getter function
This function return the name of the node or fill the current buffer with it if not NULL. if name is NULL, the function will allocate a buffer that user should free using roxml_release when no longer needed. Be carreful as if your buffer is too short for the returned string, it will be truncated
n | is one node of the tree | |
buffer | a buffer pointer or NULL if has to be auto allocated | |
size | the size of buffer pointed by buffer if not NULL |
int ROXML_API roxml_get_node_position | ( | node_t * | n | ) |
text content getter function
this function return the text content of a node as a TEXT nodes the content of the text node can be read using the roxml_get_content function
n | the node that contains text | |
nth | the nth text node to retrieve |
example: given this xml file:
<xml> This is <item/> an example <item/> of text nodes </xml>
#include <stdio.h> #include <roxml.h> int main(void) { int len; node_t * root = roxml_load_doc("/tmp/doc.xml"); node_t * item = roxml_get_chld(root, NULL, 0); node_t * text = roxml_get_text(item, 0); char * text_content = roxml_get_content(text, NULL, 0, &len); // HERE text_content is equal to "This is" printf("text_content = '%s'\n", text_content); text = roxml_get_text(item, 1); text_content = roxml_get_content(text, NULL, 0, &len); // HERE text_content is equal to "an example" printf("text_content = '%s'\n", text_content); text = roxml_get_text(item, 2); text_content = roxml_get_content(text, NULL, 0, &len); // HERE text_content is equal to "of text nodes" printf("text_content = '%s'\n", text_content); roxml_close(item); return 0; }
int ROXML_API roxml_get_text_nb | ( | node_t * | n | ) |
text node number getter function
this function return the number of text nodes in a standard node
n | the node to search into |
int ROXML_API roxml_get_type | ( | node_t * | n | ) |
node type function
node type getter function
This function tells if a node is an ROXML_ATTR_NODE, ROXML_TXT_NODE, ROXML_PI_NODE, ROXML_CMT_NODE or ROXML_STD_NODE.
n | is the node to test |
this function return the node type : ROXML_ARG ROXML_VAL
n | the node to return type for |
node_t* ROXML_API roxml_load_buf | ( | char * | buffer | ) |
load function for buffers
This function load a document by parsing all the corresponding nodes. The document must be contained inside the char * buffer given in parameter and remain valid until the roxml_close() function is called
buffer | the XML buffer to load |
node_t* ROXML_API roxml_load_doc | ( | char * | filename | ) |
load function for files
This function load a file document by parsing all the corresponding nodes
filename | the XML document to load |
void ROXML_API roxml_release | ( | void * | data | ) |
memory cleanning function
This function release the memory pointed by pointer just like free would but for memory allocated with roxml_malloc. Freeing a NULL pointer won't do anything. roxml_release also allow you to remove all previously allocated datas by using RELEASE_ALL as argument. You can also safely use RELEASE_LAST argument that will release the previously allocated var within the current thread (making this function thread safe). if using roxml_release on a variable non roxml_mallocated, nothing will happen
data | the pointer to delete or NULL or RELEASE_ALL or RELEASE_LAST |
exec path function
This function return a node set (table of nodes) corresponding to a given xpath. resulting node table should be roxml_release when not used anymore
n | is one node of the tree | |
path | the xpath to use | |
nb_ans | the number of results |
handled xpath are
===Relative xpath:=== * _"n0"_ ===Absolute xpath:=== * _"/n0"_ ===Special nodes:=== * _"`*`"_ * _"node()"_ * _"text()"_ * _"comment()"_ * _"processing-instruction()"_ ===Conditions:=== * Attribute string value: _"/n0`[`@a=value]"_ * Attribute int value: _"/n0`[`@a=value]"_ * Attribute int value: _"/n0`[`@a!=value]"_ * Attribute int value: _"/n0`[`@a<value]"_ * Attribute int value: _"/n0`[`@a>value]"_ * Attribute int value: _"/n0`[`@a<=value]"_ * Attribute int value: _"/n0`[`@a>=value]"_ * Node position: _"/n0`[`first()]"_ * Node position: _"/n0`[`first()+2]"_ * Node position: _"/n0`[`last()]"_ * Node position: _"/n0`[`last()-3]"_ * Node position: _"/n0`[`position() = 0]"_ * Node position: _"/n0`[`position() != 0]"_ * Node position: _"/n0`[`position() > 1]"_ * Node position: _"/n0`[`position() < 2]"_ * Node position: _"/n0`[`position() >= 1]"_ * Node position: _"/n0`[`position() <= 2]"_ * Node position: _"/n0`[`2]"_ * Other xpath: _"/n0`[`n1/@attr]"_ ===Shorten xpath for:=== * Children: _"/n0/n1/n2"_ * Attributes: _"/n0/n1/@a"_ * Descendent or self::node(): _"/n0//n5"_ * Parent: _"/n0/n1/../n1"_ * Self: _"/n0/n1/."_ ===Full xpath for:=== * Nodes: _"/n0/n1/child::a"_ * Attributes: _"/n0/n1/attribute::a"_ * Descendent or self: _"/n0/descendant-or-self::n5"_ * Parent: _"/child::n0/child::n1/parent::/n1"_ * Self: _"/child::n0/child::n1/self::"_ * Preceding: _"preceding::n1"_ * Following: _"following::n1"_ * Ancestor: _"ancestor::n2"_ * Ancestor-or-self: _"ancestor-or-self::n2"_