# Generic List

**API Group:** `xmlsec_core_list`

Generic doubly-linked list implementation.

Generic list structure functions.

## Macros

### `xmlSecPtrListGetName`

*Defined as:* `(((list) != NULL) ? xmlSecPtrListKlassGetName((list)->id) : NULL)`

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

Macro. Returns lists's name.

**Parameters:**

- `list` — the ponter to list.

---

### `xmlSecPtrListIsValid`

*Defined as:* `((( list ) != NULL) && ((( list )->id) != NULL))`

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

Macro. Returns 1 if list is not NULL and list->id is not NULL.

Macro. Returns 1 if `list` is not NULL and `list->id` is not NULL or 0 otherwise. 

**Parameters:**

- `list` — the pointer to list.

---

### `xmlSecPtrListCheckId`

*Defined as:* `(xmlSecPtrListIsValid(( list )) && \
        ((( list )->id) == ( dataId )))`

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

Macro. Returns 1 if list is valid and list's id matches dataId.

Macro. Returns 1 if `list` is valid and `list's` id is equal to `dataId`. 

**Parameters:**

- `list` — the pointer to list.
- `dataId` — the list Id.

---

### `xmlSecPtrListIdUnknown`

*Defined as:* `NULL`

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

The "unknown" id.

---

### `xmlSecPtrListKlassGetName`

*Defined as:* `(((klass) != NULL) ? ((klass)->name) : NULL)`

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

Macro. Returns the list klass name.

**Parameters:**

- `klass` — the list klass.

---

### `xmlSecStringListId`

*Defined as:* `xmlSecStringListGetKlass()`

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

Strings list klass.

---

## Typedefs

### `xmlSecPtrListKlass`

```c
typedef const struct _xmlSecPtrListKlass xmlSecPtrListKlass;
```

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

The pointer list klass.

---

### `xmlSecPtrListId`

```c
typedef const struct _xmlSecPtrListKlass* xmlSecPtrListId;
```

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

Pointer to `xmlSecPtrListKlass`.

---

### `xmlSecPtrDuplicateItemMethod`

```c
typedef xmlSecPtr(* xmlSecPtrDuplicateItemMethod) (xmlSecPtr ptr))(xmlSecPtr ptr);
```

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

Duplicates item `ptr`.

**Parameters:**

- `ptr` — the poinetr to list item.


**Returns:** pointer to new item copy or NULL if an error occurs.

---

### `xmlSecPtrDestroyItemMethod`

```c
typedef void(* xmlSecPtrDestroyItemMethod) (xmlSecPtr ptr))(xmlSecPtr ptr);
```

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

Destroys list item `ptr`.

**Parameters:**

- `ptr` — the poinetr to list item.

---

### `xmlSecPtrDebugDumpItemMethod`

```c
typedef void(* xmlSecPtrDebugDumpItemMethod) (xmlSecPtr ptr, FILE *output))(xmlSecPtr ptr, FILE *output);
```

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

Prints debug information about `item` to `output`.

**Parameters:**

- `ptr` — the poinetr to list item.
- `output` — the output FILE.

---

## Functions

### `xmlSecPtrListSetDefaultAllocMode`

```c
void xmlSecPtrListSetDefaultAllocMode(xmlSecAllocMode defAllocMode, xmlSecSize defInitialSize);
```

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

Sets the default allocation mode and initial list size.

Sets new default allocation mode and minimal initial list size. 

**Parameters:**

- `defAllocMode` — the new default memory allocation mode.
- `defInitialSize` — the new default minimal initial size.

---

### `xmlSecPtrListInitialize`

```c
int xmlSecPtrListInitialize(xmlSecPtrListPtr list, xmlSecPtrListId id);
```

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

Initializes a list object.

Initializes the list of given klass. Caller is responsible for cleaning up by calling `xmlSecPtrListFinalize` function. 

**Parameters:**

- `list` — the pointer to list.
- `id` — the list klass.


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

---

### `xmlSecPtrListFinalize`

```c
void xmlSecPtrListFinalize(xmlSecPtrListPtr list);
```

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

Cleans up a list object.

Cleans up the list initialized with `xmlSecPtrListInitialize` function. 

**Parameters:**

- `list` — the pointer to list.

---

### `xmlSecPtrListCreate`

```c
xmlSecPtrListPtr xmlSecPtrListCreate(xmlSecPtrListId id);
```

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

Creates a new list object.

Creates new list object. Caller is responsible for freeing returned list by calling `xmlSecPtrListDestroy` function. 

**Parameters:**

- `id` — the list klass.


**Returns:** pointer to newly allocated list or NULL if an error occurs.

---

### `xmlSecPtrListDestroy`

```c
void xmlSecPtrListDestroy(xmlSecPtrListPtr list);
```

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

Destroys a list object.

Destroys `list` created with `xmlSecPtrListCreate` function. 

**Parameters:**

- `list` — the pointer to list.

---

### `xmlSecPtrListEmpty`

```c
void xmlSecPtrListEmpty(xmlSecPtrListPtr list);
```

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

Remove all items from `list` (if any).

**Parameters:**

- `list` — the pointer to list.

---

### `xmlSecPtrListCopy`

```c
int xmlSecPtrListCopy(xmlSecPtrListPtr dst, xmlSecPtrListPtr src);
```

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

Copies items from one list to another.

Copies `src` list items to `dst` list using duplicateItem method of the list klass. If duplicateItem method is NULL then we jsut copy pointers to items. 

**Parameters:**

- `dst` — the pointer to destination list.
- `src` — the pointer to source list.


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

---

### `xmlSecPtrListDuplicate`

```c
xmlSecPtrListPtr xmlSecPtrListDuplicate(xmlSecPtrListPtr list);
```

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

Creates a new copy of `list` and all its items.

**Parameters:**

- `list` — the pointer to list.


**Returns:** pointer to newly allocated list or NULL if an error occurs.

---

### `xmlSecPtrListGetSize`

```c
xmlSecSize xmlSecPtrListGetSize(xmlSecPtrListPtr list);
```

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

Gets list size.

**Parameters:**

- `list` — the pointer to list.


**Returns:** the number of items in `list`.

---

### `xmlSecPtrListGetItem`

```c
xmlSecPtr xmlSecPtrListGetItem(xmlSecPtrListPtr list, xmlSecSize pos);
```

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

Gets item from the list.

**Parameters:**

- `list` — the pointer to list.
- `pos` — the item position.


**Returns:** the list item at position `pos` or NULL if `pos` is greater than the number of items in the list or an error occurs.

---

### `xmlSecPtrListAdd`

```c
int xmlSecPtrListAdd(xmlSecPtrListPtr list, xmlSecPtr item);
```

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

Adds `item` to the end of the `list`.

**Parameters:**

- `list` — the pointer to list.
- `item` — the item.


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

---

### `xmlSecPtrListInsert`

```c
int xmlSecPtrListInsert(xmlSecPtrListPtr list, xmlSecPtr item, xmlSecSize pos);
```

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

Inserts an item at the given position.

Inserts `item` at the position `pos` in the `list`. 

**Parameters:**

- `list` — the pointer to list.
- `item` — the item.
- `pos` — the position to insert at.


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

---

### `xmlSecPtrListSet`

```c
int xmlSecPtrListSet(xmlSecPtrListPtr list, xmlSecPtr item, xmlSecSize pos);
```

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

Sets a list item at the given position.

Sets the value of list item at position `pos`. The old value is destroyed. 

**Parameters:**

- `list` — the pointer to list.
- `item` — the item.
- `pos` — the pos.


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

---

### `xmlSecPtrListRemove`

```c
int xmlSecPtrListRemove(xmlSecPtrListPtr list, xmlSecSize pos);
```

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

Destroys a list item at the given position.

Destroys list item at the position `pos` and sets it value to NULL. 

**Parameters:**

- `list` — the pointer to list.
- `pos` — the position.


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

---

### `xmlSecPtrListRemoveAndReturn`

```c
xmlSecPtr xmlSecPtrListRemoveAndReturn(xmlSecPtrListPtr list, xmlSecSize pos);
```

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

Removes and returns a list item.

Remove the list item at the position `pos` and return it back. 

**Parameters:**

- `list` — the pointer to list.
- `pos` — the position.


**Returns:** the pointer to the list item.

---

### `xmlSecPtrListDebugDump`

```c
void xmlSecPtrListDebugDump(xmlSecPtrListPtr list, FILE *output);
```

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

Prints debug info about a list.

Prints debug information about `list` to the `output`. 

**Parameters:**

- `list` — the pointer to list.
- `output` — the pointer to output FILE.

---

### `xmlSecPtrListDebugXmlDump`

```c
void xmlSecPtrListDebugXmlDump(xmlSecPtrListPtr list, FILE *output);
```

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

Prints debug info about a list in XML format.

Prints debug information about `list` to the `output` in XML format. 

**Parameters:**

- `list` — the pointer to list.
- `output` — the pointer to output FILE.

---

### `xmlSecStringListGetKlass`

```c
xmlSecPtrListId xmlSecStringListGetKlass(void);
```

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

The strings list class.

**Returns:** strings list klass.

---