list: XML Security Library Reference Manual

## list list — Generic list structure functions. |

## Stability Level

Stable, unless otherwise indicated

## Functions

void | xmlSecPtrListSetDefaultAllocMode ()
int | xmlSecPtrListInitialize ()
void | xmlSecPtrListFinalize ()
xmlSecPtrListPtr | xmlSecPtrListCreate ()
void | xmlSecPtrListDestroy ()
void | xmlSecPtrListEmpty ()
int | xmlSecPtrListCopy ()
xmlSecPtrListPtr | xmlSecPtrListDuplicate ()
xmlSecSize | xmlSecPtrListGetSize ()
xmlSecPtr | xmlSecPtrListGetItem ()
int | xmlSecPtrListAdd ()
int | xmlSecPtrListSet ()
int | xmlSecPtrListRemove ()
xmlSecPtr | xmlSecPtrListRemoveAndReturn ()
void | xmlSecPtrListDebugDump ()
void | xmlSecPtrListDebugXmlDump ()
#define | xmlSecPtrListGetName()
#define | xmlSecPtrListIsValid()
#define | xmlSecPtrListCheckId()
xmlSecPtr | (*xmlSecPtrDuplicateItemMethod) ()
void | (*xmlSecPtrDestroyItemMethod) ()
void | (*xmlSecPtrDebugDumpItemMethod) ()
#define | xmlSecPtrListKlassGetName()
xmlSecPtrListId | xmlSecStringListGetKlass ()

## Types and Values

struct | xmlSecPtrList
#define | xmlSecPtrListIdUnknown
struct | xmlSecPtrListKlass
#define | xmlSecStringListId

## Description

## Functions

### xmlSecPtrListSetDefaultAllocMode ()

    void
    xmlSecPtrListSetDefaultAllocMode (xmlSecAllocMode defAllocMode,
                                      xmlSecSize defInitialSize);

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 ()

    int
    xmlSecPtrListInitialize (xmlSecPtrListPtr list,
                             xmlSecPtrListId id);

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 ()

    void
    xmlSecPtrListFinalize (xmlSecPtrListPtr list);

Cleans up the list initialized with xmlSecPtrListInitialize function.

#### Parameters

list | the pointer to list. |

### xmlSecPtrListCreate ()

    xmlSecPtrListPtr
    xmlSecPtrListCreate (xmlSecPtrListId id);

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 ()

    void
    xmlSecPtrListDestroy (xmlSecPtrListPtr list);

Destroys `list` created with xmlSecPtrListCreate function.

#### Parameters

list | the pointer to list. |

### xmlSecPtrListEmpty ()

    void
    xmlSecPtrListEmpty (xmlSecPtrListPtr list);

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

#### Parameters

list | the pointer to list. |

### xmlSecPtrListCopy ()

    int
    xmlSecPtrListCopy (xmlSecPtrListPtr dst,
                       xmlSecPtrListPtr src);

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 ()

    xmlSecPtrListPtr
    xmlSecPtrListDuplicate (xmlSecPtrListPtr list);

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 ()

    xmlSecSize
    xmlSecPtrListGetSize (xmlSecPtrListPtr list);

Gets list size.

#### Parameters

list | the pointer to list. |

#### Returns

the number of items in `list` .

### xmlSecPtrListGetItem ()

    xmlSecPtr
    xmlSecPtrListGetItem (xmlSecPtrListPtr list,
                          xmlSecSize pos);

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 ()

    int
    xmlSecPtrListAdd (xmlSecPtrListPtr list,
                      xmlSecPtr item);

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.

### xmlSecPtrListSet ()

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

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 ()

    int
    xmlSecPtrListRemove (xmlSecPtrListPtr list,
                         xmlSecSize pos);

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 ()

    xmlSecPtr
    xmlSecPtrListRemoveAndReturn (xmlSecPtrListPtr list,
                                  xmlSecSize pos);

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 ()

    void
    xmlSecPtrListDebugDump (xmlSecPtrListPtr list,
                            FILE *output);

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

#### Parameters

list | the pointer to list. |
output | the pointer to output FILE. |

### xmlSecPtrListDebugXmlDump ()

    void
    xmlSecPtrListDebugXmlDump (xmlSecPtrListPtr list,
                               FILE *output);

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

#### Parameters

list | the pointer to list. |
output | the pointer to output FILE. |

### xmlSecPtrListGetName()

    #define             xmlSecPtrListGetName(list)

Macro. Returns lists's name.

#### Parameters

list | the ponter to list. |

### xmlSecPtrListIsValid()

    #define             xmlSecPtrListIsValid(list)

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

#### Parameters

list | the pointer to list. |

### xmlSecPtrListCheckId()

    #define             xmlSecPtrListCheckId(list, 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. |

### xmlSecPtrDuplicateItemMethod ()

    xmlSecPtr
    (*xmlSecPtrDuplicateItemMethod) (xmlSecPtr ptr);

Duplicates item `ptr` .

#### Parameters

ptr | the poinetr to list item. |

#### Returns

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

### xmlSecPtrDestroyItemMethod ()

    void
    (*xmlSecPtrDestroyItemMethod) (xmlSecPtr ptr);

Destroys list item `ptr` .

#### Parameters

ptr | the poinetr to list item. |

### xmlSecPtrDebugDumpItemMethod ()

    void
    (*xmlSecPtrDebugDumpItemMethod) (xmlSecPtr ptr,
                                     FILE *output);

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

#### Parameters

ptr | the poinetr to list item. |
output | the output FILE. |

### xmlSecPtrListKlassGetName()

    #define             xmlSecPtrListKlassGetName(klass)

Macro. Returns the list klass name.

#### Parameters

klass | the list klass. 2 |

### xmlSecStringListGetKlass ()

    xmlSecPtrListId
    xmlSecStringListGetKlass (void);

The strings list class.

#### Returns

strings list klass.

## Types and Values

### struct xmlSecPtrList

    struct xmlSecPtrList {
        xmlSecPtrListId             id;

        xmlSecPtr*                  data;
        xmlSecSize                  use;
        xmlSecSize                  max;
        xmlSecAllocMode             allocMode;
    };

The pointers list.

#### Members

xmlSecPtrListId `id`; | the list items description. |
xmlSecPtr *`data`; | the list data. |
xmlSecSize `use`; | the current list size. |
xmlSecSize `max`; | the max (allocated) list size. |
xmlSecAllocMode `allocMode`; | the memory allocation mode. |

### xmlSecPtrListIdUnknown

    #define xmlSecPtrListIdUnknown                  NULL

The "unknown" id.

### struct xmlSecPtrListKlass

    struct xmlSecPtrListKlass {
        const xmlChar*                      name;
        xmlSecPtrDuplicateItemMethod        duplicateItem;
        xmlSecPtrDestroyItemMethod          destroyItem;
        xmlSecPtrDebugDumpItemMethod        debugDumpItem;
        xmlSecPtrDebugDumpItemMethod        debugXmlDumpItem;
    };

List klass.

#### Members

const xmlChar *`name`; | the list klass name. |
xmlSecPtrDuplicateItemMethod `duplicateItem`; | the duplicate item method. |
xmlSecPtrDestroyItemMethod `destroyItem`; | the destroy item method. |
xmlSecPtrDebugDumpItemMethod `debugDumpItem`; | the debug dump item method. |
xmlSecPtrDebugDumpItemMethod `debugXmlDumpItem`; | the debug dump item in xml format method. |

### xmlSecStringListId

    #define             xmlSecStringListId

Strings list klass.