GckSlot

## GckSlot GckSlot — Represents a PKCS#11 slot that can contain a token. |

## Synopsis

                        GckMechanismInfo;
    void                gck_mechanism_info_free             (GckMechanismInfo *mech_info);
    typedef             GckMechanisms;
    #define             gck_mechanisms_length               (a)
    #define             gck_mechanisms_at                   (a,
                                                             i)
    #define             gck_mechanisms_free                 (a)
    gboolean            gck_mechanisms_check                (GckMechanisms *mechanisms,
                                                             ...);
    struct              GckSlot;
    gboolean            gck_slot_equal                      (gconstpointer slot1,
                                                             gconstpointer slot2);
    guint               gck_slot_hash                       (gconstpointer slot);
    GckModule *         gck_slot_get_module                 (GckSlot *self);
    CK_SLOT_ID          gck_slot_get_handle                 (GckSlot *self);
    GckSlotInfo *       gck_slot_get_info                   (GckSlot *self);
    GckTokenInfo *      gck_slot_get_token_info             (GckSlot *self);
    GckMechanisms *     gck_slot_get_mechanisms             (GckSlot *self);
    GckMechanismInfo *  gck_slot_get_mechanism_info         (GckSlot *self,
                                                             gulong mech_type);
    gboolean            gck_slot_has_flags                  (GckSlot *self,
                                                             gulong flags);
    GckEnumerator *     gck_slots_enumerate_objects         (GList *slots,
                                                             GckAttributes *attrs,
                                                             guint session_options);
    GckSession *        gck_slot_open_session               (GckSlot *self,
                                                             guint options,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GckSession *        gck_slot_open_session_full          (GckSlot *self,
                                                             guint options,
                                                             gulong pkcs11_flags,
                                                             gpointer app_data,
                                                             CK_NOTIFY notify,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gck_slot_open_session_full_async    (GckSlot *self,
                                                             guint options,
                                                             gulong pkcs11_flags,
                                                             gpointer app_data,
                                                             CK_NOTIFY notify,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    void                gck_slot_open_session_async         (GckSlot *self,
                                                             guint options,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GckSession *        gck_slot_open_session_finish        (GckSlot *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    GckSlot *           gck_slot_from_handle                (GckModule *module,
                                                             CK_SLOT_ID slot_id);
                        GckSlotInfo;
    void                gck_slot_info_free                  (GckSlotInfo *slot_info);
                        GckTokenInfo;
    void                gck_token_info_free                 (GckTokenInfo *token_info);

## Description

A PKCS11 slot can contain a token. As an example, a slot might be a card reader, and the token the card. If the PKCS#11 module is not a hardware driver, often the slot and token are equivalent.

## Details

### GckMechanismInfo

    typedef struct {
    	gulong min_key_size;
    	gulong max_key_size;
    	gulong flags;
    } GckMechanismInfo;

Represents information about a PKCS11 mechanism.

This is analogous to a CK_MECHANISM_INFO structure.

When you're done with this structure it should be released with `gck_mechanism_info_free()`.

gulong `min_key_size`; | The minimum key size that can be used with this mechanism.
gulong `max_key_size`; | The maximum key size that can be used with this mechanism.
gulong `flags`; | Various PKCS11 flags that apply to this mechanism.

### gck_mechanism_info_free ()

    void                gck_mechanism_info_free             (GckMechanismInfo *mech_info);

Free the GckMechanismInfo and associated resources.

`mech_info` : | The mechanism info to free, or NULL.

### GckMechanisms

    typedef GArray GckMechanisms;

A set of GckMechanismInfo structures.

### gck_mechanisms_length()

    #define             gck_mechanisms_length(a)                ((a)->len)

Get the number of GckMechanismInfo in the set.

`a` : | A GckMechanisms set.
Returns : | The number in the set.

### gck_mechanisms_at()

    #define             gck_mechanisms_at(a, i)                 (g_array_index(a, CK_MECHANISM_TYPE, i))

Get a specific GckMechanismInfo in a the set.

`a` : | A GckMechanisms set.
`i` : | The index of a GckMechanismInfo.
Returns : | The GckMechanismInfo.

### gck_mechanisms_free()

    #define             gck_mechanisms_free(a)                  (g_array_free(a, TRUE))

Free a GckMechanisms set.

`a` : | A GckMechanism set.

### gck_mechanisms_check ()

    gboolean            gck_mechanisms_check                (GckMechanisms *mechanisms,
                                                             ...);

Check whether all the mechanism types are in the list.

The arguments should be a list of CKM_XXX mechanism types. The last argument should be GCK_INVALID.

`mechanisms` : | A list of mechanisms, perhaps retrieved from `gck_slot_get_mechanisms()`.
`...` : | A list of mechanism types followed by GCK_INVALID.
Returns : | Whether the mechanism is in the list or not.

### struct GckSlot

    struct GckSlot {
    	GObject parent;
    };

Represents a PKCS11 slot.

GObject `parent`; | derived from this.

### gck_slot_equal ()

    gboolean            gck_slot_equal                      (gconstpointer slot1,
                                                             gconstpointer slot2);

Checks equality of two slots. Two GckSlot objects can point to the same underlying PKCS#11 slot.

`slot1` : | A pointer to the first GckSlot
`slot2` : | A pointer to the second GckSlot
Returns : | TRUE if slot1 and slot2 are equal. FALSE if either is not a GckSlot.

### gck_slot_hash ()

    guint               gck_slot_hash                       (gconstpointer slot);

Create a hash value for the GckSlot.

This function is intended for easily hashing a GckSlot to add to a GHashTable or similar data structure.

`slot` : | A pointer to a GckSlot
Returns : | An integer that can be used as a hash value, or 0 if invalid.

### gck_slot_get_module ()

    GckModule *         gck_slot_get_module                 (GckSlot *self);

Get the module that this slot is on.

`self` : | The slot to get the module for.
Returns : | The module, you must unreference this after you're done with it.

### gck_slot_get_handle ()

    CK_SLOT_ID          gck_slot_get_handle                 (GckSlot *self);

Get the raw PKCS#11 handle of a slot.

`self` : | The slot to get the handle of.
Returns : | The raw handle.

### gck_slot_get_info ()

    GckSlotInfo *       gck_slot_get_info                   (GckSlot *self);

Get the information for this slot.

`self` : | The slot to get info for.
Returns : | The slot information. When done, use `gck_slot_info_free()` to release it.

### gck_slot_get_token_info ()

    GckTokenInfo *      gck_slot_get_token_info             (GckSlot *self);

Get the token information for this slot.

`self` : | The slot to get info for.
Returns : | The token information. When done, use `gck_token_info_free()` to release it.

### gck_slot_get_mechanisms ()

    GckMechanisms *     gck_slot_get_mechanisms             (GckSlot *self);

Get the available mechanisms for this slot.

`self` : | The slot to get mechanisms for.
Returns : | A list of the mechanisms for this slot. Use `gck_mechanisms_free()` when done with this.

### gck_slot_get_mechanism_info ()

    GckMechanismInfo *  gck_slot_get_mechanism_info         (GckSlot *self,
                                                             gulong mech_type);

Get information for the specified mechanism.

`self` : | The slot to get mechanism info from.
`mech_type` : | The mechanisms type to get info for.
Returns : | The mechanism information, or NULL if failed. Use `gck_mechanism_info_free()` when done with it.

### gck_slot_has_flags ()

    gboolean            gck_slot_has_flags                  (GckSlot *self,
                                                             gulong flags);

Check if the PKCS11 slot has the given flags.

`self` : | The GckSlot object.
`flags` : | The flags to check.
Returns : | Whether one or more flags exist.

### gck_slots_enumerate_objects ()

    GckEnumerator *     gck_slots_enumerate_objects         (GList *slots,
                                                             GckAttributes *attrs,
                                                             guint session_options);

Setup an enumerator for listing matching objects on the slots.

This call will not block but will return an enumerator immediately.

`slots` : | a list of GckSlot to enumerate objects on.
`attrs` : | Attributes that the objects must have, or empty for all objects.
`session_options` : | Options for opening a session.
Returns : | a new enumerator

### gck_slot_open_session ()

    GckSession *        gck_slot_open_session               (GckSlot *self,
                                                             guint options,
                                                             GCancellable *cancellable,
                                                             GError **error);

Open a session on the slot. If the 'auto reuse' setting is set, then this may be a recycled session with the same flags.

This call may block for an indefinite period.

`self` : | The slot ot open a session on.
`options` : | The GckSessionOptions to open a session with.
`cancellable` : | An optional cancellation object, or `NULL`.
`error` : | A location to return an error, or `NULL`.
Returns : | A new session or NULL if an error occurs.

### gck_slot_open_session_full ()

    GckSession *        gck_slot_open_session_full          (GckSlot *self,
                                                             guint options,
                                                             gulong pkcs11_flags,
                                                             gpointer app_data,
                                                             CK_NOTIFY notify,
                                                             GCancellable *cancellable,
                                                             GError **error);

Open a session on the slot. If the 'auto reuse' setting is set, then this may be a recycled session with the same flags.

This call may block for an indefinite period.

`self` : | The slot to open a session on.
`options` : | The options to open the new session with.
`pkcs11_flags` : | Additional raw PKCS#11 flags.
`app_data` : | Application data for notification callback.
`notify` : | PKCS#11 notification callback.
`cancellable` : | Optional cancellation object, or NULL.
`error` : | A location to return an error, or NULL.
Returns : | A new session or NULL if an error occurs.

### gck_slot_open_session_full_async ()

    void                gck_slot_open_session_full_async    (GckSlot *self,
                                                             guint options,
                                                             gulong pkcs11_flags,
                                                             gpointer app_data,
                                                             CK_NOTIFY notify,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Open a session on the slot. If the 'auto reuse' setting is set, then this may be a recycled session with the same flags.

This call will return immediately and complete asynchronously.

`self` : | The slot to open a session on.
`options` : | Options to open the new session with.
`pkcs11_flags` : | Additional raw PKCS#11 flags.
`app_data` : | Application data for notification callback.
`notify` : | PKCS#11 notification callback.
`cancellable` : | Optional cancellation object, or NULL.
`callback` : | Called when the operation completes.
`user_data` : | Data to pass to the callback.

### gck_slot_open_session_async ()

    void                gck_slot_open_session_async         (GckSlot *self,
                                                             guint options,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Open a session on the slot. If the 'auto reuse' setting is set, then this may be a recycled session with the same flags.

This call will return immediately and complete asynchronously.

`self` : | The slot to open a session on.
`options` : | The options to open the new session with.
`cancellable` : | Optional cancellation object, or NULL.
`callback` : | Called when the operation completes.
`user_data` : | Data to pass to the callback.

### gck_slot_open_session_finish ()

    GckSession *        gck_slot_open_session_finish        (GckSlot *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Get the result of an open session operation. If the 'auto reuse' setting is set, then this may be a recycled session with the same flags.

`self` : | The slot to open a session on.
`result` : | The result passed to the callback.
`error` : | A location to return an error or NULL.
Returns : | The new session or NULL if an error occurs.

### gck_slot_from_handle ()

    GckSlot *           gck_slot_from_handle                (GckModule *module,
                                                             CK_SLOT_ID slot_id);

Create a new GckSlot object for a raw PKCS#11 handle.

`module` : | The module that this slot is on.
`slot_id` : | The raw PKCS#11 handle or slot id of this slot.
Returns : | The new GckSlot object.

### GckSlotInfo

    typedef struct {
    	gchar *slot_description;
    	gchar *manufacturer_id;
    	gulong flags;
    	guint8 hardware_version_major;
    	guint8 hardware_version_minor;
    	guint8 firmware_version_major;
    	guint8 firmware_version_minor;
    } GckSlotInfo;

Represents information about a PKCS11 slot.

This is analogous to a CK_SLOT_INFO structure, but the strings are far more usable.

When you're done with this structure it should be released with `gck_slot_info_free()`.

gchar *`slot_description`; | Description of the slot.
gchar *`manufacturer_id`; | The manufacturer of this slot.
gulong `flags`; | Various PKCS11 flags that apply to this slot.
guint8 `hardware_version_major`; | The major version of the hardware.
guint8 `hardware_version_minor`; | The minor version of the hardware.
guint8 `firmware_version_major`; | The major version of the firmware.
guint8 `firmware_version_minor`; | The minor version of the firmware.

### gck_slot_info_free ()

    void                gck_slot_info_free                  (GckSlotInfo *slot_info);

Free the GckSlotInfo and associated resources.

`slot_info` : | The slot info to free, or NULL.

### GckTokenInfo

    typedef struct {
    	gchar *label;
    	gchar *manufacturer_id;
    	gchar *model;
    	gchar *serial_number;
    	gulong flags;
    	glong max_session_count;
    	glong session_count;
    	glong max_rw_session_count;
    	glong rw_session_count;
    	glong max_pin_len;
    	glong min_pin_len;
    	glong total_public_memory;
    	glong free_public_memory;
    	glong total_private_memory;
    	glong free_private_memory;
    	guint8 hardware_version_major;
    	guint8 hardware_version_minor;
    	guint8 firmware_version_major;
    	guint8 firmware_version_minor;
    	gint64 utc_time;
    } GckTokenInfo;

Represents information about a PKCS11 token.

This is analogous to a CK_TOKEN_INFO structure, but the strings are far more usable.

When you're done with this structure it should be released with `gck_token_info_free()`.

gchar *`label`; | The displayable token label.
gchar *`manufacturer_id`; | The manufacturer of this slot.
gchar *`model`; | The token model number as a string.
gchar *`serial_number`; | The token serial number as a string.
gulong `flags`; | Various PKCS11 flags that apply to this token.
glong `max_session_count`; | The maximum number of sessions allowed on this token.
glong `session_count`; | The number of sessions open on this token.
glong `max_rw_session_count`; | The maximum number of read/write sessions allowed on this token.
glong `rw_session_count`; | The number of sessions open on this token.
glong `max_pin_len`; | The maximum length of a PIN for locking this token.
glong `min_pin_len`; | The minimum length of a PIN for locking this token.
glong `total_public_memory`; | The total amount of memory on this token for storing public objects.
glong `free_public_memory`; | The available amount of memory on this token for storing public objects.
glong `total_private_memory`; | The total amount of memory on this token for storing private objects.
glong `free_private_memory`; | The available amount of memory on this token for storing private objects.
guint8 `hardware_version_major`; | The major version of the hardware.
guint8 `hardware_version_minor`; | The minor version of the hardware.
guint8 `firmware_version_major`; | The major version of the firmware.
guint8 `firmware_version_minor`; | The minor version of the firmware.
gint64 `utc_time`; | If the token has a hardware clock, this is set to the number of seconds since the epoch.

### gck_token_info_free ()

    void                gck_token_info_free                 (GckTokenInfo *token_info);

Free the GckTokenInfo and associated resources.

`token_info` : | The token info to free, or NULL.