- Home
- Download
- News
- Documentation

- FAQ
- Tutorial
- API reference
- Examples

- XML Digital Signature

- Online Verifier

- XML Encryption
- XML Canonicalization
- Reporting Bugs
- Mailing list
- Related
- Authors

# xmltree

## Name

xmltree --

## Synopsis

    #define     xmlSecNodeGetName               (node)
    const xmlChar* xmlSecGetNodeNsHref          (const xmlNodePtr cur);
    int         xmlSecCheckNodeName             (const xmlNodePtr cur,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);
    xmlNodePtr  xmlSecGetNextElementNode        (xmlNodePtr cur);
    xmlNodePtr  xmlSecFindChild                 (const xmlNodePtr parent,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);
    xmlNodePtr  xmlSecFindParent                (const xmlNodePtr cur,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);
    xmlNodePtr  xmlSecFindNode                  (const xmlNodePtr parent,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);
    xmlNodePtr  xmlSecAddChild                  (xmlNodePtr parent,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);
    xmlNodePtr  xmlSecAddChildNode              (xmlNodePtr parent,
                                                 xmlNodePtr child);
    xmlNodePtr  xmlSecAddNextSibling            (xmlNodePtr node,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);
    xmlNodePtr  xmlSecAddPrevSibling            (xmlNodePtr node,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);
    int         xmlSecReplaceNode               (xmlNodePtr node,
                                                 xmlNodePtr newNode);
    int         xmlSecReplaceContent            (xmlNodePtr node,
                                                 xmlNodePtr newNode);
    int         xmlSecReplaceNodeBuffer         (xmlNodePtr node,
                                                 const xmlSecByte *buffer,
                                                 xmlSecSize size);
    void        xmlSecAddIDs                    (xmlDocPtr doc,
                                                 xmlNodePtr cur,
                                                 const xmlChar **ids);
    int         xmlSecGenerateAndAddID          (xmlNodePtr node,
                                                 const xmlChar *attrName,
                                                 const xmlChar *prefix,
                                                 xmlSecSize len);
    xmlChar*    xmlSecGenerateID                (const xmlChar *prefix,
                                                 xmlSecSize len);
    xmlDocPtr   xmlSecCreateTree                (const xmlChar *rootNodeName,
                                                 const xmlChar *rootNodeNs);
    int         xmlSecIsEmptyNode               (xmlNodePtr node);
    int         xmlSecIsEmptyString             (const xmlChar *str);
    xmlChar*    xmlSecGetQName                  (xmlNodePtr node,
                                                 const xmlChar *href,
                                                 const xmlChar *local);
    #define     xmlSecIsHex                     (c)
    #define     xmlSecGetHex                    (c)
    typedef     xmlSecQName2IntegerInfoConstPtr;
    struct      xmlSecQName2IntegerInfo;
    xmlSecQName2IntegerInfoConstPtr xmlSecQName2IntegerGetInfo
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 int intValue);
    int         xmlSecQName2IntegerGetInteger   (xmlSecQName2IntegerInfoConstPtr info,
                                                 const xmlChar *qnameHref,
                                                 const xmlChar *qnameLocalPart,
                                                 int *intValue);
    int         xmlSecQName2IntegerGetIntegerFromString
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *qname,
                                                 int *intValue);
    xmlChar*    xmlSecQName2IntegerGetStringFromInteger
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 int intValue);
    int         xmlSecQName2IntegerNodeRead     (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 int *intValue);
    int         xmlSecQName2IntegerNodeWrite    (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *nodeName,
                                                 const xmlChar *nodeNs,
                                                 int intValue);
    int         xmlSecQName2IntegerAttributeRead
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *attrName,
                                                 int *intValue);
    int         xmlSecQName2IntegerAttributeWrite
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *attrName,
                                                 int intValue);
    void        xmlSecQName2IntegerDebugDump    (xmlSecQName2IntegerInfoConstPtr info,
                                                 int intValue,
                                                 const xmlChar *name,
                                                 FILE *output);
    void        xmlSecQName2IntegerDebugXmlDump (xmlSecQName2IntegerInfoConstPtr info,
                                                 int intValue,
                                                 const xmlChar *name,
                                                 FILE *output);
    typedef     xmlSecBitMask;
    typedef     xmlSecQName2BitMaskInfoConstPtr;
    struct      xmlSecQName2BitMaskInfo;
    xmlSecQName2BitMaskInfoConstPtr xmlSecQName2BitMaskGetInfo
                                                (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlSecBitMask mask);
    int         xmlSecQName2BitMaskGetBitMask   (xmlSecQName2BitMaskInfoConstPtr info,
                                                 const xmlChar *qnameLocalPart,
                                                 const xmlChar *qnameHref,
                                                 xmlSecBitMask *mask);
    int         xmlSecQName2BitMaskNodesRead    (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlNodePtr *node,
                                                 const xmlChar *nodeName,
                                                 const xmlChar *nodeNs,
                                                 int stopOnUnknown,
                                                 xmlSecBitMask *mask);
    int         xmlSecQName2BitMaskGetBitMaskFromString
                                                (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *qname,
                                                 xmlSecBitMask *mask);
    xmlChar*    xmlSecQName2BitMaskGetStringFromBitMask
                                                (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 xmlSecBitMask mask);
    int         xmlSecQName2BitMaskNodesWrite   (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *nodeName,
                                                 const xmlChar *nodeNs,
                                                 xmlSecBitMask mask);
    void        xmlSecQName2BitMaskDebugDump    (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlSecBitMask mask,
                                                 const xmlChar *name,
                                                 FILE *output);
    void        xmlSecQName2BitMaskDebugXmlDump (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlSecBitMask mask,
                                                 const xmlChar *name,
                                                 FILE *output);

## Description

## Details

### xmlSecNodeGetName()

    #define     xmlSecNodeGetName(node)

Macro. Returns node's name.

node : | the pointer to node.

### xmlSecGetNodeNsHref ()

    const xmlChar* xmlSecGetNodeNsHref          (const xmlNodePtr cur);

Get's node's namespace href.

cur : | the pointer to node.
Returns : | node's namespace href.

### xmlSecCheckNodeName ()

    int         xmlSecCheckNodeName             (const xmlNodePtr cur,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);

Checks that the node has a given name and a given namespace href.

cur : | the pointer to an XML node.
name : | the name,
ns : | the namespace href.
Returns : | 1 if the node matches or 0 otherwise.

### xmlSecGetNextElementNode ()

    xmlNodePtr  xmlSecGetNextElementNode        (xmlNodePtr cur);

Seraches for the next element node.

cur : | the pointer to an XML node.
Returns : | the pointer to next element node or NULL if it is not found.

### xmlSecFindChild ()

    xmlNodePtr  xmlSecFindChild                 (const xmlNodePtr parent,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);

Searches a direct child of the parent node having given name and namespace href.

parent : | the pointer to XML node.
name : | the name.
ns : | the namespace href (may be NULL).
Returns : | the pointer to the found node or NULL if an error occurs or node is not found.

### xmlSecFindParent ()

    xmlNodePtr  xmlSecFindParent                (const xmlNodePtr cur,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);

Searches the ancestors axis of the cur node for a node having given name and namespace href.

cur : | the pointer to an XML node.
name : | the name.
ns : | the namespace href (may be NULL).
Returns : | the pointer to the found node or NULL if an error occurs or node is not found.

### xmlSecFindNode ()

    xmlNodePtr  xmlSecFindNode                  (const xmlNodePtr parent,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);

Searches all children of the parent node having given name and namespace href.

parent : | the pointer to XML node.
name : | the name.
ns : | the namespace href (may be NULL).
Returns : | the pointer to the found node or NULL if an error occurs or node is not found.

### xmlSecAddChild ()

    xmlNodePtr  xmlSecAddChild                  (xmlNodePtr parent,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);

Adds a child to the node parent with given name and namespace ns.

parent : | the pointer to an XML node.
name : | the new node name.
ns : | the new node namespace.
Returns : | pointer to the new node or NULL if an error occurs.

### xmlSecAddChildNode ()

    xmlNodePtr  xmlSecAddChildNode              (xmlNodePtr parent,
                                                 xmlNodePtr child);

Adds child node to the parent node.

parent : | the pointer to an XML node.
child : | the new node.
Returns : | pointer to the new node or NULL if an error occurs.

### xmlSecAddNextSibling ()

    xmlNodePtr  xmlSecAddNextSibling            (xmlNodePtr node,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);

Adds next sibling to the node node with given name and namespace ns.

node : | the pointer to an XML node.
name : | the new node name.
ns : | the new node namespace.
Returns : | pointer to the new node or NULL if an error occurs.

### xmlSecAddPrevSibling ()

    xmlNodePtr  xmlSecAddPrevSibling            (xmlNodePtr node,
                                                 const xmlChar *name,
                                                 const xmlChar *ns);

Adds prev sibling to the node node with given name and namespace ns.

node : | the pointer to an XML node.
name : | the new node name.
ns : | the new node namespace.
Returns : | pointer to the new node or NULL if an error occurs.

### xmlSecReplaceNode ()

    int         xmlSecReplaceNode               (xmlNodePtr node,
                                                 xmlNodePtr newNode);

Swaps the node and newNode in the XML tree.

node : | the current node.
newNode : | the new node.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecReplaceContent ()

    int         xmlSecReplaceContent            (xmlNodePtr node,
                                                 xmlNodePtr newNode);

Swaps the content of node and newNode.

node : | the current node.
newNode : | the new node.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecReplaceNodeBuffer ()

    int         xmlSecReplaceNodeBuffer         (xmlNodePtr node,
                                                 const xmlSecByte *buffer,
                                                 xmlSecSize size);

Swaps the node and the parsed XML data from the buffer in the XML tree.

node : | the current node.
buffer : | the XML data.
size : | the XML data size.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecAddIDs ()

    void        xmlSecAddIDs                    (xmlDocPtr doc,
                                                 xmlNodePtr cur,
                                                 const xmlChar **ids);

Walks thru all children of the cur node and adds all attributes from the ids list to the doc document IDs attributes hash.

doc : | the pointer to an XML document.
cur : | the pointer to an XML node.
ids : | the pointer to a NULL terminated list of ID attributes.

### xmlSecGenerateAndAddID ()

    int         xmlSecGenerateAndAddID          (xmlNodePtr node,
                                                 const xmlChar *attrName,
                                                 const xmlChar *prefix,
                                                 xmlSecSize len);

Generates a unique ID in the format <prefix>base64-encoded(len random bytes) and puts it in the attribute attrName.

node : | the node to ID attr to.
attrName : | the ID attr name.
prefix : | the prefix to add to the generated ID (can be NULL).
len : | the length of ID.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecGenerateID ()

    xmlChar*    xmlSecGenerateID                (const xmlChar *prefix,
                                                 xmlSecSize len);

Generates a unique ID in the format <prefix>base64-encoded(len random bytes). The caller is responsible for freeing returned string using xmlFree function.

prefix : | the prefix to add to the generated ID (can be NULL).
len : | the length of ID.
Returns : | pointer to generated ID string or NULL if an error occurs.

### xmlSecCreateTree ()

    xmlDocPtr   xmlSecCreateTree                (const xmlChar *rootNodeName,
                                                 const xmlChar *rootNodeNs);

Creates a new XML tree with one root node rootNodeName.

rootNodeName : | the root node name.
rootNodeNs : | the root node namespace (otpional).
Returns : | pointer to the newly created tree or NULL if an error occurs.

### xmlSecIsEmptyNode ()

    int         xmlSecIsEmptyNode               (xmlNodePtr node);

Checks whethere the node is empty (i.e. has only whitespaces children).

node : | the node to check
Returns : | 1 if node is empty, 0 otherwise or a negative value if an error occurs.

### xmlSecIsEmptyString ()

    int         xmlSecIsEmptyString             (const xmlChar *str);

Checks whethere the str is empty (i.e. has only whitespaces children).

str : | the string to check
Returns : | 1 if str is empty, 0 otherwise or a negative value if an error occurs.

### xmlSecGetQName ()

    xmlChar*    xmlSecGetQName                  (xmlNodePtr node,
                                                 const xmlChar *href,
                                                 const xmlChar *local);

Creates QName (prefix:local) from href and local in the context of the node. Caller is responsible for freeing returned string with xmlFree.

node : | the context node.
href : | the QName href (can be NULL).
local : | the QName local part.
Returns : | qname or NULL if an error occurs.

### xmlSecIsHex()

    #define     xmlSecIsHex(c)

Macro. Returns 1 if c is a hex digit or 0 other wise.

c : | the character.

### xmlSecGetHex()

    #define     xmlSecGetHex(c)

Macro. Returns the hex value of the c.

c : | the character,

### xmlSecQName2IntegerInfoConstPtr

    typedef const struct _xmlSecQName2IntegerInfo*		xmlSecQName2IntegerInfoConstPtr;

### struct xmlSecQName2IntegerInfo

    struct xmlSecQName2IntegerInfo {

        const xmlChar*      qnameHref;
        const xmlChar*      qnameLocalPart;
        int       		intValue;
    };

### xmlSecQName2IntegerGetInfo ()

    xmlSecQName2IntegerInfoConstPtr xmlSecQName2IntegerGetInfo
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 int intValue);

Maps integer intValue to a QName prefix.

info : | the qname<->integer mapping information.
intValue : | the integer value.
Returns : | the QName info that is mapped to intValue or NULL if such value is not found.

### xmlSecQName2IntegerGetInteger ()

    int         xmlSecQName2IntegerGetInteger   (xmlSecQName2IntegerInfoConstPtr info,
                                                 const xmlChar *qnameHref,
                                                 const xmlChar *qnameLocalPart,
                                                 int *intValue);

Maps qname qname to an integer and returns it in intValue.

info : | the qname<->integer mapping information.
qnameHref : | the qname href value.
qnameLocalPart : | the qname local part value.
intValue : | the pointer to result integer value.
Returns : | 0 on success or a negative value if an error occurs,

### xmlSecQName2IntegerGetIntegerFromString ()

    int         xmlSecQName2IntegerGetIntegerFromString
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *qname,
                                                 int *intValue);

info : |
node : |
qname : |
intValue : |
Returns : |

### xmlSecQName2IntegerGetStringFromInteger ()

    xmlChar*    xmlSecQName2IntegerGetStringFromInteger
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 int intValue);

Creates qname string for intValue in context of given node. Caller is responsible for freeing returned string with xmlFree.

info : | the qname<->integer mapping information.
node : | the pointer to node.
intValue : | the integer value.
Returns : | pointer to newly allocated string on success or NULL if an error occurs,

### xmlSecQName2IntegerNodeRead ()

    int         xmlSecQName2IntegerNodeRead     (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 int *intValue);

Reads the content of node and converts it to an integer using mapping from info.

info : | the qname<->integer mapping information.
node : | the pointer to node.
intValue : | the pointer to result integer value.
Returns : | 0 on success or a negative value if an error occurs,

### xmlSecQName2IntegerNodeWrite ()

    int         xmlSecQName2IntegerNodeWrite    (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *nodeName,
                                                 const xmlChar *nodeNs,
                                                 int intValue);

Creates new child node in node and sets its value to intValue.

info : | the qname<->integer mapping information.
node : | the parent node.
nodeName : | the child node name.
nodeNs : | the child node namespace.
intValue : | the integer value.
Returns : | 0 on success or a negative value if an error occurs,

### xmlSecQName2IntegerAttributeRead ()

    int         xmlSecQName2IntegerAttributeRead
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *attrName,
                                                 int *intValue);

Gets the value of attrName atrtibute from node and converts it to integer according to info.

info : | the qname<->integer mapping information.
node : | the element node.
attrName : | the attribute name.
intValue : | the pointer to result integer value.
Returns : | 0 on success or a negative value if an error occurs,

### xmlSecQName2IntegerAttributeWrite ()

    int         xmlSecQName2IntegerAttributeWrite
                                                (xmlSecQName2IntegerInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *attrName,
                                                 int intValue);

Converts intValue to a qname and sets it to the value of attribute attrName in node.

info : | the qname<->integer mapping information.
node : | the parent node.
attrName : | the name of attribute.
intValue : | the integer value.
Returns : | 0 on success or a negative value if an error occurs,

### xmlSecQName2IntegerDebugDump ()

    void        xmlSecQName2IntegerDebugDump    (xmlSecQName2IntegerInfoConstPtr info,
                                                 int intValue,
                                                 const xmlChar *name,
                                                 FILE *output);

Prints intValue into output.

info : | the qname<->integer mapping information.
intValue : | the integer value.
name : |
output : | the pointer to output FILE.

### xmlSecQName2IntegerDebugXmlDump ()

    void        xmlSecQName2IntegerDebugXmlDump (xmlSecQName2IntegerInfoConstPtr info,
                                                 int intValue,
                                                 const xmlChar *name,
                                                 FILE *output);

Prints intValue into output in XML format.

info : | the qname<->integer mapping information.
intValue : | the integer value.
name : |
output : | the pointer to output FILE.

### xmlSecBitMask

    typedef unsigned int                            	xmlSecBitMask;

### xmlSecQName2BitMaskInfoConstPtr

    typedef const struct _xmlSecQName2BitMaskInfo*		xmlSecQName2BitMaskInfoConstPtr;

### struct xmlSecQName2BitMaskInfo

    struct xmlSecQName2BitMaskInfo {

        const xmlChar*      qnameHref;
        const xmlChar*      qnameLocalPart;
        xmlSecBitMask       mask;
    };

### xmlSecQName2BitMaskGetInfo ()

    xmlSecQName2BitMaskInfoConstPtr xmlSecQName2BitMaskGetInfo
                                                (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlSecBitMask mask);

Converts mask to qname.

info : | the qname<->bit mask mapping information.
mask : | the bit mask.
Returns : | pointer to the qname info for mask or NULL if mask is unknown.

### xmlSecQName2BitMaskGetBitMask ()

    int         xmlSecQName2BitMaskGetBitMask   (xmlSecQName2BitMaskInfoConstPtr info,
                                                 const xmlChar *qnameLocalPart,
                                                 const xmlChar *qnameHref,
                                                 xmlSecBitMask *mask);

Converts qnameLocalPart to mask.

info : | the qname<->bit mask mapping information.
qnameLocalPart : | the qname LocalPart value.
qnameHref : | the qname Href value.
mask : | the pointer to result mask.
Returns : | 0 on success or a negative value if an error occurs,

### xmlSecQName2BitMaskNodesRead ()

    int         xmlSecQName2BitMaskNodesRead    (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlNodePtr *node,
                                                 const xmlChar *nodeName,
                                                 const xmlChar *nodeNs,
                                                 int stopOnUnknown,
                                                 xmlSecBitMask *mask);

Reads <nodeNs:nodeName> elements and puts the result bit mask into mask. When function exits, node points to the first element node after all the <nodeNs:nodeName> elements.

info : | the qname<->bit mask mapping information.
node : | the start.
nodeName : | the mask nodes name.
nodeNs : | the mask nodes namespace.
stopOnUnknown : | if this flag is set then function exits if unknown value was found.
mask : | the pointer to result mask.
Returns : | 0 on success or a negative value if an error occurs,

### xmlSecQName2BitMaskGetBitMaskFromString ()

    int         xmlSecQName2BitMaskGetBitMaskFromString
                                                (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *qname,
                                                 xmlSecBitMask *mask);

info : |
node : |
qname : |
mask : |
Returns : |

### xmlSecQName2BitMaskGetStringFromBitMask ()

    xmlChar*    xmlSecQName2BitMaskGetStringFromBitMask
                                                (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 xmlSecBitMask mask);

Creates qname string for mask in context of given node. Caller is responsible for freeing returned string with xmlFree.

info : | the qname<->integer mapping information.
node : | the pointer to node.
mask : | the mask.
Returns : | pointer to newly allocated string on success or NULL if an error occurs,

### xmlSecQName2BitMaskNodesWrite ()

    int         xmlSecQName2BitMaskNodesWrite   (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlNodePtr node,
                                                 const xmlChar *nodeName,
                                                 const xmlChar *nodeNs,
                                                 xmlSecBitMask mask);

Writes <nodeNs:nodeName> elemnts with values from mask to node.

info : | the qname<->bit mask mapping information.
node : | the parent element for mask nodes.
nodeName : | the mask nodes name.
nodeNs : | the mask nodes namespace.
mask : | the bit mask.
Returns : | 0 on success or a negative value if an error occurs,

### xmlSecQName2BitMaskDebugDump ()

    void        xmlSecQName2BitMaskDebugDump    (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlSecBitMask mask,
                                                 const xmlChar *name,
                                                 FILE *output);

Prints debug information about mask to output.

info : | the qname<->bit mask mapping information.
mask : | the bit mask.
name : |
output : | the pointer to output FILE.

### xmlSecQName2BitMaskDebugXmlDump ()

    void        xmlSecQName2BitMaskDebugXmlDump (xmlSecQName2BitMaskInfoConstPtr info,
                                                 xmlSecBitMask mask,
                                                 const xmlChar *name,
                                                 FILE *output);

Prints debug information about mask to output in XML format.

info : | the qname<->bit mask mapping information.
mask : | the bit mask.
name : |
output : | the pointer to output FILE.