Nut/OS  4.10.3
API Reference
XML Parser

XML Parser for tiny systems. More...

Collaboration diagram for XML Parser:

Defines

#define MAX_UXMLTAG_SIZE   512
 Maximum tag size including brackets.
#define MAX_UXMLTKN_SIZE   64
 Maximum token size.

Functions

char * UxmlParseTag (char *data, char *tkn, size_t size)
 Retrieve the next token from an XML tag.
int UxmlFilterMatch (char *name, char **filt)
 Check if name matches filter list.
UXML_NODEUxmlParseStream (FILE *stream, char **f_tags, char **f_attr)
 Parse XML stream.
UXML_NODEUxmlNodeCreate (char *name)
 Allocate a new tree node.
int UxmlNodeAddAttrib (UXML_NODE *node, char *name, char *value)
 Add an attribute to the specified node.
UXML_NODEUxmlTreeAddSibling (UXML_NODE *node, UXML_NODE *sibling)
 Add a sibling to the specified node.
UXML_NODEUxmlTreeAddChild (UXML_NODE *node, UXML_NODE *child)
 Add a child to the specified node.
void UxmlTreeDestroy (UXML_NODE *node)
 Release all memory of an XML tree structure.

Detailed Description

XML Parser for tiny systems.


Define Documentation

#define MAX_UXMLTAG_SIZE   512

Maximum tag size including brackets.

Larger tags will be silently discarded.

Definition at line 64 of file uxmlstream.c.

Referenced by UxmlParseStream().

#define MAX_UXMLTKN_SIZE   64

Maximum token size.

Larger tokens will be cut to the specified size. This may be fine for attribute values containing lengthy descriptions, but may be disastrous for tag or attribute names.

Definition at line 75 of file uxmlstream.c.

Referenced by UxmlParseStream().


Function Documentation

char* UxmlParseTag ( char *  data,
char *  tkn,
size_t  size 
)

Retrieve the next token from an XML tag.

Parameters:
dataPointer to the next character within the string to parse.
tknPointer to the buffer that receives the next token.
sizeSize of the token buffer.
Returns:
Pointer to the character following the one parsed last.

Definition at line 63 of file uxmlparse.c.

Referenced by UxmlParseStream().

int UxmlFilterMatch ( char *  name,
char **  filt 
)

Check if name matches filter list.

Parameters:
nameString to check against list.
filtArray of filter strings.
Returns:
1 if the name matches at list one filter string. Otherwise 0 is returned.

Definition at line 112 of file uxmlparse.c.

References strcasecmp.

Referenced by UxmlParseStream().

UXML_NODE* UxmlParseStream ( FILE stream,
char **  f_tags,
char **  f_attr 
)

Parse XML stream.

This is the main routine of the Micro XML Stream Parser. It reads the XML document from a previously opened stream and creates a corresponding tree structure.

Note, that this is a minimal and probably incomplete implementation, which had been specifically created to parse the SHOUTcast radio station list. On the other hand, it offers a practical XML parser solution for embedded systems with very low memory resources. Unlike most other implementations, it does not require to copy the whole XML document into internal memory. Instead, the parser reads and interprets individual tags. Furthermore, the caller may specify tag and attribute filters to reduce the resulting tree size. Be aware, that because of filtering the root of the tree may have siblings.

Normally the parser will return when the end of a file is reached. On TCP connections this may be either on connection close or timeout. If closing and re-opening connections may create too much overhead and timeouts are too slow, an EOF (ASCII 0) may be sent alternatively.

Parameters:
streamThe stream to read from.
f_tagsOptional tag filter, which points to an array of tag names to include. All other tags will be discarded. This can be used to limit memory consumption of the tree structure. Note, that this filtering may result in a tree structure, which is different from the structure of the original document. Set to NULL to disable tag filtering.
f_attrOptional attribute filter, which points to an array of attribute names to include. All other attributes will be discarded. Like the tag filter, it can be used to limit memory consumption of the tree structure. Set to NULL to disable attribute filtering.
Returns:
Pointer to a newly allocated UXML_NODE tree structure. NULL may be returned in case of an error. The caller should use UxmlTreeDestroy() to release the memory allocated by the tree.

Definition at line 192 of file uxmlstream.c.

References free(), malloc(), MAX_UXMLTAG_SIZE, MAX_UXMLTKN_SIZE, NutHeapAvailable, strcasecmp, strdup(), strlen(), UxmlFilterMatch(), UxmlNodeAddAttrib(), UxmlNodeCreate(), UxmlParseTag(), UxmlTreeAddChild(), UxmlTreeAddSibling(), _UXML_NODE::xmln_name, and _UXML_NODE::xmln_parent.

Here is the call graph for this function:

UXML_NODE* UxmlNodeCreate ( char *  name)

Allocate a new tree node.

Parameters:
nameName of the node to add.
Returns:
Pointer to the new node. In case of an error, NULL is returned.

Definition at line 63 of file uxmltree.c.

References malloc(), memcpy(), memset(), strlen(), and _UXML_NODE::xmln_name.

Referenced by UxmlParseStream().

Here is the call graph for this function:

int UxmlNodeAddAttrib ( UXML_NODE node,
char *  name,
char *  value 
)

Add an attribute to the specified node.

Parameters:
nodeThe attribute is added to this node.
nameAttribute's name.
valueAttribute's value.
Returns:
0 on success, -1 otherwise.

Definition at line 87 of file uxmltree.c.

References free(), malloc(), strdup(), _UXML_ATTRIB::xmla_name, _UXML_ATTRIB::xmla_next, _UXML_ATTRIB::xmla_value, and _UXML_NODE::xmln_attribs.

Referenced by UxmlParseStream().

Here is the call graph for this function:

UXML_NODE* UxmlTreeAddSibling ( UXML_NODE node,
UXML_NODE sibling 
)

Add a sibling to the specified node.

Parameters:
nodeThe sibling is added to this node.
childSibling to add.
Returns:
Pointer to the sibling node.

Definition at line 153 of file uxmltree.c.

References _UXML_NODE::xmln_next, and _UXML_NODE::xmln_parent.

Referenced by UxmlParseStream(), and UxmlTreeAddChild().

UXML_NODE* UxmlTreeAddChild ( UXML_NODE node,
UXML_NODE child 
)

Add a child to the specified node.

Parameters:
nodeThe child is added to this node.
childChild to add.
Returns:
Pointer to the child node.

Definition at line 174 of file uxmltree.c.

References UxmlTreeAddSibling(), _UXML_NODE::xmln_child, and _UXML_NODE::xmln_parent.

Referenced by UxmlParseStream().

Here is the call graph for this function:

void UxmlTreeDestroy ( UXML_NODE node)

Release all memory of an XML tree structure.

Parameters:
nodePointer to the root entry.

Definition at line 190 of file uxmltree.c.

References UxmlTreeDestroy(), _UXML_NODE::xmln_child, and _UXML_NODE::xmln_next.

Referenced by UxmlTreeDestroy().

Here is the call graph for this function: