nodeset: XML Security Library Reference Manual

## nodeset nodeset — XML nodes set functions |

## Stability Level

Stable, unless otherwise indicated

## Functions

int | (*xmlSecNodeSetWalkCallback) ()
xmlSecNodeSetPtr | xmlSecNodeSetCreate ()
void | xmlSecNodeSetDestroy ()
void | xmlSecNodeSetDocDestroy ()
int | xmlSecNodeSetContains ()
xmlSecNodeSetPtr | xmlSecNodeSetAdd ()
xmlSecNodeSetPtr | xmlSecNodeSetAddList ()
xmlSecNodeSetPtr | xmlSecNodeSetGetChildren ()
int | xmlSecNodeSetWalk ()
int | xmlSecNodeSetDumpTextNodes ()
void | xmlSecNodeSetDebugDump ()

## Types and Values

enum | xmlSecNodeSetType
enum | xmlSecNodeSetOp
struct | xmlSecNodeSet

## Description

## Functions

### xmlSecNodeSetWalkCallback ()

    int
    (*xmlSecNodeSetWalkCallback) (xmlSecNodeSetPtr nset,
                                  xmlNodePtr cur,
                                  xmlNodePtr parent,
                                  void *data);

The callback function called once per each node in the nodes set.

#### Parameters

nset | the pointer to xmlSecNodeSet structure. |
cur | the pointer current XML node. |
parent | the pointer to the `cur` parent node. |
data | the pointer to application specific data. |

#### Returns

0 on success or a negative value if an error occurs an walk procedure should be interrupted.

### xmlSecNodeSetCreate ()

    xmlSecNodeSetPtr
    xmlSecNodeSetCreate (xmlDocPtr doc,
                         xmlNodeSetPtr nodes,
                         xmlSecNodeSetType type);

Creates new nodes set. Caller is responsible for freeing returned object by calling xmlSecNodeSetDestroy function.

#### Parameters

doc | the pointer to parent XML document. |
nodes | the list of nodes. |
type | the nodes set type. |

#### Returns

pointer to newly allocated node set or NULL if an error occurs.

### xmlSecNodeSetDestroy ()

    void
    xmlSecNodeSetDestroy (xmlSecNodeSetPtr nset);

Destroys the nodes set created with xmlSecNodeSetCreate function.

#### Parameters

nset | the pointer to node set. |

### xmlSecNodeSetDocDestroy ()

    void
    xmlSecNodeSetDocDestroy (xmlSecNodeSetPtr nset);

Instructs node set to destroy nodes parent doc when node set is destroyed.

#### Parameters

nset | the pointer to node set. |

### xmlSecNodeSetContains ()

    int
    xmlSecNodeSetContains (xmlSecNodeSetPtr nset,
                           xmlNodePtr node,
                           xmlNodePtr parent);

Checks whether the `node` is in the nodes set or not.

#### Parameters

nset | the pointer to node set. |
node | the pointer to XML node to check. |
parent | the pointer to `node` parent node. |

#### Returns

1 if the `node` is in the nodes set `nset` , 0 if it is not and a negative value if an error occurs.

### xmlSecNodeSetAdd ()

    xmlSecNodeSetPtr
    xmlSecNodeSetAdd (xmlSecNodeSetPtr nset,
                      xmlSecNodeSetPtr newNSet,
                      xmlSecNodeSetOp op);

Adds `newNSet` to the `nset` using operation `op` .

#### Parameters

nset | the pointer to current nodes set (or NULL). |
newNSet | the pointer to new nodes set. |
op | the operation type. |

#### Returns

the pointer to combined nodes set or NULL if an error occurs.

### xmlSecNodeSetAddList ()

    xmlSecNodeSetPtr
    xmlSecNodeSetAddList (xmlSecNodeSetPtr nset,
                          xmlSecNodeSetPtr newNSet,
                          xmlSecNodeSetOp op);

Adds `newNSet` to the `nset` as child using operation `op` .

#### Parameters

nset | the pointer to current nodes set (or NULL). |
newNSet | the pointer to new nodes set. |
op | the operation type. |

#### Returns

the pointer to combined nodes set or NULL if an error occurs.

### xmlSecNodeSetGetChildren ()

    xmlSecNodeSetPtr
    xmlSecNodeSetGetChildren (xmlDocPtr doc,
                              const xmlNodePtr parent,
                              int withComments,
                              int invert);

Creates a new nodes set that contains:

- if `withComments` is not 0 and `invert` is 0: all nodes in the `parent` subtree;

- if `withComments` is 0 and `invert` is 0: all nodes in the `parent` subtree except comment nodes;

- if `withComments` is not 0 and `invert` not is 0: all nodes in the `doc` except nodes in the `parent` subtree;

- if `withComments` is 0 and `invert` is 0: all nodes in the `doc` except nodes in the `parent` subtree and comment nodes.

#### Parameters

doc | the pointer to an XML document. |
parent | the pointer to parent XML node or NULL if we want to include all document nodes. |
withComments | the flag include comments or not. |
invert | the "invert" flag. |

#### Returns

pointer to the newly created xmlSecNodeSet structure or NULL if an error occurs.

### xmlSecNodeSetWalk ()

    int
    xmlSecNodeSetWalk (xmlSecNodeSetPtr nset,
                       xmlSecNodeSetWalkCallback walkFunc,
                       void *data);

Calls the function `walkFunc` once per each node in the nodes set `nset` . If the `walkFunc` returns a negative value, then the walk procedure is interrupted.

#### Parameters

nset | the pointer to node set. |
walkFunc | the callback functions. |
data | the application specific data passed to the `walkFunc` . |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecNodeSetDumpTextNodes ()

    int
    xmlSecNodeSetDumpTextNodes (xmlSecNodeSetPtr nset,
                                xmlOutputBufferPtr out);

Dumps content of all the text nodes from `nset` to `out` .

#### Parameters

nset | the pointer to node set. |
out | the output buffer. |

#### Returns

0 on success or a negative value otherwise.

### xmlSecNodeSetDebugDump ()

    void
    xmlSecNodeSetDebugDump (xmlSecNodeSetPtr nset,
                            FILE *output);

Prints information about `nset` to the `output` .

#### Parameters

nset | the pointer to node set. |
output | the pointer to output FILE. |

## Types and Values

### enum xmlSecNodeSetType

The basic nodes sets types.

#### Members

xmlSecNodeSetNormal | nodes set = nodes in the list. |
xmlSecNodeSetInvert | nodes set = all document nodes minus nodes in the list. |
xmlSecNodeSetTree | nodes set = nodes in the list and all their subtress. |
xmlSecNodeSetTreeWithoutComments | nodes set = nodes in the list and all their subtress but no comment nodes. |
xmlSecNodeSetTreeInvert | nodes set = all document nodes minus nodes in the list and all their subtress. |
xmlSecNodeSetTreeWithoutCommentsInvert | nodes set = all document nodes minus (nodes in the list and all their subtress plus all comment nodes). |
xmlSecNodeSetList | nodes set = all nodes in the children list of nodes sets. |

### enum xmlSecNodeSetOp

The simple nodes sets operations.

#### Members

xmlSecNodeSetIntersection | intersection. |
xmlSecNodeSetSubtraction | subtraction. |
xmlSecNodeSetUnion | union. |

### struct xmlSecNodeSet

    struct xmlSecNodeSet {
        xmlNodeSetPtr       nodes;
        xmlDocPtr           doc;
        int                 destroyDoc;
        xmlSecNodeSetType   type;
        xmlSecNodeSetOp     op;
        xmlSecNodeSetPtr    next;
        xmlSecNodeSetPtr    prev;
        xmlSecNodeSetPtr    children;
    };

The enchanced nodes set.

#### Members

xmlNodeSetPtr `nodes`; | the nodes list. |
xmlDocPtr `doc`; | the parent XML document. |
int `destroyDoc`; | the flag: if set to 1 then `doc` will be destroyed when node set is destroyed. |
xmlSecNodeSetType `type`; | the nodes set type. |
xmlSecNodeSetOp `op`; | the operation type. |
xmlSecNodeSetPtr `next`; | the next nodes set. |
xmlSecNodeSetPtr `prev`; | the previous nodes set. |
xmlSecNodeSetPtr `children`; | the children list (valid only if type equal to xmlSecNodeSetList). |