## GP11Attributes

GP11Attributes — A set of PKCS11 attributes.

## Synopsis

                        GP11Attributes;
    #define             GP11_TYPE_ATTRIBUTES
    GP11Attributes*     gp11_attributes_new                 (void);
    GP11Attributes*     gp11_attributes_new_empty           (gulong attr_type,
                                                             ...);
    GP11Attributes*     gp11_attributes_newv                (gulong attr_type,
                                                             ...);
    GP11Attribute*      gp11_attributes_at                  (GP11Attributes *attrs,
                                                             guint index);
    GP11Attribute*      gp11_attributes_add                 (GP11Attributes *attrs,
                                                             GP11Attribute *attr);
    GP11Attribute*      gp11_attributes_add_data            (GP11Attributes *attrs,
                                                             gulong attr_type,
                                                             gconstpointer value,
                                                             gsize length);
    GP11Attribute*      gp11_attributes_add_invalid         (GP11Attributes *attrs,
                                                             gulong attr_type);
    GP11Attribute*      gp11_attributes_add_empty           (GP11Attributes *attrs,
                                                             gulong attr_type);
    GP11Attribute*      gp11_attributes_add_boolean         (GP11Attributes *attrs,
                                                             gulong attr_type,
                                                             gboolean value);
    GP11Attribute*      gp11_attributes_add_string          (GP11Attributes *attrs,
                                                             gulong attr_type,
                                                             const gchar *value);
    GP11Attribute*      gp11_attributes_add_date            (GP11Attributes *attrs,
                                                             gulong attr_type,
                                                             const GDate *value);
    GP11Attribute*      gp11_attributes_add_ulong           (GP11Attributes *attrs,
                                                             gulong attr_type,
                                                             gulong value);
    GP11Attribute*      gp11_attributes_find                (GP11Attributes *attrs,
                                                             gulong attr_type);
    gboolean            gp11_attributes_find_boolean        (GP11Attributes *attrs,
                                                             gulong attr_type,
                                                             gboolean *value);
    gboolean            gp11_attributes_find_ulong          (GP11Attributes *attrs,
                                                             gulong attr_type,
                                                             gulong *value);
    gboolean            gp11_attributes_find_string         (GP11Attributes *attrs,
                                                             gulong attr_type,
                                                             gchar **value);
    gboolean            gp11_attributes_find_date           (GP11Attributes *attrs,
                                                             gulong attr_type,
                                                             GDate *value);
    gulong              gp11_attributes_count               (GP11Attributes *attrs);
    GP11Attributes*     gp11_attributes_ref                 (GP11Attributes *attrs);
    void                gp11_attributes_unref               (GP11Attributes *attrs);
    gpointer            (*GP11Allocator)                    (gpointer data,
                                                             gsize length);
    #define             GP11_BOOLEAN
    #define             GP11_ULONG
    #define             GP11_STRING
    #define             GP11_DATE
    #define             GP11_INVALID

## Description

A set of GP11Attribute structures. These attributes contain information about a PKCS11 object. Use `gp11_object_get()` or `gp11_object_set()` to set and retrieve attributes on an object.

## Details

### GP11Attributes

    typedef struct _GP11Attributes GP11Attributes;

A set of GP11Attribute structures.

### GP11_TYPE_ATTRIBUTES

    #define             GP11_TYPE_ATTRIBUTES                    (gp11_attributes_get_boxed_type ())

### gp11_attributes_new ()

    GP11Attributes*     gp11_attributes_new                 (void);

Create a new GP11Attributes array.

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

### gp11_attributes_new_empty ()

    GP11Attributes*     gp11_attributes_new_empty           (gulong attr_type,
                                                             ...);

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

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

### gp11_attributes_newv ()

    GP11Attributes*     gp11_attributes_newv                (gulong attr_type,
                                                             ...);

Create a new GP11Attributes array, containing a list of attributes.

The variable argument list should contain:

a) | The gulong attribute type (ie: CKA_LABEL).
b) | The attribute data type (one of GP11_BOOLEAN, GP11_ULONG, GP11_STRING, GP11_DATE) orthe raw attribute value length.
c) | The attribute value, either a gboolean, gulong, gchar*, GDate* or a pointer to a raw attribute value.

The variable argument list should be terminated with GP11_INVALID.

`attr_type` : | The first attribute type.
`...` : | The arguments must be triples of: attribute type, data type, value
Returns : | The new attributes array. When done with the array release it with `gp11_attributes_unref()`.

### gp11_attributes_at ()

    GP11Attribute*      gp11_attributes_at                  (GP11Attributes *attrs,
                                                             guint index);

Get attribute at the specified index in the attribute array.

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

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

### gp11_attributes_add ()

    GP11Attribute*      gp11_attributes_add                 (GP11Attributes *attrs,
                                                             GP11Attribute *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.

### gp11_attributes_add_data ()

    GP11Attribute*      gp11_attributes_add_data            (GP11Attributes *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.

### gp11_attributes_add_invalid ()

    GP11Attribute*      gp11_attributes_add_invalid         (GP11Attributes *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.

### gp11_attributes_add_empty ()

    GP11Attribute*      gp11_attributes_add_empty           (GP11Attributes *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.

### gp11_attributes_add_boolean ()

    GP11Attribute*      gp11_attributes_add_boolean         (GP11Attributes *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.

### gp11_attributes_add_string ()

    GP11Attribute*      gp11_attributes_add_string          (GP11Attributes *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.

### gp11_attributes_add_date ()

    GP11Attribute*      gp11_attributes_add_date            (GP11Attributes *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.

### gp11_attributes_add_ulong ()

    GP11Attribute*      gp11_attributes_add_ulong           (GP11Attributes *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.

### gp11_attributes_find ()

    GP11Attribute*      gp11_attributes_find                (GP11Attributes *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.

### gp11_attributes_find_boolean ()

    gboolean            gp11_attributes_find_boolean        (GP11Attributes *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.

### gp11_attributes_find_ulong ()

    gboolean            gp11_attributes_find_ulong          (GP11Attributes *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.

### gp11_attributes_find_string ()

    gboolean            gp11_attributes_find_string         (GP11Attributes *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.

### gp11_attributes_find_date ()

    gboolean            gp11_attributes_find_date           (GP11Attributes *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.

### gp11_attributes_count ()

    gulong              gp11_attributes_count               (GP11Attributes *attrs);

Get the number of attributes in this attribute array.

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

### gp11_attributes_ref ()

    GP11Attributes*     gp11_attributes_ref                 (GP11Attributes *attrs);

Reference this attributes array.

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

### gp11_attributes_unref ()

    void                gp11_attributes_unref               (GP11Attributes *attrs);

Unreference this attribute array.

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

`attrs` : | An attribute array

### GP11Allocator ()

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

An allocator used to allocate data for the attributes in this GP11Attributes 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.

### GP11_BOOLEAN

    #define GP11_BOOLEAN  ((gssize)-1)

The attribute data is a gboolean. Used with variable argument functions.

### GP11_ULONG

    #define GP11_ULONG    ((gssize)-2)

The attribute data is a gulong. Used with variable argument functions.

### GP11_STRING

    #define GP11_STRING   ((gssize)-3)

The attribute data is a gchar. Used with variable argument functions.

### GP11_DATE

    #define GP11_DATE     ((gssize)-4)

Signifies that no more attributes follow. Used with variable argument functions.

### GP11_INVALID

    #define GP11_INVALID G_MAXULONG