<libroxml  version="3.0.2" />
contact: tristan.lelong@libroxml.net
Functions
roxml_stub.c File Reference

API consistency module. More...

#include "roxml_internal.h"

Go to the source code of this file.

Functions

ROXML_STUB int roxml_commit_changes (node_t *n, char *dest, char **buffer, int human)
 sync function More...
 
ROXML_STUB int roxml_commit_file (node_t *n, char *dest, int human)
 sync to named file function More...
 
ROXML_STUB int roxml_commit_buffer (node_t *n, char **buffer, int human)
 sync to a memory buffer function More...
 
ROXML_STUB int roxml_commit_fd (node_t *n, int fd, int human)
 sync to file descriptor function More...
 
ROXML_STUB void roxml_del_node (node_t *n)
 node deletion function More...
 
ROXML_STUB node_troxml_add_node (node_t *parent, int position, int type, char *name, char *value)
 add a node to the tree More...
 
ROXML_STUB node_troxml_set_ns (node_t *n, node_t *ns)
 namespace setter function More...
 
ROXML_STUB char * roxml_get_content (node_t *n, char *buffer, int bufsize, int *size)
 content getter function More...
 
ROXML_STUB char * roxml_get_name (node_t *n, char *buffer, int size)
 name getter function More...
 
ROXML_STUB int roxml_get_nodes_nb (node_t *n, int type)
 number of nodes getter function More...
 
ROXML_STUB node_troxml_get_nodes (node_t *n, int type, char *name, int nth)
 nodes getter function More...
 
ROXML_STUB node_troxml_get_ns (node_t *n)
 namespace getter function More...
 
ROXML_STUB int roxml_get_pi_nb (node_t *n)
 process-instruction number getter function More...
 
ROXML_STUB node_troxml_get_pi (node_t *n, int nth)
 process-instruction getter function More...
 
ROXML_STUB int roxml_get_cmt_nb (node_t *n)
 comments number getter function More...
 
ROXML_STUB node_troxml_get_cmt (node_t *n, int nth)
 comment getter function More...
 
ROXML_STUB int roxml_get_txt_nb (node_t *n)
 text node number getter function More...
 
ROXML_STUB node_troxml_get_txt (node_t *n, int nth)
 text node getter function More...
 
ROXML_STUB int roxml_get_attr_nb (node_t *n)
 number of attribute getter function More...
 
ROXML_STUB node_troxml_get_attr (node_t *n, char *name, int nth)
 attribute getter function More...
 
ROXML_STUB int roxml_get_chld_nb (node_t *n)
 chlds number getter function More...
 
ROXML_STUB node_troxml_get_chld (node_t *n, char *name, int nth)
 chld getter function More...
 
ROXML_STUB int roxml_get_type (node_t *n)
 node type function More...
 
ROXML_STUB int roxml_get_node_position (node_t *n)
 node get position function More...
 
ROXML_STUB node_t ** roxml_xpath (node_t *n, char *path, int *nb_ans)
 exec path function More...
 
ROXML_STUB node_troxml_get_prev_sibling (node_t *n)
 prev sibling getter function More...
 
ROXML_STUB node_troxml_get_next_sibling (node_t *n)
 next sibling getter function More...
 
ROXML_STUB node_troxml_get_parent (node_t *n)
 parent getter function More...
 
ROXML_STUB node_troxml_get_root (node_t *n)
 root getter function More...
 
ROXML_STUB node_troxml_load_fd (int fd)
 load function for file descriptors More...
 
ROXML_STUB node_troxml_load_doc (char *filename)
 load function for files More...
 
ROXML_STUB int roxml_read_file (int pos, int size, char *buffer, node_t *node)
 read xml doc function More...
 
ROXML_STUB void roxml_close_file (node_t *n)
 unload function More...
 
ROXML_STUB int roxml_parse_file (roxml_load_ctx_t *context, roxml_parser_item_t *parser, FILE *file)
 generic load function More...
 
ROXML_STUB node_troxml_load_buf (char *buffer)
 load function for buffers More...
 
ROXML_STUB int roxml_read_buff (int pos, int size, char *buffer, node_t *node)
 read xml doc function More...
 
ROXML_STUB void roxml_close_buff (node_t *n)
 unload function More...
 
ROXML_STUB int roxml_parse_buff (roxml_load_ctx_t *context, roxml_parser_item_t *parser, char *buffer)
 generic load function More...
 

Detailed Description

API consistency module.

(C) Copyright 2014 Tristan Lelong trist.nosp@m.an.l.nosp@m.elong.nosp@m.@lib.nosp@m.roxml.nosp@m..net

SPDX-Licence-Identifier: LGPL-2.1+ The author added a static linking exception, see License.txt.

Definition in file roxml_stub.c.

Function Documentation

◆ roxml_add_node()

ROXML_STUB node_t* 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. One should call roxml_commit_changes to save modifications. If the parent node is an ROXML_ELM_NODE, then, new node will be added as a child. Else the node will be added as a sibling of the parent node. In the later case, position parameter describes the position in the sibling list, instead of position in the children list.

Parameters
parentthe parent node
positionthe position as a child of parent 1 is the first child, 0 for auto position at the end of children list...
typethe type of node between ROXML_ATTR_NODE, ROXML_ELM_NODE, ROXML_TXT_NODE, ROXML_CDATA_NODE, ROXML_PI_NODE, ROXML_CMT_NODE, ROXML_NSDEF_NODE, ROXML_NS_NODE.
namethe name of the node (mandatory for ROXML_ATTR_NODE and ROXML_ELM_NODE and ROXML_PI_NODE and ROXML_NSDEF_NODE and ROXML_NS_NODE only)
valuethe text content (mandatory for ROXML_TXT_NODE, ROXML_CDATA_NODE, ROXML_CMT_NODE, ROXML_ATTR_NODE and ROXML_NSDEF_NODE optional for ROXML_ELM_NODE, ROXML_PI_NODE). The text content for an attribute is the attribute value
Returns
the newly created node
See also
roxml_commit_changes
roxml_commit_buffer
roxml_commit_file
roxml_del_node
roxml_close

Escaping the as per XML specifications can be done by adding the ROXML_ESCAPED_MOD modifier to node type as showed below:

roxml_add_node(NULL, 0, ROXML_ESCAPE_MODE | ROXML_ELM_NODE, "node1", "content <that> needs escaping");

This will create a node that exports as:

 * <node1>content &lt;that&gt; needs escaping</node1>
 * 

paramaters name and value depending on node type:

  • ROXML_ELM_NODE take at least a node name. the parameter value is optional and represents the text content.
  • ROXML_TXT_NODE ignore the node name. the parameter value represents the text content.
  • ROXML_CDATA_NODE ignore the node name. the parameter value represents the text content that will be encapsulated in CDATA tags.
  • ROXML_CMT_NODE ignore the node name. the parameter value represents the comment.
  • ROXML_PI_NODE take the node name as process-instruction target. the parameter value represents the content of processing-instruction.
  • ROXML_ATTR_NODE take an attribute name. and the attribute value as given by parameter value.
  • ROXML_NSDEF_NODE take an attribute name (empty string for default namespace). and the namespace value as given by parameter value.
  • ROXML_NS_NODE take an attribute name (empty string for default namespace).

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_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", "24");
roxml_commit_changes(root, "/tmp/test.xml", NULL, 1);
roxml_close(root);
return 0;
}

Or also:

#include <roxml.h>
int main(void)
{
node_t *root = roxml_add_node(NULL, 0, ROXML_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", NULL);
tmp = roxml_add_node(tmp, 0, ROXML_TXT_NODE, NULL, "24");
roxml_commit_changes(root, "/tmp/test.xml", NULL, 1);
roxml_close(root);
return 0;
}

If you need a valid XML doc, just start by adding a corresponding process-instruction. Example, to obtain this xml file:

<?xml version="1.0" encoding="UTF-8"?>
<!--sample file-->
<doc>
 basic content
 <item/>
 <item/>
 <item/>
</doc>
#include <roxml.h>
int main(void)
{
node_t *root = roxml_add_node(NULL, 0, ROXML_PI_NODE, "xml", "version=\"1.0\" encoding=\"UTF-8\"");
node_t *node = roxml_add_node(root, 0, ROXML_CMT_NODE, NULL, "sample file");
node = roxml_add_node(root, 0, ROXML_ELM_NODE, "doc", "basic content");
roxml_add_node(node, 0, ROXML_ELM_NODE, "item", NULL);
roxml_add_node(node, 0, ROXML_ELM_NODE, "item", NULL);
roxml_add_node(node, 0, ROXML_ELM_NODE, "item", NULL);
roxml_commit_changes(root, "/tmp/test.xml", NULL, 1);
roxml_close(root);
return 0;
}

Definition at line 47 of file roxml_stub.c.

◆ roxml_close_buff()

ROXML_STUB void roxml_close_buff ( node_t n)

unload function

This function clear a document that was opened as part of a buffer

Parameters
nis any node of the tree to be cleaned
Returns
void

Definition at line 247 of file roxml_stub.c.

◆ roxml_close_file()

ROXML_STUB void roxml_close_file ( node_t n)

unload function

This function clear a document that was opened as part of a file

Parameters
nis any node of the tree to be cleaned
Returns
void

Definition at line 221 of file roxml_stub.c.

◆ roxml_commit_buffer()

ROXML_STUB int roxml_commit_buffer ( node_t n,
char **  buffer,
int  human 
)

sync to a memory buffer function

this function syncs changes from the RAM tree to the given buffer in human or one-line format The tree will be processed starting with the root node 'n' and following with all its children or if n is the root, all its siblings and children. 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'. The allocated buffer can be freed using free()

Parameters
nthe root node of the tree to write
bufferthe address of a buffer where the tree will be written. This buffer have to be freed after use
human0 for one-line tree, or 1 for human format (using indentation, newlines...)
Returns
the number of bytes written to file or buffer

One should do:

#include <roxml.h>
int main(void)
{
char *buffer = NULL;
node_t *root = roxml_add_node(NULL, 0, ROXML_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", "24");
roxml_commit_changes(root, &buffer, 1);
roxml_close(root);
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)
{
char *buffer = NULL;
node_t *root = roxml_add_node(NULL, 0, ROXML_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", "24");
roxml_commit_buffer(root, &buffer, 0);
roxml_close(root);
return 0;
}

to generate the following xml bloc:

<root><!-- sample XML file --><item id="42"><price>24</price></item></root>
See also
roxml_commit_changes
roxml_commit_file
roxml_commit_fd

Definition at line 27 of file roxml_stub.c.

◆ roxml_commit_changes()

ROXML_STUB int roxml_commit_changes ( node_t n,
char *  dest,
char **  buffer,
int  human 
)

sync function

Deprecated:
this function sync changes from the RAM tree 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 or if n is the root, all its siblings and 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'. The allocated buffer can be freed usinf free()
Warning
in the case of a tree loaded using roxml_load_doc, the roxml_commit_changes cannot be done to that same file since it may override datas it need. This usually result in a new file filled with garbages. The solution is to write it to a temporary file and rename it after roxml_close the current tree.

This function is now deprecated and one should use roxml_commit_buffer or roxml_commit_file that achieves the exact same goal.

Parameters
nthe root node of the tree to write
destthe path to a file to write tree to
bufferthe address of a buffer where the tree will be written. This buffer have to be freed after use
human0 for one-line tree, or 1 for human format (using tabs, newlines...)
Returns
the number of bytes written to file or buffer
See also
roxml_commit_buffer
roxml_commit_file

This is a legacy function that proposes the same functionnalities as both roxml_commit_file and roxml_commit_buffer. New code should use the latter functions when needed.

One should do:

#include <roxml.h>
int main(void)
{
node_t *root = roxml_add_node(NULL, 0, ROXML_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_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_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", "24");
roxml_commit_changes(root, "/tmp/test.xml", NULL, 0);
roxml_close(root);
return 0;
}

to generate the following xml bloc:

<root><!-- sample XML file --><item id="42"><price>24</price></item></root>

the buffer variant works more or less the same way

#include <stdio.h>
#include <roxml.h>
int main(void)
{
int len = 0;
char * buffer = NULL;
FILE * file_out;
node_t *root = roxml_add_node(NULL, 0, ROXML_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", "24");
len = roxml_commit_changes(root, NULL, &buffer, 0);
file_out = fopen("/tmp/test.xml", "w");
fwrite(buffer, 1, len, file_out);
fclose(file_out);
roxml_close(root);
return 0;
}

to generate the following xml bloc:

<root><!-- sample XML file --><item id="42"><price>24</price></item></root>
See also
roxml_commit_file
roxml_commit_buffer
roxml_commit_fd

Definition at line 15 of file roxml_stub.c.

◆ roxml_commit_fd()

ROXML_STUB int roxml_commit_fd ( node_t n,
int  fd,
int  human 
)

sync to file descriptor function

this function synchronizes changes from the RAM tree to the given file in human or one-line format. The tree will be processed starting with the root node 'n' and following with all its children or if n is the root, all its siblings and children. The tree will be dumped to a file if fd is a valid file descriptor.

Warning
in the case of a tree loaded using roxml_load_doc, the roxml_commit_fd cannot be done to that same file since it may override datas it needs. This usually results in a new file filled with garbage. The solution is to write it to a temporary file and rename it after roxml_close the current tree.
Parameters
nthe root node of the tree to write
fdthe file descriptor to write tree to
human0 for one-line tree, or 1 for human format (using tabs, newlines...)
Returns
the number of bytes written to file

The file described by fd is not truncated so this function allows one to append an XML subtree to an existing file.

One should do:

#include <roxml.h>
int main(void)
{
int fd = open("/tmp/test.xml", O_TRUNC|O_WRONLY, 0666);
node_t *root = roxml_add_node(NULL, 0, ROXML_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", "24");
roxml_commit_fd(root, fd, 1);
roxml_close(root);
close(fd);
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)
{
int fd = open("/tmp/test.xml", O_TRUNC|O_WRONLY, 0666);
node_t *root = roxml_add_node(NULL, 0, ROXML_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", "24");
roxml_commit_fd(root, fd, 0);
roxml_close(root);
close(fd);
return 0;
}

to generate the following xml bloc:

<root><!-- sample XML file --><item id="42"><price>24</price></item></root>
See also
roxml_commit_changes
roxml_commit_file
roxml_commit_buffer

Definition at line 33 of file roxml_stub.c.

◆ roxml_commit_file()

ROXML_STUB int roxml_commit_file ( node_t n,
char *  dest,
int  human 
)

sync to named file function

this function sync changes from the RAM tree to the given file in human or one-line format The tree will be processed starting with the root node 'n' and following with all its children or if n is the root, all its siblings and children. The tree will be dumped to a file if 'dest' is not null and contains a valid path.

Warning
in the case of a tree loaded using roxml_load_doc, the roxml_commit_file cannot be done to that same file since it may override datas it needs. This usually resultis in a new file filled with garbage. The solution is to write it to a temporary file and rename it after roxml_close the current tree.
Parameters
nthe root node of the tree to write
destthe path to a file to write tree to
human0 for one-line tree, or 1 for human format (using tabs, newlines...)
Returns
the number of bytes written to file or buffer

One should do:

#include <roxml.h>
int main(void)
{
node_t *root = roxml_add_node(NULL, 0, ROXML_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", "24");
roxml_commit_file(root, "/tmp/test.xml", 1);
roxml_close(root);
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_ELM_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_ELM_NODE, "item", NULL);
roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
tmp = roxml_add_node(tmp, 0, ROXML_ELM_NODE, "price", "24");
roxml_commit_file(root, "/tmp/test.xml", 0);
roxml_close(root);
return 0;
}

to generate the following xml bloc:

<root><!-- sample XML file --><item id="42"><price>24</price></item></root>
See also
roxml_commit_changes
roxml_commit_buffer
roxml_commit_fd

Definition at line 21 of file roxml_stub.c.

◆ roxml_del_node()

ROXML_STUB void roxml_del_node ( node_t n)

node deletion function

this function delete a node from the tree. The node is not really deleted from the file or buffer until the roxml_commit_changes is called, but it won't be visible anymore in the XML tree.

Parameters
nthe node to delete
Returns
See also
roxml_add_node
roxml_commit_changes
roxml_commit_buffer
roxml_commit_file
Warning
when removing a nsdef node, all node using this namespace will be updated and inherit their parent namespace

Definition at line 41 of file roxml_stub.c.

◆ roxml_get_attr()

ROXML_STUB node_t* roxml_get_attr ( node_t n,
char *  name,
int  nth 
)
inline

attribute getter function

This function get the nth attribute of a node.

Parameters
nis one node of the tree
nameis the name of the attribute to get
nththe id of attribute to read
Returns
the attribute corresponding to name or id (if both are set, name is used)

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;
}

Definition at line 135 of file roxml_stub.c.

◆ roxml_get_attr_nb()

ROXML_STUB int roxml_get_attr_nb ( node_t n)
inline

number of attribute getter function

This function returns the number of attributes for a given node

Parameters
nis one node of the tree
Returns
the number of attributes in node

Definition at line 129 of file roxml_stub.c.

◆ roxml_get_chld()

ROXML_STUB node_t* roxml_get_chld ( node_t n,
char *  name,
int  nth 
)
inline

chld getter function

This function returns a given chld of a node etheir by name, or the nth child.

Parameters
nis one node of the tree
nameis the name of the child to get
nthis the id of the chld to get
Returns
the chld corresponding to name or id (if both are set, name is used)
See also
roxml_get_chld_nb

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;
}

Definition at line 147 of file roxml_stub.c.

◆ roxml_get_chld_nb()

ROXML_STUB int roxml_get_chld_nb ( node_t n)
inline

chlds number getter function

This function return the number of chlidren for a given node

Parameters
nis one node of the tree
Returns
the number of chlildren

Definition at line 141 of file roxml_stub.c.

◆ roxml_get_cmt()

ROXML_STUB node_t* roxml_get_cmt ( node_t n,
int  nth 
)
inline

comment getter function

This function returns the nth comment of a node

Parameters
nis one node of the tree
nthis the id of the cmt to get
Returns
the comment corresponding to id
See also
roxml_get_cmt_nb
roxml_get_nodes

example: given the following xml file

<xml>
 <item1/>
 <!--comment1-->
 <!--comment2-->
 <item2/>
 <item3/>
</xml>
#include <stdio.h>
#include <roxml.h>
int main(void)
{
node_t *root = roxml_load_doc("/tmp/doc.xml");
node_t *xml = roxml_get_chld(root, NULL, 0);
node_t *cmt1 = roxml_get_cmt(xml, 0);
node_t *cmt2 = roxml_get_cmt(xml, 1);
// here cmt1 is the "comment1" node
if(strcmp(roxml_get_content(cmt1, NULL, 0, NULL), "comment1") == 0) {
printf("got the first comment\n");
}
// and cmt2 is the "comment2" node
if(strcmp(roxml_get_content(cmt2, NULL, 0, NULL), "comment2") == 0) {
printf("got the second comment\n");
}
roxml_close(root);
return 0;
}

Definition at line 111 of file roxml_stub.c.

◆ roxml_get_cmt_nb()

ROXML_STUB int roxml_get_cmt_nb ( node_t n)
inline

comments number getter function

This function return the number of comments for a given node

Parameters
nis one node of the tree
Returns
the number of comments
See also
roxml_get_cmt_nb
roxml_get_nodes

Definition at line 105 of file roxml_stub.c.

◆ roxml_get_content()

ROXML_STUB char* roxml_get_content ( node_t n,
char *  buffer,
int  bufsize,
int *  size 
)

content getter function

This function returns the content of a node.; if the returned pointer is NULL then the node either has no content or this function is irrelevant for this kind of node. depending on node type it will return:

  • ROXML_ELM_NODE: returns the concatenation of all direct text node children
  • ROXML_ATTR_NODE: returns the attribute value
  • ROXML_PI_NODE: returns the process-instruction instruction
  • ROXML_TXT_NODE: returns the text content of the node
  • ROXML_CMT_NODE: returns the text content of the comment
  • ROXML_NS_NODE: returns the namespace definition (usually an URL)

returned string should be freed using roxml_release when not used anymore

Parameters
nis one node of the tree
bufferis the buffer where result will be written or NULL for internal allocation
bufsizethe size if using custom buffer
sizethe actual size of copied result. returned size should be less that buffer size since roxml_get_content will add the \0. if buffer was not NULL and size == buf_size, then given buffer was too small and node content was truncated
Returns
the text content
See also
roxml_release

Definition at line 61 of file roxml_stub.c.

◆ roxml_get_name()

ROXML_STUB char* 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. depending on node type it will return:

  • ROXML_ELM_NODE: returns the node name
  • ROXML_ATTR_NODE: returns the attribute name
  • ROXML_PI_NODE: returns the process-instruction targeted application
  • ROXML_TXT_NODE: returns NULL (or empty string if you provided a buffer in buffer param)
  • ROXML_CMT_NODE: returns NULL (or empty string if you provided a buffer in buffer param)
  • ROXML_NS_NODE: returns the namespace alias associated with the ns node

Be carreful as if your buffer is too short for the returned string, it will be truncated

Parameters
nis one node of the tree
buffera buffer pointer or NULL if has to be auto allocated
sizethe size of buffer pointed by buffer if not NULL
Returns
the name of the node (return our buffer pointer if it wasn't NULL)
See also
roxml_release

Definition at line 69 of file roxml_stub.c.

◆ roxml_get_next_sibling()

ROXML_STUB node_t* roxml_get_next_sibling ( node_t n)

next sibling getter function

This function returns the next sibling of a given node

Parameters
nis one node of the tree
Returns
the next sibling node

Definition at line 183 of file roxml_stub.c.

◆ roxml_get_node_position()

ROXML_STUB int roxml_get_node_position ( node_t n)

node get position function

This function tells the index of a node between all its siblings homonyns.

Parameters
nis the node to test
Returns
the postion between 1 and N

Definition at line 159 of file roxml_stub.c.

◆ roxml_get_nodes()

ROXML_STUB node_t* roxml_get_nodes ( node_t n,
int  type,
char *  name,
int  nth 
)

nodes getter function

This function get the nth node matching type contained in a node, or the first node named name. All other roxml_get_* are wrapper to this function. When asking for several node type (let say ROXML_ALL_NODES), all ROXML_ATTR_NODE will be placed first, then, all other nodes will come mixed, depending on xml document order.

Parameters
nis one node of the tree
typeis the bitmask of node types we want to consider
nameis the name of the child to get. This parameter is only relevant for node with types: ROXML_ELM_NODE, ROXML_ATTR_NODE, ROXML_PI_NODE
nththe id of attribute to read
Returns
the node corresponding to name or id (if both are set, name is used)
See also
roxml_get_attr
roxml_get_chld
roxml_get_txt
roxml_get_cmt
roxml_get_pi

Definition at line 81 of file roxml_stub.c.

◆ roxml_get_nodes_nb()

ROXML_STUB int roxml_get_nodes_nb ( node_t n,
int  type 
)

number of nodes getter function

This function returns the number of nodes matching type flag contained in a given node all other roxml_get_*_nb are wrapper to this

Parameters
nis one node of the tree
typeis the bitmask of node types we want to consider
Returns
the number of nodes
See also
roxml_get_attr_nb
roxml_get_chld_nb
roxml_get_txt_nb
roxml_get_cmt_nb
roxml_get_pi_nb

example: given the following xml file

<xml>
 <!-- comment -->
 <?value="2"?>
 <product id="42" class="item"/>
 <product id="43" class="item"/>
</xml>
#include <stdio.h>
#include <roxml.h>
int main(void)
{
node_t *root = roxml_load_doc("/tmp/doc.xml");
int all_nodes_2 = roxml_get_nodes_nb(root, ROXML_ALL_NODES);
// here all_nodes_1 == all_nodes_2
if(all_nodes_1 == all_nodes_2) {
printf("%d Nodes are contained in root\n", all_nodes_1);
}
// let's count elm node (== children)
int elm_nodes1 = roxml_get_nodes_nb(root, ROXML_ELM_NODE);
int elm_nodes2 = roxml_get_chld_nb(root);
// here elm_nodes1 == elm_nodes2 == 2
if(elm_nodes1 == elm_nodes2) {
printf("%d ELM Nodes are contained in root\n", elm_nodes_1);
}
// we can also count all node except elm nodes, doing:
int almost_all_nodes = roxml_get_nodes_nb(root, ROXML_ALL_NODES & ~ROXML_ELM_NODE);
// here almost_all_nodes = 2 since we have one comment node and one processing-instruction node
if(almost_all_nodes == 2) {
printf("%d non ELM Nodes are contained in root\n", almost_all_nodes_1);
}
roxml_close(root);
return 0;
}

Definition at line 75 of file roxml_stub.c.

◆ roxml_get_ns()

ROXML_STUB node_t* roxml_get_ns ( node_t n)
inline

namespace getter function

This function returns the namespace of a node

Parameters
nis one node of the tree
Returns
the namespace or NULL if none are set for this node
See also
roxml_add_node
roxml_set_ns
roxml_get_nodes

example: given the following xml file

<xml xmlns:test="http://www.test.org">
 <test:item1 test:value1="3"/>
</xml>
#include <stdio.h>
#include <roxml.h>
int main(void)
{
node_t *root = roxml_load_doc("/tmp/doc.xml");
node_t *xml = roxml_get_chld(root, NULL, 0);
node_t *nsdef = roxml_get_attr(xml, NULL, 0);
node_t *node1 = roxml_get_chld(xml, NULL, 0);
node_t *attr1 = roxml_get_attr(node1, NULL, 0);
node_t *node1_ns = roxml_get_ns(node1);
node_t *attr1_ns = roxml_get_ns(attr1);
// here node1_ns and attr1_ns are the "test:" namespace
if(node1_ns == nsdef) {
printf("got the correct namespace node for elem\n");
}
if(attr1_ns == nsdef) {
printf("got the correct namespace node for attr\n");
}
if(strcmp(roxml_get_name(node1_ns, NULL, 0), "test") == 0) {
printf("got the correct namespace alias\n");
}
if(strcmp(roxml_get_content(node1_ns, NULL, 0, NULL), "http://www.test.org") == 0) {
printf("got the correct namespace\n");
}
roxml_close(root);
return 0;
}

Definition at line 87 of file roxml_stub.c.

◆ roxml_get_parent()

ROXML_STUB node_t* roxml_get_parent ( node_t n)

parent getter function

This function returns the parent of a given node

Parameters
nis one node of the tree
Returns
the parent node

Definition at line 189 of file roxml_stub.c.

◆ roxml_get_pi()

ROXML_STUB node_t* roxml_get_pi ( node_t n,
int  nth 
)
inline

process-instruction getter function

This function returns the nth process-instruction of a node.

Parameters
nis one node of the tree
nthis the id of the pi to get
Returns
the process-instruction corresponding to id
See also
roxml_get_pi_nb
roxml_get_nodes

example: given the following xml file

<xml>
 <item1/>
 <?test value="2"?>
 <?test param="3"?>
 <item2/>
 <item3/>
</xml>
#include <stdio.h>
#include <roxml.h>
int main(void)
{
node_t *root = roxml_load_doc("/tmp/doc.xml");
node_t *xml = roxml_get_chld(root, NULL, 0);
node_t *pi1 = roxml_get_pi(xml, 0);
node_t *pi2 = roxml_get_pi(xml, 1);
// here pi1 is the <?value="2"?> node
if(strcmp(roxml_get_content(pi1, NULL, 0, NULL), "value=\"2\"") == 0) {
printf("got the first process-instruction\n");
}
// and pi2 is the <?param="3"?> node
if(strcmp(roxml_get_content(pi2, NULL, 0, NULL), "param=\"3\"") == 0) {
printf("got the second process-instruction\n");
}
roxml_close(root);
return 0;
}

Definition at line 99 of file roxml_stub.c.

◆ roxml_get_pi_nb()

ROXML_STUB int roxml_get_pi_nb ( node_t n)
inline

process-instruction number getter function

This function return the number of process-instruction in a given node

Parameters
nis one node of the tree
Returns
the number of process-instructions
See also
roxml_get_pi
roxml_get_nodes_nb

Definition at line 93 of file roxml_stub.c.

◆ roxml_get_prev_sibling()

ROXML_STUB node_t* roxml_get_prev_sibling ( node_t n)

prev sibling getter function

This function returns the prev sibling of a given node

Parameters
nis one node of the tree
Returns
the prev sibling node

Definition at line 177 of file roxml_stub.c.

◆ roxml_get_root()

ROXML_STUB node_t* roxml_get_root ( node_t n)

root getter function

This function returns the root of a tree containing the given node The root is defined as a virtual node that contains all first rank nodes if document is not a valid xml document:

<data1>
 <item/>
 <item/>
</data1>
<data2>
 <item/>
 <item/>
</data2>

will be processed successfully and the root node will have 2 children: data1 and data2

if document was:

<?xml version="1.0">
<doc>
 <data1>
  <item/>
  <item/>
 </data1>
 <data2>
  <item/>
  <item/>
 </data2>
</doc>

In this case, the node "doc" will be the root, and will contain 2 children: data1 and data2

For a document to be valid, following conditions must be met:

  • the first node is a processing instruction with the string "xml" as target application.
  • there is only one ELM node containing all document (but there may be several process-instructions or comments)
Parameters
nis one node of the tree
Returns
the root node

Definition at line 195 of file roxml_stub.c.

◆ roxml_get_txt()

ROXML_STUB node_t* roxml_get_txt ( node_t n,
int  nth 
)
inline

text node getter function

this function return the text content of a node as a ROXML_TXT_NODE the content of the text node can be read using the roxml_get_content function

Parameters
nthe node that contains text
nththe nth text node to retrieve
Returns
the text node or ROXML_INVALID_DOC (NULL)
See also
roxml_get_txt_nb
roxml_get_nodes
roxml_get_content

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_txt(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_txt(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_txt(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;
}

Definition at line 123 of file roxml_stub.c.

◆ roxml_get_txt_nb()

ROXML_STUB int roxml_get_txt_nb ( node_t n)
inline

text node number getter function

this function return the number of text nodes in a standard node

Parameters
nthe node to search into
Returns
the number of text node
See also
roxml_get_txt

Definition at line 117 of file roxml_stub.c.

◆ roxml_get_type()

ROXML_STUB int roxml_get_type ( node_t n)
inline

node type function

This function tells if a node is an ROXML_ATTR_NODE, ROXML_TXT_NODE, ROXML_PI_NODE, ROXML_CMT_NODE or ROXML_ELM_NODE. Warning: ROXML_CDATA_NODE are special. They return a type as ROXML_TXT_NODE.

Parameters
nis the node to test
Returns
the node type

Definition at line 153 of file roxml_stub.c.

◆ roxml_load_buf()

ROXML_STUB node_t* 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

Parameters
bufferthe XML buffer to load
Returns
the root node or ROXML_INVALID_DOC (NULL). errno is set to EINVAL in case of parsing error
See also
roxml_close
roxml_load_fd
roxml_load_doc

Definition at line 235 of file roxml_stub.c.

◆ roxml_load_doc()

ROXML_STUB node_t* roxml_load_doc ( char *  filename)

load function for files

This function load a file document by parsing all the corresponding nodes

Warning
the file is not fully copied and thus, it should stay untouched until roxml_close is called on the corresponding XML tree.
Parameters
filenamethe XML document to load
Returns
the root node or ROXML_INVALID_DOC (NULL). errno is set to EINVAL in case of parsing error
See also
roxml_close
roxml_load_fd
roxml_load_buf

Definition at line 209 of file roxml_stub.c.

◆ roxml_load_fd()

ROXML_STUB node_t* roxml_load_fd ( int  fd)

load function for file descriptors

This function load a document by parsing all the corresponding nodes

Parameters
fdthe opened file descriptor to XML document to load
Returns
the root node or ROXML_INVALID_DOC (NULL). errno is set to EINVAL in case of parsing error
See also
roxml_close
roxml_load_doc
roxml_load_buf

Definition at line 203 of file roxml_stub.c.

◆ roxml_parse_buff()

ROXML_STUB int roxml_parse_buff ( roxml_load_ctx_t context,
roxml_parser_item_t parser,
char *  buffer 
)

generic load function

This function parse a buffer document and all the corresponding nodes

Parameters
contextinternal data used for parsing
parserthe parser object to run
bufferaddress of buffer that contains xml
Returns
an error code and filled context see roxml_close_buff

Definition at line 253 of file roxml_stub.c.

◆ roxml_parse_file()

ROXML_STUB int roxml_parse_file ( roxml_load_ctx_t context,
roxml_parser_item_t parser,
FILE *  file 
)

generic load function

This function parse a file document and all the corresponding nodes

Parameters
contextinternal data used for parsing
parserthe parser object to run
filefile pointer to the document
Returns
an error code and filled context see roxml_close_buff

Definition at line 227 of file roxml_stub.c.

◆ roxml_read_buff()

ROXML_STUB int roxml_read_buff ( int  pos,
int  size,
char *  buffer,
node_t node 
)

read xml doc function

this function read inside a xml buffer and fill the given buffer

Parameters
posthe pos in the xml document
sizethe size of the data to read
bufferthe destination buffer
nodethe node that belong to the tree we want to read to
Returns
the number of bytes read

Definition at line 241 of file roxml_stub.c.

◆ roxml_read_file()

ROXML_STUB int roxml_read_file ( int  pos,
int  size,
char *  buffer,
node_t node 
)

read xml doc function

this function read inside a xml file and fill the given buffer

Parameters
posthe pos in the xml document
sizethe size of the data to read
bufferthe destination buffer
nodethe node that belong to the tree we want to read to
Returns
the number of bytes read

Definition at line 215 of file roxml_stub.c.

◆ roxml_set_ns()

ROXML_STUB node_t* roxml_set_ns ( node_t n,
node_t ns 
)

namespace setter function

This function set the namespace of a node to the given namespace definition. The namespace must be previously defined in the xml tree in an ancestor of node n.

Parameters
nis one node of the tree
nsis one nsdef node of the tree
Returns
the node or ROXML_INVALID_DOC (NULL) if ns cannot be set
See also
roxml_add_node
roxml_get_ns
roxml_get_nodes
Warning
: Setting a namespace to a node is recursif:
  • it will update all element and attribute that are descendant from current node
  • namespace will be applied to all new node added as descendant as current node

Definition at line 53 of file roxml_stub.c.

◆ roxml_xpath()

ROXML_STUB node_t** roxml_xpath ( node_t n,
char *  path,
int *  nb_ans 
)

exec path function

This function return a node set (table of nodes) corresponding to a given xpath. resulting node set should be roxml_release when not used anymore (but not individual nodes)

Parameters
nis one node of the tree
paththe xpath to use
nb_ansthe number of results
Returns
the node table or NULL

handled xpath are described in xpath handling

Definition at line 167 of file roxml_stub.c.