## Future Future — Future Unstable API |

## Synopsis

    void                p11_kit_set_progname                (const char *progname);
    void                p11_kit_be_quiet                    (void);
    void                p11_kit_be_loud                     (void);
    const char *        p11_kit_message                     (void);
    void                (*p11_kit_destroyer)                (void *data);
    typedef             P11KitIter;
    P11KitIter *        p11_kit_iter_new                    (P11KitUri *uri);
    void                p11_kit_iter_set_session_flags      (P11KitIter *iter,
                                                             CK_FLAGS flags);
    void                p11_kit_iter_add_callback           (P11KitIter *iter,
                                                             p11_kit_iter_callback callback,
                                                             void *callback_data,
                                                             p11_kit_destroyer callback_destroy);
    CK_RV               (*p11_kit_iter_callback)            (P11KitIter *iter,
                                                             CK_BBOOL *matches,
                                                             void *data);
    void                p11_kit_iter_add_filter             (P11KitIter *iter,
                                                             CK_ATTRIBUTE *matching,
                                                             CK_ULONG count);
    void                p11_kit_iter_begin                  (P11KitIter *iter,
                                                             CK_FUNCTION_LIST_PTR *modules);
    void                p11_kit_iter_begin_with             (P11KitIter *iter,
                                                             CK_FUNCTION_LIST_PTR module,
                                                             CK_SLOT_ID slot,
                                                             CK_SESSION_HANDLE session);
    CK_RV               p11_kit_iter_next                   (P11KitIter *iter);
    CK_FUNCTION_LIST_PTR p11_kit_iter_get_module            (P11KitIter *iter);
    CK_SLOT_ID          p11_kit_iter_get_slot               (P11KitIter *iter);
    CK_SESSION_HANDLE   p11_kit_iter_get_session            (P11KitIter *iter);
    CK_SESSION_HANDLE   p11_kit_iter_keep_session           (P11KitIter *iter);
    CK_OBJECT_HANDLE    p11_kit_iter_get_object             (P11KitIter *iter);
    CK_RV               p11_kit_iter_load_attributes        (P11KitIter *iter,
                                                             CK_ATTRIBUTE *template,
                                                             CK_ULONG count);
    void                p11_kit_iter_free                   (P11KitIter *iter);

## Description

API that is not yet stable enough to be enabled by default. In all likelyhood this will be included in the next release. To use this API you must define a MACRO. See the p11-kit.h header for more details.

## Details

### p11_kit_set_progname ()

    void                p11_kit_set_progname                (const char *progname);

Set the program base name that is used by the `enable-in` and `disable-in` module configuration options.

Normally this is automatically calculated from the program's argument list. You would usually call this before initializing p11-kit modules.

`progname` : | the program base name

### p11_kit_be_quiet ()

    void                p11_kit_be_quiet                    (void);

Once this function is called, the p11-kit library will no longer print failure or warning messages to stderr.

### p11_kit_be_loud ()

    void                p11_kit_be_loud                     (void);

Tell the p11-kit library will print failure or warning messages to stderr. This is the default behavior, but can be changed using `p11_kit_be_quiet()`.

### p11_kit_message ()

    const char *        p11_kit_message                     (void);

Gets the failure message for a recently called p11-kit function, which returned a failure code on this thread. Not all functions set this message. Each function that does so, will note it in its documentation.

If the most recent p11-kit function did not fail, then this will return NULL. The string is owned by the p11-kit library and is only valid on the same thread that the failed function executed on.

Returns : | The last failure message, or `NULL`.

### p11_kit_destroyer ()

    void                (*p11_kit_destroyer)                (void *data);

A callback called to free a resource.

`data` : | data to destroy

### P11KitIter

    typedef struct p11_kit_iter P11KitIter;

Used to iterate over PKCS#11 objects.

### p11_kit_iter_new ()

    P11KitIter *        p11_kit_iter_new                    (P11KitUri *uri);

Create a new PKCS#11 iterator for iterating over objects. Only objects that match the `uri` will be returned by the iterator. Relevant information in `uri` is copied, and you need not keep `uri` around.

If no `uri` is specified then the iterator will iterate over all objects, unless otherwise filtered.

`uri` : | a PKCS#11 URI to filter on, or `NULL`. [allow-none]
Returns : | a new iterator, which should be freed with `p11_kit_iter_free()`. [transfer full]

### p11_kit_iter_set_session_flags ()

    void                p11_kit_iter_set_session_flags      (P11KitIter *iter,
                                                             CK_FLAGS flags);

Set the PKCS#11 session flags to be used when the iterator opens new sessions.

`iter` : | the iterator
`flags` : | set of session flags

### p11_kit_iter_add_callback ()

    void                p11_kit_iter_add_callback           (P11KitIter *iter,
                                                             p11_kit_iter_callback callback,
                                                             void *callback_data,
                                                             p11_kit_destroyer callback_destroy);

Adds a callback to the iterator which will be called each time that an object is iterated.

These callbacks can also perform filtering. If any callback indicates through it's `matches` argument that the object should not match, then that object will not be iterated as far as `p11_kit_iter_next()` is concerned.

`iter` : | the iterator
`callback` : | a function to call for each iteration
`callback_data` : | data to pass to the function. [allow-none]
`callback_destroy` : | used to cleanup the data. [allow-none]

### p11_kit_iter_callback ()

    CK_RV               (*p11_kit_iter_callback)            (P11KitIter *iter,
                                                             CK_BBOOL *matches,
                                                             void *data);

A callback setup with `p11_kit_iter_add_callback()`. This callback is called for each object iterated.

If the callback sets `matches` to CK_FALSE, then this object is skipped and not matched by `p11_kit_iter_next()`. If you return anything but CKR_OK, then the iteration is stopped, and `p11_kit_iter_next()` returns the result code.

`iter` : | the iterator
`matches` : | whether to match the current object. [out]
`data` : | callback data
Returns : | CKR_OK to continue iterating, CKR_CANCEL to stop, or anything else to fail

### p11_kit_iter_add_filter ()

    void                p11_kit_iter_add_filter             (P11KitIter *iter,
                                                             CK_ATTRIBUTE *matching,
                                                             CK_ULONG count);

Add a filter to limit the objects that the iterator iterates over.

Only objects matching the passed in attributes will be iterated. This function can be called multiple times.

The `matching` attributes are copied.

`iter` : | the iterator
`matching` : | the attributes that the objects should match. [array length=count]
`count` : | the number of attributes

### p11_kit_iter_begin ()

    void                p11_kit_iter_begin                  (P11KitIter *iter,
                                                             CK_FUNCTION_LIST_PTR *modules);

Begin iterating PKCS#11 objects in the given `modules`.

The `modules` arguments should be a null-terminated list of pointers to the modules' PKCS#11 function pointers.

For each module, all initialized slots will be iterated over, having sessions opened for each of them in turn, and searched for objects matching the search criteria.

`iter` : | the iterator
`modules` : | null-terminated list of modules to iterate over. [array zero-terminated=1]

### p11_kit_iter_begin_with ()

    void                p11_kit_iter_begin_with             (P11KitIter *iter,
                                                             CK_FUNCTION_LIST_PTR module,
                                                             CK_SLOT_ID slot,
                                                             CK_SESSION_HANDLE session);

Begin iterating PKCS#11 objects in the given `module`.

If `slot` is non-zero then the iteration will be limited to that slot.

If `session` is non-zero then the iteration will be limited to objects visible through that session, which implies that they are also limited to the slot which the session was opened for.

`iter` : | the iterator
`module` : | the module to iterate over
`slot` : | the slot to iterate objects in, or zero. [allow-none]
`session` : | the session to search for objects on, or zero. [allow-none]

### p11_kit_iter_next ()

    CK_RV               p11_kit_iter_next                   (P11KitIter *iter);

Iterate to the next matching object.

To access the object, session and so on, use the `p11_kit_iter_get_object()`, `p11_kit_iter_get_session()`, and `p11_kit_iter_get_module()` functions.

This call must only be called after either `p11_kit_iter_begin()` or `p11_kit_iter_begin_with()` have been called.

Objects which are skipped by callbacks will not be returned here as matching objects.

`iter` : | the iterator
Returns : | CKR_OK if an object matched, CKR_CANCEL if no more objects, or another error

### p11_kit_iter_get_module ()

    CK_FUNCTION_LIST_PTR p11_kit_iter_get_module            (P11KitIter *iter);

Get the module function pointers for the current matching object.

This can only be called after `p11_kit_iter_next()` succeeds.

`iter` : | the iterator
Returns : | the module which the current matching object is in

### p11_kit_iter_get_slot ()

    CK_SLOT_ID          p11_kit_iter_get_slot               (P11KitIter *iter);

Get the slot which the current matching object is on.

This can only be called after `p11_kit_iter_next()` succeeds.

`iter` : | the iterator
Returns : | the slot of the current matching object

### p11_kit_iter_get_session ()

    CK_SESSION_HANDLE   p11_kit_iter_get_session            (P11KitIter *iter);

Get the session which the current matching object is acessible through.

This can only be called after `p11_kit_iter_next()` succeeds.

The session may be closed after the next `p11_kit_iter_next()` call unless `p11_kit_iter_keep_session()` is called.

`iter` : | the iterator
Returns : | the slot of the current matching object

### p11_kit_iter_keep_session ()

    CK_SESSION_HANDLE   p11_kit_iter_keep_session           (P11KitIter *iter);

After calling this function the session open for iterating the current object will not be automatically closed by the iterator after later calls to `p11_kit_iter_next()` or `p11_kit_iter_free()`.

It is the callers responsibility to close this session, after the iterator has been freed. The session may still be used by the iterator if further iterations are performed.

This can only be called after `p11_kit_iter_next()` succeeds.

`iter` : | the iterator
Returns : | the current session

### p11_kit_iter_get_object ()

    CK_OBJECT_HANDLE    p11_kit_iter_get_object             (P11KitIter *iter);

Get the current matching object.

This can only be called after `p11_kit_iter_next()` succeeds.

`iter` : | the iterator
Returns : | the current matching object

### p11_kit_iter_load_attributes ()

    CK_RV               p11_kit_iter_load_attributes        (P11KitIter *iter,
                                                             CK_ATTRIBUTE *template,
                                                             CK_ULONG count);

Retrieve attributes for the current matching object.

Each attribute in the array will be filled in with the value of that attribute retrieved from the object. After use the attribute value memory pointed to by the `pValue` of each attribute should be freed with the `free()` function.

If the `pValue` of an attribute is not `NULL` passed to this function, then it will be passed to `realloc()` to allocate the correct amount of space for the attribute value.

If any attribute is not present on the object, or is sensitive and cannot be retrieved, then the `pValue` will be NULL. If `pValue` was not `NULL` when passed to this function then it will be freed with `free()`. In these cases `CKR_OK` is returned.

This can only be called after `p11_kit_iter_next()` succeeds.

`iter` : | the iterator
`template` : | the attributes to load. [array length=count][inout]
`count` : | the number of attributes
Returns : | CKR_OK or a failure code

### p11_kit_iter_free ()

    void                p11_kit_iter_free                   (P11KitIter *iter);

Frees the iterator and all resources, such as sessions or callbacks held by the iterator.

`iter` : | the iterator