## GckObject

GckObject — Represents a PKCS11 object such as a key or certificate.

## Synopsis

    struct              GckObject;
    GckObject *         gck_object_from_handle              (GckSession *session,
                                                             CK_OBJECT_HANDLE handle);
    GList *             gck_objects_from_handle_array       (GckSession *session,
                                                             CK_OBJECT_HANDLE_PTR handles,
                                                             CK_ULONG n_handles);
    gboolean            gck_object_equal                    (gconstpointer object1,
                                                             gconstpointer object2);
    guint               gck_object_hash                     (gconstpointer object);
    GckModule *         gck_object_get_module               (GckObject *self);
    CK_OBJECT_HANDLE    gck_object_get_handle               (GckObject *self);
    GckSession *        gck_object_get_session              (GckObject *self);
    gboolean            gck_object_destroy                  (GckObject *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gck_object_destroy_async            (GckObject *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gck_object_destroy_finish           (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            gck_object_set                      (GckObject *self,
                                                             GckAttributes *attrs,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gck_object_set_async                (GckObject *self,
                                                             GckAttributes *attrs,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gck_object_set_finish               (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    GckAttributes *     gck_object_get                      (GckObject *self,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);
    void                gck_object_get_async                (GckObject *self,
                                                             gulong *attr_types,
                                                             guint n_attr_types,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GckAttributes *     gck_object_get_finish               (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gpointer            gck_object_get_data                 (GckObject *self,
                                                             gulong attr_type,
                                                             GCancellable *cancellable,
                                                             gsize *n_data,
                                                             GError **error);
    gpointer            gck_object_get_data_full            (GckObject *self,
                                                             gulong attr_type,
                                                             GckAllocator allocator,
                                                             GCancellable *cancellable,
                                                             gsize *n_data,
                                                             GError **error);
    void                gck_object_get_data_async           (GckObject *self,
                                                             gulong attr_type,
                                                             GckAllocator allocator,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gpointer            gck_object_get_data_finish          (GckObject *self,
                                                             GAsyncResult *result,
                                                             gsize *n_data,
                                                             GError **error);
    GckAttributes *     gck_object_get_full                 (GckObject *self,
                                                             gulong *attr_types,
                                                             guint n_attr_types,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GckAttributes *     gck_object_get_template             (GckObject *self,
                                                             gulong attr_type,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gck_object_get_template_async       (GckObject *self,
                                                             gulong attr_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GckAttributes *     gck_object_get_template_finish      (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            gck_object_set_template             (GckObject *self,
                                                             gulong attr_type,
                                                             GckAttributes *attrs,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gck_object_set_template_async       (GckObject *self,
                                                             gulong attr_type,
                                                             GckAttributes *attrs,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gck_object_set_template_finish      (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);

## Description

A GckObject holds a handle to a PKCS11 object such as a key or certificate. Token objects are stored on the token persistently. Others are transient and are called session objects.

## Details

### struct GckObject

    struct GckObject {
    	GObject parent;
    };

Represents a PKCS11 object handle such as a key or certifiacte.

GObject `parent`; | derived from this.

### gck_object_from_handle ()

    GckObject *         gck_object_from_handle              (GckSession *session,
                                                             CK_OBJECT_HANDLE handle);

Initialize a GckObject from a raw PKCS#11 handle. Normally you would use `gck_session_create_object()` or `gck_session_find_objects()` to access objects.

`session` : | The session through which this object is accessed or created.
`handle` : | The raw handle of the object.
Returns : | The new GckObject. You should use `g_object_unref()` when done with this object.

### gck_objects_from_handle_array ()

    GList *             gck_objects_from_handle_array       (GckSession *session,
                                                             CK_OBJECT_HANDLE_PTR handles,
                                                             CK_ULONG n_handles);

Initialize a list of GckObject from raw PKCS#11 handles. The handles argument must contain contiguous CK_OBJECT_HANDLE handles in an array.

`session` : | The session for these objects
`handles` : | The raw object handles.
`n_handles` : | The number of raw object handles.
Returns : | The list of GckObject. You should use `gck_list_unref_free()` when done with this list.

### gck_object_equal ()

    gboolean            gck_object_equal                    (gconstpointer object1,
                                                             gconstpointer object2);

Checks equality of two objects. Two GckObject objects can point to the same underlying PKCS#11 object.

`object1` : | A pointer to the first GckObject
`object2` : | A pointer to the second GckObject
Returns : | TRUE if object1 and object2 are equal. FALSE if either is not a GckObject.

### gck_object_hash ()

    guint               gck_object_hash                     (gconstpointer object);

Create a hash value for the GckObject.

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

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

### gck_object_get_module ()

    GckModule *         gck_object_get_module               (GckObject *self);

Get the PKCS#11 module to which this object belongs.

`self` : | The object.
Returns : | The module, which should be unreffed after use.

### gck_object_get_handle ()

    CK_OBJECT_HANDLE    gck_object_get_handle               (GckObject *self);

Get the raw PKCS#11 handle of a GckObject.

`self` : | The object.
Returns : | The raw object handle.

### gck_object_get_session ()

    GckSession *        gck_object_get_session              (GckObject *self);

Get the PKCS#11 session assigned to make calls on when operating on this object.

This will only return a session if it was set explitly on this object. By default an object will open and close sessions appropriate for its calls.

`self` : | The object
Returns : | The assigned session, which must be unreffed after use.

### gck_object_destroy ()

    gboolean            gck_object_destroy                  (GckObject *self,
                                                             GCancellable *cancellable,
                                                             GError **error);

Destroy a PKCS#11 object, deleting it from storage or the session. This call may block for an indefinite period.

`self` : | The object to destroy.
`cancellable` : | Optional cancellable object, or NULL to ignore.
`error` : | A location to return an error.
Returns : | Whether the call was successful or not.

### gck_object_destroy_async ()

    void                gck_object_destroy_async            (GckObject *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Destroy a PKCS#11 object, deleting it from storage or the session. This call will return immediately and complete asynchronously.

`self` : | The object to destroy.
`cancellable` : | Optional cancellable object, or NULL to ignore.
`callback` : | Callback which is called when operation completes.
`user_data` : | Data to pass to the callback.

### gck_object_destroy_finish ()

    gboolean            gck_object_destroy_finish           (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Get the status of the operation to destroy a PKCS#11 object, begun with `gck_object_destroy_async()`.

`self` : | The object being destroyed.
`result` : | The result of the destory operation passed to the callback.
`error` : | A location to store an error.
Returns : | Whether the object was destroyed successfully or not.

### gck_object_set ()

    gboolean            gck_object_set                      (GckObject *self,
                                                             GckAttributes *attrs,
                                                             GCancellable *cancellable,
                                                             GError **error);

Set PKCS#11 attributes on an object. This call may block for an indefinite period.

`self` : | The object to set attributes on.
`attrs` : | The attributes to set on the object.
`cancellable` : | Optional cancellable object, or NULL to ignore.
`error` : | A location to return an error.
Returns : | Whether the call was successful or not.

### gck_object_set_async ()

    void                gck_object_set_async                (GckObject *self,
                                                             GckAttributes *attrs,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Set PKCS#11 attributes on an object. This call will return immediately and completes asynchronously.

`self` : | The object to set attributes on.
`attrs` : | The attributes to set on the object.
`cancellable` : | Optional cancellable object, or NULL to ignore.
`callback` : | Callback which is called when operation completes.
`user_data` : | Data to pass to the callback.

### gck_object_set_finish ()

    gboolean            gck_object_set_finish               (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Get the status of the operation to set attributes on a PKCS#11 object, begun with `gck_object_set_async()`.

`self` : | The object to set attributes on.
`result` : | The result of the destory operation passed to the callback.
`error` : | A location to store an error.
Returns : | Whether the attributes were successfully set on the object or not.

### gck_object_get ()

    GckAttributes *     gck_object_get                      (GckObject *self,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             ...);

Get the specified attributes from the object. This call may block for an indefinite period.

`self` : | The object to get attributes from.
`cancellable` : | A GCancellable or `NULL`
`error` : | A location to store an error.
`...` : | The attribute types to get.
Returns : | The resulting PKCS#11 attributes, or NULL if an error occurred. The result must be unreffed when you're finished with it.

### gck_object_get_async ()

    void                gck_object_get_async                (GckObject *self,
                                                             gulong *attr_types,
                                                             guint n_attr_types,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Get the specified attributes from the object. The attributes will be cleared of their current values, and new attributes will be stored. The attributes should not be accessed in any way except for referencing and unreferencing them until `gck_object_get_finish()` is called.

This call returns immediately and completes asynchronously.

`self` : | The object to get attributes from.
`attr_types` : | The types of the attributes to get.
`n_attr_types` : | The number of attr_types
`cancellable` : | Optional cancellation object, or NULL.
`callback` : | A callback which is called when the operation completes.
`user_data` : | Data to be passed to the callback.

### gck_object_get_finish ()

    GckAttributes *     gck_object_get_finish               (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Get the result of a get operation and return specified attributes from the object.

No extra references are added to the returned attributes pointer.

`self` : | The object to get attributes from.
`result` : | The result passed to the callback.
`error` : | A location to store an error.
Returns : | The filled in attributes structure if successful or NULL if not successful.

### gck_object_get_data ()

    gpointer            gck_object_get_data                 (GckObject *self,
                                                             gulong attr_type,
                                                             GCancellable *cancellable,
                                                             gsize *n_data,
                                                             GError **error);

Get the data for the specified attribute from the object. For convenience the returned data has a null terminator.

This call may block for an indefinite period.

`self` : | The object to get attribute data from.
`attr_type` : | The attribute to get data for.
`cancellable` : | A GCancellable or `NULL`
`n_data` : | The length of the resulting data.
`error` : | A location to store an error.
Returns : | The resulting PKCS#11 attribute data, or NULL if an error occurred.

### gck_object_get_data_full ()

    gpointer            gck_object_get_data_full            (GckObject *self,
                                                             gulong attr_type,
                                                             GckAllocator allocator,
                                                             GCancellable *cancellable,
                                                             gsize *n_data,
                                                             GError **error);

Get the data for the specified attribute from the object. For convenience the returned data has an extra null terminator, not included in the returned length.

This call may block for an indefinite period.

`self` : | The object to get attribute data from.
`attr_type` : | The attribute to get data for.
`allocator` : | An allocator with which to allocate memory for the data, or NULL for default.
`cancellable` : | Optional cancellation object, or NULL.
`n_data` : | The length of the resulting data.
`error` : | A location to store an error.
Returns : | The resulting PKCS#11 attribute data, or NULL if an error occurred.

### gck_object_get_data_async ()

    void                gck_object_get_data_async           (GckObject *self,
                                                             gulong attr_type,
                                                             GckAllocator allocator,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Get the data for the specified attribute from the object.

This call will return immediately and complete asynchronously.

`self` : | The object to get attribute data from.
`attr_type` : | The attribute to get data for.
`allocator` : | An allocator with which to allocate memory for the data, or NULL for default.
`cancellable` : | Optional cancellation object, or NULL.
`callback` : | Called when the operation completes.
`user_data` : | Data to be passed to the callback.

### gck_object_get_data_finish ()

    gpointer            gck_object_get_data_finish          (GckObject *self,
                                                             GAsyncResult *result,
                                                             gsize *n_data,
                                                             GError **error);

Get the result of an operation to get attribute data from an object. For convenience the returned data has an extra null terminator, not included in the returned length.

`self` : | The object to get an attribute from.
`result` : | The result passed to the callback.
`n_data` : | The length of the resulting data.
`error` : | A location to store an error.
Returns : | The PKCS#11 attribute data or NULL if an error occurred.

### gck_object_get_full ()

    GckAttributes *     gck_object_get_full                 (GckObject *self,
                                                             gulong *attr_types,
                                                             guint n_attr_types,
                                                             GCancellable *cancellable,
                                                             GError **error);

Get the specified attributes from the object. This call may block for an indefinite period.

No extra references are added to the returned attributes pointer. During this call you may not access the attributes in any way.

`self` : | The object to get attributes from.
`attr_types` : | The types of the attributes to get.
`n_attr_types` : | The number of attr_types
`cancellable` : | Optional cancellation object, or NULL.
`error` : | A location to store an error.
Returns : | A pointer to the filled in attributes if successful, or NULL if not.

### gck_object_get_template ()

    GckAttributes *     gck_object_get_template             (GckObject *self,
                                                             gulong attr_type,
                                                             GCancellable *cancellable,
                                                             GError **error);

Get an attribute template from the object. The attr_type must be for an attribute which returns a template.

This call may block for an indefinite period.

`self` : | The object to get an attribute template from.
`attr_type` : | The template attribute type.
`cancellable` : | Optional cancellation object, or NULL.
`error` : | A location to store an error.
Returns : | The resulting PKCS#11 attribute template, or NULL if an error occurred.

### gck_object_get_template_async ()

    void                gck_object_get_template_async       (GckObject *self,
                                                             gulong attr_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Get an attribute template from the object. The attr_type must be for an attribute which returns a template.

This call will return immediately and complete asynchronously.

`self` : | The object to get an attribute template from.
`attr_type` : | The template attribute type.
`cancellable` : | Optional cancellation object, or NULL.
`callback` : | Called when the operation completes.
`user_data` : | Data to be passed to the callback.

### gck_object_get_template_finish ()

    GckAttributes *     gck_object_get_template_finish      (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Get the result of an operation to get attribute template from an object.

`self` : | The object to get an attribute from.
`result` : | The result passed to the callback.
`error` : | A location to store an error.
Returns : | The resulting PKCS#11 attribute template, or NULL if an error occurred.

### gck_object_set_template ()

    gboolean            gck_object_set_template             (GckObject *self,
                                                             gulong attr_type,
                                                             GckAttributes *attrs,
                                                             GCancellable *cancellable,
                                                             GError **error);

Set an attribute template on the object. The attr_type must be for an attribute which contains a template.

This call may block for an indefinite period.

`self` : | The object to set an attribute template on.
`attr_type` : | The attribute template type.
`attrs` : | The attribute template.
`cancellable` : | Optional cancellation object, or NULL.
`error` : | A location to store an error.
Returns : | TRUE if the operation succeeded.

### gck_object_set_template_async ()

    void                gck_object_set_template_async       (GckObject *self,
                                                             gulong attr_type,
                                                             GckAttributes *attrs,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Set an attribute template on the object. The attr_type must be for an attribute which contains a template.

This call will return immediately and complete asynchronously.

`self` : | The object to set an attribute template on.
`attr_type` : | The attribute template type.
`attrs` : | The attribute template.
`cancellable` : | Optional cancellation object, or NULL.
`callback` : | Called when the operation completes.
`user_data` : | Data to be passed to the callback.

### gck_object_set_template_finish ()

    gboolean            gck_object_set_template_finish      (GckObject *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Get the result of an operation to set attribute template on an object.

`self` : | The object to set an attribute template on.
`result` : | The result passed to the callback.
`error` : | A location to store an error.
Returns : | TRUE if the operation succeeded.