roxml_content.c File Reference

XML content access module. More...

#include <string.h>
#include <stdlib.h>
#include "roxml_mem.h"
#include "roxml_file.h"
#include "roxml_buff.h"

Go to the source code of this file.

Data Structures
struct	roxml_escape_char

Functions
ROXML_API int	roxml_escape (const char *buf, int decode, char *out)
	XML encoding/decoding function.
ROXML_STATIC ROXML_INT int	roxml_read (int pos, int size, char *buffer, node_t *node)
	read xml doc function
ROXML_STATIC ROXML_INT int	roxml_content_size (node_t *n, int *offset)
ROXML_STATIC ROXML_INT char *	roxml_prepare_buffer (node_t *n, char *buffer, int contentsize, int size)
ROXML_API char *	roxml_get_content (node_t *n, char *buffer, int bufsize, int *size)
	content getter function
ROXML_STATIC ROXML_INT int	roxml_name_size (node_t *n, int size, int *offset)
ROXML_API char *	roxml_get_name (node_t *n, char *buffer, int size)
	name getter function
ROXML_API int	roxml_get_nodes_nb (node_t *n, int type)
	number of nodes getter function
ROXML_STATIC ROXML_INT node_t *	roxml_get_nodes_by_name (node_t *n, int type, char *name)
ROXML_STATIC ROXML_INT node_t *	roxml_get_nodes_by_nth (node_t *n, int type, int nth)
ROXML_API node_t *	roxml_get_nodes (node_t *n, int type, char *name, int nth)
	nodes getter function
ROXML_API node_t *	roxml_get_ns (node_t *n)
	namespace getter function
ROXML_API int	roxml_get_pi_nb (node_t *n)
	process-instruction number getter function
ROXML_API node_t *	roxml_get_pi (node_t *n, int nth)
	process-instruction getter function
ROXML_API int	roxml_get_cmt_nb (node_t *n)
	comments number getter function
ROXML_API node_t *	roxml_get_cmt (node_t *n, int nth)
	comment getter function
ROXML_API int	roxml_get_txt_nb (node_t *n)
	text node number getter function
ROXML_API node_t *	roxml_get_txt (node_t *n, int nth)
	text node getter function
ROXML_API int	roxml_get_attr_nb (node_t *n)
	number of attribute getter function
ROXML_API node_t *	roxml_get_attr (node_t *n, char *name, int nth)
	attribute getter function
ROXML_API int	roxml_get_chld_nb (node_t *n)
	chlds number getter function
ROXML_API node_t *	roxml_get_chld (node_t *n, char *name, int nth)
	chld getter function
ROXML_API int	roxml_get_type (node_t *n)
	node type function
ROXML_API int	roxml_get_node_position (node_t *n)
	node get position function

Variables
struct roxml_escape_char	specials [5]

Detailed Description

XML content access 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_content.c.

Function Documentation

roxml_content_size()

ROXML_STATIC ROXML_INT int roxml_content_size ( node_t *  n, int *  offset  )

inline

Definition at line 88 of file roxml_content.c.

roxml_escape()

roxml_escape	(	const char *	buf,
		int	decode,
		char *	out
	)

XML encoding/decoding function.

this function converts the escape codes into ascii char or special carachers in escape codes.

Parameters

buf	the bytes to be converted
decode	indicates whether to encde or decode escape caracteres.
out	is filled with the encoded/decoded data if not null.

Returns

the size of encoded/decoded data

See also

roxml_add_node

ENCODE

DECODE

Definition at line 31 of file roxml_content.c.

roxml_get_attr()

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

n	is one node of the tree
name	is the name of the attribute to get
nth	the 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 444 of file roxml_content.c.

roxml_get_attr_nb()

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

n	is one node of the tree

Returns

the number of attributes in node

Definition at line 439 of file roxml_content.c.

roxml_get_chld()

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

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

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 454 of file roxml_content.c.

roxml_get_chld_nb()

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

n	is one node of the tree

Returns

the number of chlildren

Definition at line 449 of file roxml_content.c.

roxml_get_cmt()

node_t * roxml_get_cmt ( node_t *  n, int  nth  )

inline

comment getter function

This function returns the nth comment of a node

Parameters

n	is one node of the tree
nth	is 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 424 of file roxml_content.c.

roxml_get_cmt_nb()

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

n	is one node of the tree

Returns

the number of comments

See also

roxml_get_cmt_nb

roxml_get_nodes

Definition at line 419 of file roxml_content.c.

roxml_get_content()

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

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 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 148 of file roxml_content.c.

roxml_get_name()

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

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

Returns

the name of the node (return our buffer pointer if it wasn't NULL)

See also

roxml_release

Definition at line 225 of file roxml_content.c.

roxml_get_node_position()

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

n	is the node to test

Returns

the postion between 1 and N

Definition at line 466 of file roxml_content.c.

roxml_get_nodes()

char * 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

n	is one node of the tree
type	is the bitmask of node types we want to consider
name	is 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
nth	the 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 394 of file roxml_content.c.

roxml_get_nodes_by_name()

ROXML_STATIC ROXML_INT node_t * roxml_get_nodes_by_name ( node_t *  n, int  type, char *  name  )

inline

Definition at line 336 of file roxml_content.c.

roxml_get_nodes_by_nth()

ROXML_STATIC ROXML_INT node_t * roxml_get_nodes_by_nth ( node_t *  n, int  type, int  nth  )

inline

Definition at line 357 of file roxml_content.c.

roxml_get_nodes_nb()

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

n	is one node of the tree
type	is 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_1 = roxml_get_nodes_nb(root, ROXML_ELM_NODE | ROXML_CMT_NODE | ROXML_PI_NODE | ROXML_TXT_NODE | ROXML_ATTR_NODE);
     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 308 of file roxml_content.c.

roxml_get_ns()

node_t * roxml_get_ns ( node_t *  n )

inline

namespace getter function

This function returns the namespace of a node

Parameters

n	is 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 404 of file roxml_content.c.

roxml_get_pi()

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

n	is one node of the tree
nth	is 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 414 of file roxml_content.c.

roxml_get_pi_nb()

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

n	is one node of the tree

Returns

the number of process-instructions

See also

roxml_get_pi

roxml_get_nodes_nb

Definition at line 409 of file roxml_content.c.

roxml_get_txt()

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

n	the node that contains text
nth	the 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 434 of file roxml_content.c.

roxml_get_txt_nb()

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

n	the node to search into

Returns

the number of text node

See also

roxml_get_txt

Definition at line 429 of file roxml_content.c.

roxml_get_type()

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

n	is the node to test

Returns

the node type

Definition at line 459 of file roxml_content.c.

roxml_name_size()

ROXML_STATIC ROXML_INT int roxml_name_size ( node_t *  n, int  size, int *  offset  )

inline

Definition at line 200 of file roxml_content.c.

roxml_prepare_buffer()

ROXML_STATIC ROXML_INT char * roxml_prepare_buffer ( node_t *  n, char *  buffer, int  contentsize, int  size  )

inline

Definition at line 134 of file roxml_content.c.

roxml_read()

roxml_read ( int  pos, int  size, char *  buffer, node_t *  node  )

inline

read xml doc function

this function read inside a xml doc (file or buffer) and fill the given buffer

Parameters

pos	the pos in the xml document
size	the size of the data to read
buffer	the destination buffer
node	the node that belong to the tree we want to read to

Returns

the number of bytes read

Definition at line 74 of file roxml_content.c.

Variable Documentation

specials

struct roxml_escape_char specials[5]

Initial value:

= {
        { .code = '"', .escape = """ },
        { .code = '\'', .escape = "'" },
        { .code = '<', .escape = "&lt;"},
        { .code = '>', .escape = "&gt;"},
        { .code = '&', .escape = "&amp;"}
}

Definition at line 23 of file roxml_content.c.