- Home
- Download
- News
- Documentation

- FAQ
- Tutorial
- API reference
- Examples

- XML Digital Signature

- Online Verifier

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

# list

## Name

list -- Generic list structure implementation.

## Synopsis

    struct              xmlSecPtrList;
    voidxmlSecPtrListSetDefaultAllocMode    (xmlSecAllocMode defAllocMode,
                                                             xmlSecSize defInitialSize);
    intxmlSecPtrListInitialize             (xmlSecPtrListPtr list,
                                                             xmlSecPtrListId id);
    voidxmlSecPtrListFinalize               (xmlSecPtrListPtr list);
    xmlSecPtrListPtr    xmlSecPtrListCreate                 (xmlSecPtrListId id);
    voidxmlSecPtrListDestroy                (xmlSecPtrListPtr list);
    voidxmlSecPtrListEmpty                  (xmlSecPtrListPtr list);
    intxmlSecPtrListCopy                   (xmlSecPtrListPtr dst,
                                                             xmlSecPtrListPtr src);
    xmlSecPtrListPtrxmlSecPtrListDuplicate              (xmlSecPtrListPtr list);
    xmlSecSize          xmlSecPtrListGetSize                (xmlSecPtrListPtr list);
    xmlSecPtr           xmlSecPtrListGetItem                (xmlSecPtrListPtr list,
                                                             xmlSecSize pos);
    intxmlSecPtrListAdd                    (xmlSecPtrListPtr list,
                                                             xmlSecPtr item);
    intxmlSecPtrListSet                    (xmlSecPtrListPtr list,
                                                             xmlSecPtr item,
                                                             xmlSecSize pos);
    intxmlSecPtrListRemove                 (xmlSecPtrListPtr list,
                                                             xmlSecSize pos);
    xmlSecPtr           xmlSecPtrListRemoveAndReturn        (xmlSecPtrListPtr list,
                                                             xmlSecSize pos);
    voidxmlSecPtrListDebugDump              (xmlSecPtrListPtr list,
                                                             FILE *output);
    voidxmlSecPtrListDebugXmlDump           (xmlSecPtrListPtr list,
                                                             FILE *output);
    #define             xmlSecPtrListGetName                (list)
    #define             xmlSecPtrListIsValid                (list)
    #define             xmlSecPtrListCheckId                (list,
                                                             dataId)
    #define             xmlSecPtrListIdUnknown
    xmlSecPtr           (*xmlSecPtrDuplicateItemMethod)     (xmlSecPtr ptr);
    void                (*xmlSecPtrDestroyItemMethod)       (xmlSecPtr ptr);
    void                (*xmlSecPtrDebugDumpItemMethod)     (xmlSecPtr ptr,
                                                             FILE *output);
    struct              xmlSecPtrListKlass;
    #define             xmlSecPtrListKlassGetName           (klass)
    #define             xmlSecStringListId
    xmlSecPtrListIdxmlSecStringListGetKlass            (void);

## Description

Generic list structure implementation.

## Details

### struct xmlSecPtrList

    struct xmlSecPtrList {
        xmlSecPtrListId             id;

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

The pointers list.

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.

### xmlSecPtrListSetDefaultAllocMode ()

    void                xmlSecPtrListSetDefaultAllocMode    (xmlSecAllocMode defAllocMode,
                                                             xmlSecSize defInitialSize);

Sets new default allocation mode and minimal initial list size.

`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.

`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.

`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.

`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.

`list` : | the pointer to list.

### xmlSecPtrListEmpty ()

    void                xmlSecPtrListEmpty                  (xmlSecPtrListPtr list);

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

`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.

`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.

`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.

`list` : | the pointer to list.
Returns : | the number of itmes in `list`.

### xmlSecPtrListGetItem ()

    xmlSecPtr           xmlSecPtrListGetItem                (xmlSecPtrListPtr list,
                                                             xmlSecSize pos);

Gets item from the list.

`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`.

`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.

`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.

`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.

`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`.

`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.

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

### xmlSecPtrListGetName()

    #define             xmlSecPtrListGetName(list)

Macro. Returns lists's name.

`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.

`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`.

`list` : | the pointer to list.
`dataId` : | the list Id.

### xmlSecPtrListIdUnknown

    #define xmlSecPtrListIdUnknown                  NULL

The "unknown" id.

### xmlSecPtrDuplicateItemMethod ()

    xmlSecPtr           (*xmlSecPtrDuplicateItemMethod)     (xmlSecPtr ptr);

Duplicates item `ptr`.

`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`.

`ptr` : | the poinetr to list item.

### xmlSecPtrDebugDumpItemMethod ()

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

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

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

### struct xmlSecPtrListKlass

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

List klass.

const xmlChar *`name`; | the list klass name.
xmlSecPtrDuplicateItemMethod `duplicateItem`; | the duplciate 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.

### xmlSecPtrListKlassGetName()

    #define             xmlSecPtrListKlassGetName(klass)

Macro. Returns the list klass name.

`klass` : | the list klass. 2

### xmlSecStringListId

    #define             xmlSecStringListId

Strings list klass.

### xmlSecStringListGetKlass ()

    xmlSecPtrListId     xmlSecStringListGetKlass            (void);

The strins list class.

Returns : | strings list klass.