GckAttributes

## GckAttributes GckAttributes — A set of PKCS11 attributes. |

## Synopsis

                        GckAttributes;
    #define             GCK_TYPE_ATTRIBUTES
    GckAttributes*      gck_attributes_new                  (void);
    GckAttributes*      gck_attributes_new_empty            (gulong attr_type,
                                                             ...);
    GckAttribute*       gck_attributes_at                   (GckAttributes *attrs,
                                                             guint index);
    GckAttribute*       gck_attributes_add                  (GckAttributes *attrs,
                                                             GckAttribute *attr);
    GckAttribute*       gck_attributes_add_data             (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gconstpointer value,
                                                             gsize length);
    GckAttribute*       gck_attributes_add_invalid          (GckAttributes *attrs,
                                                             gulong attr_type);
    GckAttribute*       gck_attributes_add_empty            (GckAttributes *attrs,
                                                             gulong attr_type);
    GckAttribute*       gck_attributes_add_boolean          (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gboolean value);
    GckAttribute*       gck_attributes_add_string           (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             const gchar *value);
    GckAttribute*       gck_attributes_add_date             (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             const GDate *value);
    GckAttribute*       gck_attributes_add_ulong            (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gulong value);
    GckAttribute*       gck_attributes_find                 (GckAttributes *attrs,
                                                             gulong attr_type);
    gboolean            gck_attributes_find_boolean         (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gboolean *value);
    gboolean            gck_attributes_find_ulong           (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gulong *value);
    gboolean            gck_attributes_find_string          (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gchar **value);
    gboolean            gck_attributes_find_date            (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             GDate *value);
    gulong              gck_attributes_count                (GckAttributes *attrs);
    GckAttributes*      gck_attributes_ref                  (GckAttributes *attrs);
    void                gck_attributes_unref                (GckAttributes *attrs);
    gpointer            (*GckAllocator)                     (gpointer data,
                                                             gsize length);
    #define             GCK_INVALID

## Description

A set of GckAttribute structures. These attributes contain information about a PKCS11 object. Use `gck_object_get()` or `gck_object_set()` to set and retrieve attributes on an object.

## Details

### GckAttributes

    typedef struct _GckAttributes GckAttributes;

A set of GckAttribute structures.

### GCK_TYPE_ATTRIBUTES

    #define             GCK_TYPE_ATTRIBUTES                     (gck_attributes_get_boxed_type ())

### gck_attributes_new ()

    GckAttributes*      gck_attributes_new                  (void);

Create a new GckAttributes array.

Returns : | The new attributes array. When done with the array release it with `gck_attributes_unref()`.

### gck_attributes_new_empty ()

    GckAttributes*      gck_attributes_new_empty            (gulong attr_type,
                                                             ...);

Creates an GckAttributes array with empty attributes. The arguments should be values of attribute types, terminated with gck_INVALID.

`attr_type` : | The first attribute type to add as empty.
`...` : | The arguments should be values of attribute types, terminated with gck_INVALID.
Returns : | The new attributes array. When done with the array release it with `gck_attributes_unref()`.

### gck_attributes_at ()

    GckAttribute*       gck_attributes_at                   (GckAttributes *attrs,
                                                             guint index);

Get attribute at the specified index in the attribute array.

Use `gck_attributes_count()` to determine how many attributes are in the array.

`attrs` : | The attributes array.
`index` : | The attribute index to retrieve.
Returns : | The specified attribute.

### gck_attributes_add ()

    GckAttribute*       gck_attributes_add                  (GckAttributes *attrs,
                                                             GckAttribute *attr);

Add the specified attribute to the array.

The value stored in the attribute will be copied.

`attrs` : | The attributes array to add to
`attr` : | The attribute to add.
Returns : | The attribute that was added.

### gck_attributes_add_data ()

    GckAttribute*       gck_attributes_add_data             (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gconstpointer value,
                                                             gsize length);

Add an attribute with the specified type and value to the array.

The value stored in the attribute will be copied.

`attrs` : | The attributes array to add to.
`attr_type` : | The type of attribute to add.
`value` : | The raw memory of the attribute value.
`length` : | The length of the attribute value.
Returns : | The attribute that was added.

### gck_attributes_add_invalid ()

    GckAttribute*       gck_attributes_add_invalid          (GckAttributes *attrs,
                                                             gulong attr_type);

Add an attribute with the specified type and an 'invalid' value to the array.

`attrs` : | The attributes array to add to.
`attr_type` : | The type of attribute to add.
Returns : | The attribute that was added.

### gck_attributes_add_empty ()

    GckAttribute*       gck_attributes_add_empty            (GckAttributes *attrs,
                                                             gulong attr_type);

Add an attribute with the specified type, with empty data.

`attrs` : | The attributes array to add.
`attr_type` : | The type of attribute to add.
Returns : | The attribute that was added.

### gck_attributes_add_boolean ()

    GckAttribute*       gck_attributes_add_boolean          (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gboolean value);

Add an attribute with the specified type and value to the array.

The value will be stored as a CK_BBOOL PKCS11 style attribute.

`attrs` : | The attributes array to add to.
`attr_type` : | The type of attribute to add.
`value` : | The boolean value to add.
Returns : | The attribute that was added.

### gck_attributes_add_string ()

    GckAttribute*       gck_attributes_add_string           (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             const gchar *value);

Add an attribute with the specified type and value to the array.

The value will be copied into the attribute.

`attrs` : | The attributes array to add to.
`attr_type` : | The type of attribute to add.
`value` : | The null terminated string value to add.
Returns : | The attribute that was added.

### gck_attributes_add_date ()

    GckAttribute*       gck_attributes_add_date             (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             const GDate *value);

Add an attribute with the specified type and value to the array.

The value will be stored as a CK_DATE PKCS11 style attribute.

`attrs` : | The attributes array to add to.
`attr_type` : | The type of attribute to add.
`value` : | The GDate value to add.
Returns : | The attribute that was added.

### gck_attributes_add_ulong ()

    GckAttribute*       gck_attributes_add_ulong            (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gulong value);

Add an attribute with the specified type and value to the array.

The value will be stored as a CK_ULONG PKCS11 style attribute.

`attrs` : | The attributes array to add to.
`attr_type` : | The type of attribute to add.
`value` : | The gulong value to add.
Returns : | The attribute that was added.

### gck_attributes_find ()

    GckAttribute*       gck_attributes_find                 (GckAttributes *attrs,
                                                             gulong attr_type);

Find an attribute with the specified type in the array.

`attrs` : | The attributes array to search.
`attr_type` : | The type of attribute to find.
Returns : | The first attribute found with the specified type, or NULL.

### gck_attributes_find_boolean ()

    gboolean            gck_attributes_find_boolean         (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gboolean *value);

Find an attribute with the specified type in the array.

The attribute (if found) must be of the right size to store a boolean value (ie: CK_BBOOL). If the attribute is marked invalid then it will be treated as not found.

`attrs` : | The attributes array to search.
`attr_type` : | The type of attribute to find.
`value` : | The resulting gboolean value.
Returns : | Whether a value was found or not.

### gck_attributes_find_ulong ()

    gboolean            gck_attributes_find_ulong           (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gulong *value);

Find an attribute with the specified type in the array.

The attribute (if found) must be of the right size to store a unsigned long value (ie: CK_ULONG). If the attribute is marked invalid then it will be treated as not found.

`attrs` : | The attributes array to search.
`attr_type` : | The type of attribute to find.
`value` : | The resulting gulong value.
Returns : | Whether a value was found or not.

### gck_attributes_find_string ()

    gboolean            gck_attributes_find_string          (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             gchar **value);

Find an attribute with the specified type in the array.

If the attribute is marked invalid then it will be treated as not found. The resulting string will be null-terminated, and must be freed by the caller using `g_free()`.

`attrs` : | The attributes array to search.
`attr_type` : | The type of attribute to find.
`value` : | The resulting string value.
Returns : | Whether a value was found or not.

### gck_attributes_find_date ()

    gboolean            gck_attributes_find_date            (GckAttributes *attrs,
                                                             gulong attr_type,
                                                             GDate *value);

Find an attribute with the specified type in the array.

The attribute (if found) must be of the right size to store a date value (ie: CK_DATE). If the attribute is marked invalid then it will be treated as not found.

`attrs` : | The attributes array to search.
`attr_type` : | The type of attribute to find.
`value` : | The resulting GDate value.
Returns : | Whether a value was found or not.

### gck_attributes_count ()

    gulong              gck_attributes_count                (GckAttributes *attrs);

Get the number of attributes in this attribute array.

`attrs` : | The attributes array to count.
Returns : | The number of contained attributes.

### gck_attributes_ref ()

    GckAttributes*      gck_attributes_ref                  (GckAttributes *attrs);

Reference this attributes array.

`attrs` : | An attribute array
Returns : | The attributes.

### gck_attributes_unref ()

    void                gck_attributes_unref                (GckAttributes *attrs);

Unreference this attribute array.

When all outstanding references are NULL, the array will be freed.

`attrs` : | An attribute array

### GckAllocator ()

    gpointer            (*GckAllocator)                     (gpointer data,
                                                             gsize length);

An allocator used to allocate data for the attributes in this GckAttributes set.

This is a function that acts like g_realloc. Specifically it frees when length is set to zero, it allocates when data is set to NULL, and it reallocates when both are valid.

`data` : | Memory to allocate or deallocate.
`length` : | New length of memory.
Returns : | The allocated memory, or NULL when freeing.

### GCK_INVALID

    #define GCK_INVALID G_MAXULONG