# XML Node Sets

**API Group:** `xmlsec_core_nodeset`

XML node-set implementation used during transformations.

XML nodes set functions.

## Typedefs

### `xmlSecNodeSetWalkCallback`

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

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L69)

Node walk callback, called once per node in the nodes set.

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.

---

## Enumerations

### `xmlSecNodeSetType`

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L26)

The basic nodes sets types.

| Value | Initializer | Description |
|-------|-------------|-------------|
| `xmlSecNodeSetNormal` | `= 0` |  |
| `xmlSecNodeSetInvert` | `` |  |
| `xmlSecNodeSetTree` | `` |  |
| `xmlSecNodeSetTreeWithoutComments` | `` |  |
| `xmlSecNodeSetTreeInvert` | `` |  |
| `xmlSecNodeSetTreeWithoutCommentsInvert` | `` |  |
| `xmlSecNodeSetList` | `` |  |

---

### `xmlSecNodeSetOp`

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L39)

The simple nodes sets operations.

| Value | Initializer | Description |
|-------|-------------|-------------|
| `xmlSecNodeSetIntersection` | `= 0` |  |
| `xmlSecNodeSetSubtraction` | `` |  |
| `xmlSecNodeSetUnion` | `` |  |

---

## Functions

### `xmlSecNodeSetCreate`

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

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L74)

Creates a new nodes set.

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`

```c
void xmlSecNodeSetDestroy(xmlSecNodeSetPtr nset);
```

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L77)

Destroys a nodes set.

Destroys the nodes set created with `xmlSecNodeSetCreate` function. 

**Parameters:**

- `nset` — the pointer to node set.

---

### `xmlSecNodeSetDocDestroy`

```c
void xmlSecNodeSetDocDestroy(xmlSecNodeSetPtr nset);
```

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L78)

Marks node set to destroy the parent document.

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

**Parameters:**

- `nset` — the pointer to node set.

---

### `xmlSecNodeSetContains`

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

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L79)

Checks if a node is in the nodes set.

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`

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

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L82)

Adds a nodes set to another with an operation.

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`

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

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L85)

Adds a nodes set as a child list.

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`

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

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L88)

Creates a nodes set from parent subtree children.

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`

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

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L92)

Walks all nodes in a set calling a callback function.

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`

```c
int xmlSecNodeSetDumpTextNodes(xmlSecNodeSetPtr nset, xmlOutputBufferPtr out);
```

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L95)

Dumps text node content from a nodes set.

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`

```c
void xmlSecNodeSetDebugDump(xmlSecNodeSetPtr nset, FILE *output);
```

*Source:* [include/xmlsec/nodeset.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/nodeset.h#L97)

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

**Parameters:**

- `nset` — the pointer to node set.
- `output` — the pointer to output FILE.

---