GckEnumerator: Gck Library Reference Manual

## GckEnumerator GckEnumerator — Enumerates through PKCS#11 objects. |

## Functions

GckObject * | gck_enumerator_next ()
void | gck_enumerator_next_async ()
GList * | gck_enumerator_next_finish ()
GList * | gck_enumerator_next_n ()
GTlsInteraction * | gck_enumerator_get_interaction ()
void | gck_enumerator_set_interaction ()
GType | gck_enumerator_get_object_type ()
void | gck_enumerator_set_object_type ()
void | gck_enumerator_set_object_type_full ()
GckEnumerator * | gck_enumerator_get_chained ()
void | gck_enumerator_set_chained ()

## Properties

GckEnumerator * | chained | Read / Write
GTlsInteraction * | interaction | Read / Write
GType * | object-type | Read / Write

## Types and Values

struct | GckEnumerator

## Object Hierarchy

        GObject
        ╰── GckEnumerator

## Description

A GckEnumerator can be used to enumerate through PKCS#11 objects. It will automatically create sessions as necessary.

Use `gck_modules_enumerate_objects()` or `gck_modules_enumerate_uri()` to create an enumerator. To get the objects use `gck_enumerator_next()` or `gck_enumerator_next_async()` functions.

## Functions

### gck_enumerator_next ()

    GckObject *
    gck_enumerator_next (GckEnumerator *self,
                         GCancellable *cancellable,
                         GError **error);

Get the next object in the enumerator, or `NULL` if there are no more objects.

`NULL` is also returned if the function fails. Use the `error` to determine whether a failure occurred or not.

#### Parameters

self | The enumerator |
cancellable | A GCancellable or `NULL` |
error | A location to store an error on failure |

#### Returns

The next object, which must be released using g_object_unref, or `NULL`.

[transfer full][allow-none]

### gck_enumerator_next_async ()

    void
    gck_enumerator_next_async (GckEnumerator *self,
                               gint max_objects,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Get the next set of objects from the enumerator. This operation completes asynchronously.The maximum number of objects can be specified with `max_objects` . If -1 is specified, then all the remaining objects will be enumerated.

#### Parameters

self | An enumerator |
max_objects | The maximum number of objects to get |
cancellable | A GCancellable or `NULL` |
callback | Called when the result is ready |
user_data | Data to pass to the callback |

### gck_enumerator_next_finish ()

    GList *
    gck_enumerator_next_finish (GckEnumerator *self,
                                GAsyncResult *result,
                                GError **error);

Complete an operation to enumerate next objects.

`NULL` is also returned if the function fails. Use the `error` to determine whether a failure occurred or not.

#### Parameters

self | An enumerator |
result | The result passed to the callback |
error | A location to raise an error on failure. |

#### Returns

The list of objects, which should be freed with `gck_list_unref_free()`.

[element-type Gck.Object][transfer full]

### gck_enumerator_next_n ()

    GList *
    gck_enumerator_next_n (GckEnumerator *self,
                           gint max_objects,
                           GCancellable *cancellable,
                           GError **error);

Get the next set of objects from the enumerator. The maximum number of objects can be specified with `max_objects` . If -1 is specified, then all the remaining objects will be returned.

`NULL` is also returned if the function fails. Use the `error` to determine whether a failure occurred or not.

#### Parameters

self | An enumerator |
max_objects | The maximum amount of objects to enumerate |
cancellable | A GCancellable or `NULL` |
error | A location to store an error on failure |

#### Returns

A list of objects, which should be freed using `gck_list_unref_free()`.

[transfer full][element-type Gck.Object]

### gck_enumerator_get_interaction ()

    GTlsInteraction *
    gck_enumerator_get_interaction (GckEnumerator *self);

Get the interaction used when a pin is needed

#### Parameters

self | the enumerator |

#### Returns

the interaction or `NULL`.

[transfer full][allow-none]

### gck_enumerator_set_interaction ()

    void
    gck_enumerator_set_interaction (GckEnumerator *self,
                                    GTlsInteraction *interaction);

Set the interaction used when a pin is needed

#### Parameters

self | the enumerator |
interaction | the interaction or `NULL`. | [allow-none]

### gck_enumerator_get_object_type ()

    GType
    gck_enumerator_get_object_type (GckEnumerator *self);

Get the type of objects created by this enumerator. The type will always either be GckObject or derived from it.

#### Parameters

self | an enumerator |

#### Returns

the type of objects created

### gck_enumerator_set_object_type ()

    void
    gck_enumerator_set_object_type (GckEnumerator *self,
                                    GType object_type);

Set the type of objects to be created by this enumerator. The type must always be either GckObject or derived from it.

If the GckObjectCache interface is implemented on the derived class and the default_types class field is set, then the enumerator will retrieve attributes for each object.

[skip]

#### Parameters

self | an enumerator |
object_type | the type of objects to create |

### gck_enumerator_set_object_type_full ()

    void
    gck_enumerator_set_object_type_full (GckEnumerator *self,
                                         GType object_type,
                                         const gulong *attr_types,
                                         gint attr_count);

Set the type of objects to be created by this enumerator. The type must always be either GckObject or derived from it.

If `attr_types` and `attr_count` are non-NULL and non-zero respectively, then the GckObjectCache interface is expected to be implemented on the derived class, then the enumerator will retrieve attributes for each object.

[rename-to gck_enumerator_set_object_type]

#### Parameters

self | an enumerator |
object_type | the type of objects to create |
attr_types | types of attributes to retrieve for objects. | [array length=attr_count]
attr_count | the number of attributes to retrieve |

### gck_enumerator_get_chained ()

    GckEnumerator *
    gck_enumerator_get_chained (GckEnumerator *self);

Get the enumerator that will be run after all objects from this one are seen.

#### Parameters

self | the enumerator |

#### Returns

the chained enumerator or `NULL`.

[transfer full][allow-none]

### gck_enumerator_set_chained ()

    void
    gck_enumerator_set_chained (GckEnumerator *self,
                                GckEnumerator *chained);

Set a chained enumerator that will be run after all objects from this one are seen.

#### Parameters

self | the enumerator |
chained | the chained enumerator or `NULL`. | [allow-none]

## Types and Values

### struct GckEnumerator

    struct GckEnumerator;

An object that allows enumerating of objects across modules, tokens.

## Property Details

### The `“chained”` property

      “chained”                  GckEnumerator *

Chained enumerator, which will be enumerated when this enumerator has enumerated all its objects.

Flags: Read / Write

### The `“interaction”` property

      “interaction”              GTlsInteraction *

Interaction object used to ask the user for pins when opening sessions. Used if the session_options of the enumerator have `GCK_SESSION_LOGIN_USER`

Flags: Read / Write

### The `“object-type”` property

      “object-type”              GType *

The type of objects that are created by the enumerator. Must be GckObject or derived from it.

[skip]

Flags: Read / Write

Allowed values: GckObject