GNOME.org
 

[gcr] gck: Add documentation for newly functions

commit 742d24ccecd31071a5e763c1e1884fb0dac5558b
Author: Stef Walter <stefw collabora co uk>
Date:   Thu Dec 8 17:41:56 2011 +0100

    gck: Add documentation for newly functions

 docs/reference/gck/gck-docs.sgml    |    2 +-
 docs/reference/gck/gck-sections.txt |  124 ++++++---
 gck/gck-attributes.c                |  526 ++++++++++++++++++++++++++++++++++-
 gck/gck-enumerator.c                |    2 +-
 gck/gck-misc.c                      |    1 +
 gck/gck-module.c                    |    4 +-
 gck/gck-modules.c                   |    6 +-
 gck/gck-object-cache.c              |  154 +++++++++--
 gck/gck-object.c                    |    8 +
 gck/gck-session.c                   |   35 +++
 gck/gck-slot.c                      |    4 +
 gck/gck.h                           |   10 +-
 gck/gck.symbols                     |    2 +-
 gck/tests/test-gck-enumerator.c     |    6 +-
 gcr/tests/test-subject-public-key.c |    6 +-
 15 files changed, 800 insertions(+), 90 deletions(-)
---
diff --git a/docs/reference/gck/gck-docs.sgml b/docs/reference/gck/gck-docs.sgml
index e70290a..b89be0b 100644
--- a/docs/reference/gck/gck-docs.sgml
+++ b/docs/reference/gck/gck-docs.sgml
@@ -21,7 +21,7 @@
 		<xi:include href="xml/gck-object.xml"/>
 		<xi:include href="xml/gck-attribute.xml"/>
 		<xi:include href="xml/gck-attributes.xml"/>
-		<xi:include href="xml/gck-object-attributes.xml"/>
+		<xi:include href="xml/gck-object-cache.xml"/>
 		<xi:include href="xml/gck-enumerator.xml"/>
 		<xi:include href="xml/gck-modules.xml"/>
 		<xi:include href="xml/gck-error.xml"/>
diff --git a/docs/reference/gck/gck-sections.txt b/docs/reference/gck/gck-sections.txt
index afb4d24..98cf196 100644
--- a/docs/reference/gck/gck-sections.txt
+++ b/docs/reference/gck/gck-sections.txt
@@ -1,33 +1,33 @@
 <SECTION>
 <FILE>gck-attribute</FILE>
 GckAttribute
+gck_attribute_is_invalid
+gck_attribute_get_boolean
+gck_attribute_get_ulong
+gck_attribute_get_string
+gck_attribute_get_date
+gck_attribute_dump
+gck_attribute_equal
+gck_attribute_hash
 gck_attribute_init
-gck_attribute_init_invalid
-gck_attribute_init_empty
 gck_attribute_init_boolean
 gck_attribute_init_date
-gck_attribute_init_ulong
 gck_attribute_init_string
+gck_attribute_init_ulong
+gck_attribute_init_empty
+gck_attribute_init_invalid
 gck_attribute_init_copy
 gck_attribute_new
-gck_attribute_new_invalid
-gck_attribute_new_empty
 gck_attribute_new_boolean
 gck_attribute_new_date
-gck_attribute_new_ulong
 gck_attribute_new_string
-gck_attribute_is_invalid
-gck_attribute_get_boolean
-gck_attribute_get_ulong
-gck_attribute_get_string
-gck_attribute_get_date
+gck_attribute_new_ulong
+gck_attribute_new_empty
+gck_attribute_new_invalid
 gck_attribute_dup
 gck_attribute_clear
 gck_attribute_free
-gck_attribute_dump
-gck_attribute_equal
-gck_attribute_hash
-<SUBSECTION Private>
+<SUBSECTION Standard>
 GCK_TYPE_ATTRIBUTE
 gck_attribute_get_type
 </SECTION>
@@ -35,25 +35,8 @@ gck_attribute_get_type
 <SECTION>
 <FILE>gck-attributes</FILE>
 GckAttributes
-gck_attributes_new
 gck_attributes_new_empty
 gck_attributes_at
-gck_attributes_add
-gck_attributes_add_data
-gck_attributes_add_invalid
-gck_attributes_add_empty
-gck_attributes_add_boolean
-gck_attributes_add_string
-gck_attributes_add_date
-gck_attributes_add_ulong
-gck_attributes_add_all
-gck_attributes_dup
-gck_attributes_set
-gck_attributes_set_boolean
-gck_attributes_set_string
-gck_attributes_set_date
-gck_attributes_set_ulong
-gck_attributes_set_all
 gck_attributes_find
 gck_attributes_find_boolean
 gck_attributes_find_ulong
@@ -61,16 +44,60 @@ gck_attributes_find_string
 gck_attributes_find_date
 gck_attributes_count
 gck_attributes_ref
+gck_attributes_ref_sink
 gck_attributes_unref
 gck_attributes_contains
 gck_attributes_to_string
 gck_attributes_dump
-gck_attributes_new_full
-GCK_TYPE_ATTRIBUTES
-GckAllocator
+GckBuilder
+GckBuilderFlags
+GCK_BUILDER_INIT
+gck_builder_init
+gck_builder_init_full
+gck_builder_new
+gck_builder_add_boolean
+gck_builder_set_boolean
+gck_builder_add_data
+gck_builder_set_data
+gck_builder_take_data
+gck_builder_add_date
+gck_builder_set_date
+gck_builder_add_string
+gck_builder_set_string
+gck_builder_add_ulong
+gck_builder_set_ulong
+gck_builder_add_empty
+gck_builder_set_empty
+gck_builder_add_invalid
+gck_builder_set_invalid
+gck_builder_add_attribute
+gck_builder_add_owned
+gck_builder_add_all
+gck_builder_set_all
+gck_builder_add_except
+gck_builder_add_exceptv
+gck_builder_add_only
+gck_builder_add_onlyv
+gck_builder_end
+gck_builder_clear
+gck_builder_steal
+gck_builder_ref
+gck_builder_unref
+gck_builder_copy
+gck_builder_find
+gck_builder_find_boolean
+gck_builder_find_date
+gck_builder_find_string
+gck_builder_find_ulong
 <SUBSECTION Standard>
+GCK_TYPE_BUILDER
+GCK_TYPE_BUILDER_FLAGS
+GCK_TYPE_ATTRIBUTES
 gck_attributes_get_type
 gck_attributes_get_boxed_type
+gck_builder_flags_get_type
+gck_builder_get_type
+GckAllocator
 </SECTION>
 
 <SECTION>
@@ -307,17 +334,24 @@ GckObjectPrivate
 </SECTION>
 
 <SECTION>
-<FILE>gck-object-attributes</FILE>
-GckObjectAttributes
-GckObjectAttributesIface
-gck_object_attributes_get_attributes
-gck_object_attributes_set_attributes
+<FILE>gck-object-cache</FILE>
+GckObjectCache
+GckObjectCacheIface
+gck_object_cache_get_attributes
+gck_object_cache_set_attributes
+gck_object_cache_fill
+gck_object_cache_lookup
+gck_object_cache_lookup_async
+gck_object_cache_lookup_finish
+gck_object_cache_update
+gck_object_cache_update_async
+gck_object_cache_update_finish
 <SUBSECTION Standard>
-gck_object_attributes_get_type
-GCK_IS_OBJECT_ATTRIBUTES
-GCK_OBJECT_ATTRIBUTES
-GCK_OBJECT_ATTRIBUTES_GET_INTERFACE
-GCK_TYPE_OBJECT_ATTRIBUTES
+gck_object_cache_get_type
+GCK_IS_OBJECT_CACHE
+GCK_OBJECT_CACHE
+GCK_OBJECT_CACHE_GET_INTERFACE
+GCK_TYPE_OBJECT_CACHE
 </SECTION>
 
 <SECTION>
diff --git a/gck/gck-attributes.c b/gck/gck-attributes.c
index d32e2cb..5c24276 100644
--- a/gck/gck-attributes.c
+++ b/gck/gck-attributes.c
@@ -173,6 +173,47 @@ gck_builder_get_type (void)
 	return type;
 }
 
+/**
+ * GckBuilder:
+ *
+ * A builder for a set of attributes. Add attributes to a builder, and then use
+ * gck_builder_end() to get the completed #GckAttributes.
+ *
+ * The fields of #GckBuilder are private and not to be accessed directly.
+ */
+
+/**
+ * GckBuilderFlags:
+ * @GCK_BUILDER_NONE: no special flags
+ * @GCK_BUILDER_SECURE_MEMORY: use non-pageable memory for the values of the attributes
+ *
+ * Flags to be used with a gck_builder_init_full() and gck_builder_new().
+ */
+
+/**
+ * GCK_BUILDER_INIT:
+ *
+ * Values that can be assigned to a #GckBuilder allocated on the stack.
+ *
+ * <informalexample><programlisting>
+ * GckBuilder builder = GCK_BUILDER_INIT;
+ * </programlisting></informalexample>
+ */
+
+/**
+ * gck_builder_new:
+ * @flags: flags for the new builder
+ *
+ * Create a new #GckBuilder not allocated on the stack, so it can be shared
+ * across a single scope, and referenced / unreferenced.
+ *
+ * Normally a #GckBuilder is created on the stack, and simply initialized.
+ *
+ * If the %GCK_BUILDER_SECURE_MEMORY flag is specified then non-pageable memory
+ * will be used for the various values of the attributes in the builder
+ *
+ * Returns: (transfer full): a new builder, to be freed with gck_builder_unref()
+ */
 GckBuilder *
 gck_builder_new (GckBuilderFlags flags)
 {
@@ -185,6 +226,18 @@ gck_builder_new (GckBuilderFlags flags)
 	return builder;
 }
 
+/**
+ * gck_builder_ref:
+ * @builder: the builder
+ *
+ * Add a reference to a builder that was created with gck_builder_new(). The
+ * builder must later be unreferenced again with gck_builder_unref().
+ *
+ * It is an error to use this function on builders that were allocated on the
+ * stack.
+ *
+ * Returns: the builder
+ */
 GckBuilder *
 gck_builder_ref (GckBuilder *builder)
 {
@@ -207,6 +260,16 @@ gck_builder_ref (GckBuilder *builder)
 	return builder;
 }
 
+/**
+ * gck_builder_unref:
+ * @builder: the builder
+ *
+ * Unreferences a builder. If this was the last reference then the builder
+ * is freed.
+ *
+ * It is an error to use this function on builders that were allocated on the
+ * stack.
+ */
 void
 gck_builder_unref (gpointer builder)
 {
@@ -221,6 +284,16 @@ gck_builder_unref (gpointer builder)
 	}
 }
 
+/**
+ * gck_builder_init_full:
+ * @builder: the builder
+ * @flags: the flags for the new builder
+ *
+ * Initialize a stack allocated builder, with the appropriate flags.
+ *
+ * If the %GCK_BUILDER_SECURE_MEMORY flag is specified then non-pageable memory
+ * will be used for the various values of the attributes in the builder
+ */
 void
 gck_builder_init_full (GckBuilder *builder,
                        GckBuilderFlags flags)
@@ -233,6 +306,26 @@ gck_builder_init_full (GckBuilder *builder,
 	real->secure = flags & GCK_BUILDER_SECURE_MEMORY;
 }
 
+/**
+ * gck_builder_init:
+ * @builder: the builder
+ *
+ * Initialize a stack allocated builder, with the default flags.
+ *
+ * This is equivalent to initializing a builder variable with the
+ * %GCK_BUILDER_INIT constant, or setting it to zeroed memory.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Equivalent ways of initializing a GckBuilder *<!-- -->/
+ * GckBuilder builder = GCK_BUILDER_INIT;
+ * GckBuilder builder2;
+ * GckBuilder builder3;
+ *
+ * gck_builder_init (&builder2);
+ *
+ * memset (&builder3, 0, sizeof (builder3));
+ * </programlisting></informalexample>
+ */
 void
 gck_builder_init (GckBuilder *builder)
 {
@@ -315,6 +408,19 @@ builder_copy (GckBuilder *builder,
 	}
 }
 
+/**
+ * gck_builder_copy:
+ * @builder: the builder to copy
+ *
+ * Make a copy of the builder and its state. The new builder is allocated
+ * with gck_builder_new() and should be freed with gck_builder_unref().
+ *
+ * Attribute value memory is automatically shared between the two builders,
+ * and is only freed when both are gone.
+ *
+ * Returns: (transfer full): the builder copy, which should be freed with
+ *          gck_builder_unref().
+ */
 GckBuilder *
 gck_builder_copy (GckBuilder *builder)
 {
@@ -332,6 +438,25 @@ gck_builder_copy (GckBuilder *builder)
 	return copy;
 }
 
+/**
+ * gck_builder_take_data:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: (transfer full): (array length=length): (allow-none): the new
+ *         attribute memory
+ * @length: the length of the memory
+ *
+ * Add a new attribute to the builder with an arbitrary value. Unconditionally
+ * adds a new attribute, even if one with the same @attr_type already exists.
+ *
+ * Ownership of the @value memory is taken by the builder, may be reallocated,
+ * and is eventually freed with g_free(). The memory must have been allocated
+ * using the standard GLib memory allocation routines.
+ *
+ * %NULL may be specified for the @value argument, in which case an empty
+ * attribute is created. GCK_INVALID may be specified for the length, in
+ * which case an invalid attribute is created in the PKCS\#11 style.
+ */
 void
 gck_builder_take_data (GckBuilder *builder,
                        gulong attr_type,
@@ -362,6 +487,22 @@ gck_builder_take_data (GckBuilder *builder,
 	}
 }
 
+/**
+ * gck_builder_add_data:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: (array length=length): (allow-none): the new attribute memory
+ * @length: the length of the memory
+ *
+ * Add a new attribute to the builder with an arbitrary value. Unconditionally
+ * adds a new attribute, even if one with the same @attr_type already exists.
+ *
+ * The memory in @value is copied by the builder.
+ *
+ * %NULL may be specified for the @value argument, in which case an empty
+ * attribute is created. GCK_INVALID may be specified for the length, in
+ * which case an invalid attribute is created in the PKCS\#11 style.
+ */
 void
 gck_builder_add_data (GckBuilder *builder,
                       gulong attr_type,
@@ -387,6 +528,23 @@ gck_builder_add_data (GckBuilder *builder,
 	}
 }
 
+/**
+ * gck_builder_set_data:
+ * @builder: the builder
+ * @attr_type: the attribute type
+ * @value: (array length=length): (allow-none): the new attribute memory
+ * @length: the length of the memory
+ *
+ * Set a new attribute to the builder with an arbitrary value. If an attribute
+ * with @attr_type already exists in the builder then it is changed to the new
+ * value, otherwise an attribute is added.
+ *
+ * The memory in @value is copied by the builder.
+ *
+ * %NULL may be specified for the @value argument, in which case an empty
+ * attribute is created. GCK_INVALID may be specified for the length, in
+ * which case an invalid attribute is created in the PKCS\#11 style.
+ */
 void
 gck_builder_set_data (GckBuilder *builder,
                       gulong attr_type,
@@ -412,6 +570,14 @@ gck_builder_set_data (GckBuilder *builder,
 	}
 }
 
+/**
+ * gck_builder_add_empty:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ *
+ * Add a new attribute to the builder that is empty. Unconditionally
+ * adds a new attribute, even if one with the same @attr_type already exists.
+ */
 void
 gck_builder_add_empty (GckBuilder *builder,
                        gulong attr_type)
@@ -421,6 +587,15 @@ gck_builder_add_empty (GckBuilder *builder,
 	builder_push (builder, attr_type);
 }
 
+/**
+ * gck_builder_set_empty:
+ * @builder: the builder
+ * @attr_type: the attribute type
+ *
+ * Set an attribute on the builder that is empty. If an attribute
+ * with @attr_type already exists in the builder then it is changed to the new
+ * value, otherwise an attribute is added.
+ */
 void
 gck_builder_set_empty (GckBuilder *builder,
                        gulong attr_type)
@@ -430,6 +605,15 @@ gck_builder_set_empty (GckBuilder *builder,
 	builder_clear_or_push (builder, attr_type);
 }
 
+/**
+ * gck_builder_add_invalid:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ *
+ * Add a new attribute to the builder that is invalid in the PKCS\#11 sense.
+ * Unconditionally adds a new attribute, even if one with the same @attr_type
+ * already exists.
+ */
 void
 gck_builder_add_invalid (GckBuilder *builder,
                          gulong attr_type)
@@ -442,6 +626,15 @@ gck_builder_add_invalid (GckBuilder *builder,
 	attr->length = (gulong)-1;
 }
 
+/**
+ * gck_builder_set_invalid:
+ * @builder: the builder
+ * @attr_type: the attribute type
+ *
+ * Set an attribute on the builder that is invalid in the PKCS\#11 sense.
+ * If an attribute with @attr_type already exists in the builder then it is
+ * changed to the new value, otherwise an attribute is added.
+ */
 void
 gck_builder_set_invalid (GckBuilder *builder,
                          gulong attr_type)
@@ -454,6 +647,16 @@ gck_builder_set_invalid (GckBuilder *builder,
 	attr->length = (gulong)-1;
 }
 
+/**
+ * gck_builder_add_ulong:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: the attribute value
+ *
+ * Add a new attribute to the builder for the unsigned long @value.
+ * Unconditionally adds a new attribute, even if one with the same @attr_type
+ * already exists.
+ */
 void
 gck_builder_add_ulong (GckBuilder *builder,
                        gulong attr_type,
@@ -464,6 +667,16 @@ gck_builder_add_ulong (GckBuilder *builder,
 	                      (const guchar *)&uval, sizeof (uval));
 }
 
+/**
+ * gck_builder_set_ulong:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: the attribute value
+ *
+ * Set an attribute on the builder for the unsigned long @value.
+ * If an attribute with @attr_type already exists in the builder then it is
+ * changed to the new value, otherwise an attribute is added.
+ */
 void
 gck_builder_set_ulong (GckBuilder *builder,
                        gulong attr_type,
@@ -474,6 +687,16 @@ gck_builder_set_ulong (GckBuilder *builder,
 	                      (const guchar *)&uval, sizeof (uval));
 }
 
+/**
+ * gck_builder_add_boolean:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: the attribute value
+ *
+ * Add a new attribute to the builder for the boolean @value.
+ * Unconditionally adds a new attribute, even if one with the same @attr_type
+ * already exists.
+ */
 void
 gck_builder_add_boolean (GckBuilder *builder,
                          gulong attr_type,
@@ -484,6 +707,16 @@ gck_builder_add_boolean (GckBuilder *builder,
 	                      (const guchar *)&bval, sizeof (bval));
 }
 
+/**
+ * gck_builder_set_boolean:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: the attribute value
+ *
+ * Set an attribute on the builder for the boolean @value.
+ * If an attribute with @attr_type already exists in the builder then it is
+ * changed to the new value, otherwise an attribute is added.
+ */
 void
 gck_builder_set_boolean (GckBuilder *builder,
                          gulong attr_type,
@@ -508,6 +741,16 @@ convert_gdate_to_ckdate (const GDate *value,
 	memcpy (&date->day, buffer + 6, 2);
 }
 
+/**
+ * gck_builder_add_date:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: the attribute value
+ *
+ * Add a new attribute to the builder for the date @value.
+ * Unconditionally adds a new attribute, even if one with the same @attr_type
+ * already exists.
+ */
 void
 gck_builder_add_date (GckBuilder *builder,
                       gulong attr_type,
@@ -522,6 +765,16 @@ gck_builder_add_date (GckBuilder *builder,
 	                      (const guchar *)&date, sizeof (CK_DATE));
 }
 
+/**
+ * gck_builder_set_date:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: the attribute value
+ *
+ * Set an attribute on the builder for the date @value.
+ * If an attribute with @attr_type already exists in the builder then it is
+ * changed to the new value, otherwise an attribute is added.
+ */
 void
 gck_builder_set_date (GckBuilder *builder,
                       gulong attr_type,
@@ -536,6 +789,16 @@ gck_builder_set_date (GckBuilder *builder,
 	                      (const guchar *)&date, sizeof (CK_DATE));
 }
 
+/**
+ * gck_builder_add_string:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: (allow-none): the attribute value
+ *
+ * Add a new attribute to the builder for the string @value or %NULL.
+ * Unconditionally adds a new attribute, even if one with the same @attr_type
+ * already exists.
+ */
 void
 gck_builder_add_string (GckBuilder *builder,
                         gulong attr_type,
@@ -545,6 +808,16 @@ gck_builder_add_string (GckBuilder *builder,
 	                      (const guchar *)value, value ? strlen (value) : 0);
 }
 
+/**
+ * gck_builder_set_string:
+ * @builder: the builder
+ * @attr_type: the new attribute type
+ * @value: the attribute value
+ *
+ * Set an attribute on the builder for the string @value or %NULL.
+ * If an attribute with @attr_type already exists in the builder then it is
+ * changed to the new value, otherwise an attribute is added.
+ */
 void
 gck_builder_set_string (GckBuilder *builder,
                         gulong attr_type,
@@ -554,6 +827,17 @@ gck_builder_set_string (GckBuilder *builder,
 	                      (const guchar *)value, value ? strlen (value) : 0);
 }
 
+/**
+ * gck_builder_add_attribute:
+ * @builder: the builder
+ * @attr: the attribute to add
+ *
+ * Add a copy of the attribute to the builder. The attribute is added
+ * unconditionally whether or not an attribute with the same type already
+ * exists on the builder.
+ *
+ * The memory in the attribute is copied.
+ */
 void
 gck_builder_add_attribute (GckBuilder *builder,
                            const GckAttribute *attr)
@@ -564,6 +848,21 @@ gck_builder_add_attribute (GckBuilder *builder,
 	gck_builder_add_data (builder, attr->type, attr->value, attr->length);
 }
 
+/**
+ * gck_builder_add_owned:
+ * @builder: the builder
+ * @attr: the attribute to add
+ *
+ * Add an attribute to the builder. The attribute is added unconditionally whether
+ * or not an attribute with the same type already exists on the builder.
+ *
+ * The @attr attribute must already be owned by a #GckAttributes or #GckBuilder.
+ * If you call this function on an arbitrary #GckAttribute that is not owned
+ * it will result in undefined behavior.
+ *
+ * As an optimization, the attribute memory value is automatically shared
+ * between the attribute and the builder.
+ */
 void
 gck_builder_add_owned (GckBuilder *builder,
                        const GckAttribute *attr)
@@ -574,6 +873,18 @@ gck_builder_add_owned (GckBuilder *builder,
 	builder_copy (builder, attr, FALSE);
 }
 
+/**
+ * gck_builder_add_all:
+ * @builder: the builder
+ * @attrs: the attributes to add
+ *
+ * Add all the @attrs attributes to the builder. The attributes are added
+ * uncondititionally whether or not attributes with the same types already
+ * exist in the builder.
+ *
+ * As an optimization, the attribute memory values are automatically shared
+ * between the attributes and the builder.
+ */
 void
 gck_builder_add_all (GckBuilder *builder,
                      GckAttributes *attrs)
@@ -587,6 +898,27 @@ gck_builder_add_all (GckBuilder *builder,
 		builder_copy (builder, &attrs->data[i], FALSE);
 }
 
+/**
+ * gck_builder_add_only: (skip)
+ * @builder: the builder
+ * @attrs: the attributes to add
+ * @only_type: the first type of attribute to add
+ * @...: the remaining attribute types to add, ending with %GCK_INVALID
+ *
+ * Add the attributes specified in the argument list from @attrs to the
+ * builder. The attributes are added uncondititionally whether or not
+ * attributes with the same types already exist in the builder.
+ *
+ * The variable arguments must be unsigned longs.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Add the CKA_ID and CKA_CLASS attributes from attrs to builder *<!-- -->/
+ * gck_builder_add_only (builder, attrs, CKA_ID, CKA_CLASS, GCK_INVALID);
+ * </programlisting></informalexample>
+ *
+ * As an optimization, the attribute memory values are automatically shared
+ * between the attributes and the builder.
+ */
 void
 gck_builder_add_only (GckBuilder *builder,
                       GckAttributes *attrs,
@@ -612,6 +944,28 @@ gck_builder_add_only (GckBuilder *builder,
 	g_array_free (types, TRUE);
 }
 
+/**
+ * gck_builder_add_onlyv:
+ * @builder: the builder
+ * @attrs: the attributes to add
+ * @only_types: (array length=n_only_types): the types of attributes to add
+ * @n_only_types: the number of attributes
+ *
+ * Add the attributes with the types in @only_types from @attrs to the
+ * builder. The attributes are added uncondititionally whether or not
+ * attributes with the same types already exist in the builder.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Add the CKA_ID and CKA_CLASS attributes from attrs to builder *<!-- -->/
+ * gulong only[] = { CKA_ID, CKA_CLASS };
+ * gck_builder_add_onlyv (builder, attrs, only, 2);
+ * </programlisting></informalexample>
+ *
+ * As an optimization, the attribute memory values are automatically shared
+ * between the attributes and the builder.
+ *
+ * Rename to: gck_builder_add_only
+ */
 void
 gck_builder_add_onlyv (GckBuilder *builder,
                        GckAttributes *attrs,
@@ -632,6 +986,27 @@ gck_builder_add_onlyv (GckBuilder *builder,
 	}
 }
 
+/**
+ * gck_builder_add_except: (skip)
+ * @builder: the builder
+ * @attrs: the attributes to add
+ * @except_type: the first type of attribute to to exclude
+ * @...: the remaining attribute types to exclude, ending with %GCK_INVALID
+ *
+ * Add the attributes in @attrs to the builder, with the exception of those
+ * in the argument list. The attributes are added uncondititionally whether or
+ * not attributes with the same types already exist in the builder.
+ *
+ * The variable arguments must be unsigned longs.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Add all attributes in attrs except CKA_CLASS to the builder *<!-- -->/
+ * gck_builder_add_except (builder, attrs, CKA_CLASS, GCK_INVALID);
+ * </programlisting></informalexample>
+ *
+ * As an optimization, the attribute memory values are automatically shared
+ * between the attributes and the builder.
+ */
 void
 gck_builder_add_except (GckBuilder *builder,
                         GckAttributes *attrs,
@@ -657,6 +1032,27 @@ gck_builder_add_except (GckBuilder *builder,
 	g_array_free (types, TRUE);
 }
 
+/**
+ * gck_builder_add_exceptv: (skip)
+ * @builder: the builder
+ * @attrs: the attributes to add
+ * @except_types: (array length=n_except_types): the except types
+ * @n_except_types: the number of except types
+ *
+ * Add the attributes in @attrs to the builder, with the exception of those
+ * whose types are specified in @except_types. The attributes are added
+ * uncondititionally whether or not attributes with the same types already
+ * exist in the builder.
+ *
+ * <informalexample><programlisting>
+ * /<!-- -->* Add all attributes in attrs except CKA_CLASS to the builder *<!-- -->/
+ * gulong except_types[] = { CKA_CLASS };
+ * gck_builder_add_exceptv (builder, attrs, except_types, 1);
+ * </programlisting></informalexample>
+ *
+ * As an optimization, the attribute memory values are automatically shared
+ * between the attributes and the builder.
+ */
 void
 gck_builder_add_exceptv (GckBuilder *builder,
                          GckAttributes *attrs,
@@ -679,6 +1075,18 @@ gck_builder_add_exceptv (GckBuilder *builder,
 	}
 }
 
+/**
+ * gck_builder_set_all:
+ * @builder: the builder
+ * @attrs: the attributes to set
+ *
+ * Set all the @attrs attributes to the builder. If any attributes with the
+ * same types are already present in the builder, then those attributes are
+ * changed to the new values.
+ *
+ * As an optimization, the attribute memory values are automatically shared
+ * between the attributes and the builder.
+ */
 void
 gck_builder_set_all (GckBuilder *builder,
                      GckAttributes *attrs)
@@ -692,6 +1100,21 @@ gck_builder_set_all (GckBuilder *builder,
 		builder_copy (builder, &attrs->data[i], TRUE);
 }
 
+/**
+ * gck_builder_find:
+ * @builder: the builder
+ * @attr_type: the type of attribute to find
+ *
+ * Find an attribute in the builder. Both valid and invalid attributes (in
+ * the PKCS\#11 sense) are returned. If multiple attributes exist for the given
+ * attribute type, then the first one is returned.
+ *
+ * The returned #GckAttribute is owned by the builder and may not be modified
+ * in any way. It is only valid until another attribute is added to or set on
+ * the builder, or until the builder is cleared or unreferenced.
+ *
+ * Returns: the attribute or %NULL if not found
+ */
 const GckAttribute *
 gck_builder_find (GckBuilder *builder,
                   gulong attr_type)
@@ -718,11 +1141,22 @@ find_attribute_boolean (GckAttribute *attrs,
 	attr = find_attribute (attrs, n_attrs, attr_type);
 	if (!attr || gck_attribute_is_invalid (attr))
 		return FALSE;
-	*value = gck_attribute_get_boolean (attr);
-	return TRUE;
+	return gck_value_to_boolean (attr->value, attr->length, value);
 }
 
-
+/**
+ * gck_builder_find_boolean:
+ * @builder: the builder
+ * @attr_type: the type of attribute to find
+ * @value: (out): the location to place the found value
+ *
+ * Find a boolean attribute in the builder that has the type @attr_type, is
+ * of the correct boolean size, and is not invalid in the PKCS\#11 sense.
+ * If multiple attributes exist for the given attribute type, then the first\
+ * one is returned.
+ *
+ * Returns: whether a valid boolean attribute was found
+ */
 gboolean
 gck_builder_find_boolean (GckBuilder *builder,
                           gulong attr_type,
@@ -751,10 +1185,22 @@ find_attribute_ulong (GckAttribute *attrs,
 	attr = find_attribute (attrs, n_attrs, attr_type);
 	if (!attr || gck_attribute_is_invalid (attr))
 		return FALSE;
-	*value = gck_attribute_get_ulong (attr);
-	return TRUE;
+	return gck_value_to_ulong (attr->value, attr->length, value);
 }
 
+/**
+ * gck_builder_find_ulong:
+ * @builder: the builder
+ * @attr_type: the type of attribute to find
+ * @value: (out): the location to place the found value
+ *
+ * Find a unsigned long attribute in the builder that has the type @attr_type,
+ * is of the correct unsigned long size, and is not invalid in the PKCS\#11 sense.
+ * If multiple attributes exist for the given attribute type, then the first\
+ * one is returned.
+ *
+ * Returns: whether a valid unsigned long attribute was found
+ */
 gboolean
 gck_builder_find_ulong (GckBuilder *builder,
                         gulong attr_type,
@@ -791,6 +1237,19 @@ find_attribute_string (GckAttribute *attrs,
 	return TRUE;
 }
 
+/**
+ * gck_builder_find_string:
+ * @builder: the builder
+ * @attr_type: the type of attribute to find
+ * @value: (out): the location to place the found value
+ *
+ * Find a string attribute in the builder that has the type @attr_type, has a
+ * non %NULL value pointer, and is not invalid in the PKCS\#11 sense.
+ * If multiple attributes exist for the given attribute type, then the first
+ * one is returned.
+ *
+ * Returns: whether a valid string attribute was found
+ */
 gboolean
 gck_builder_find_string (GckBuilder *builder,
                          gulong attr_type,
@@ -822,6 +1281,20 @@ find_attribute_date (GckAttribute *attrs,
 	gck_attribute_get_date (attr, value);
 	return TRUE;
 }
+
+/**
+ * gck_builder_find_date:
+ * @builder: the builder
+ * @attr_type: the type of attribute to find
+ * @value: (out): the location to place the found value
+ *
+ * Find a date attribute in the builder that has the type @attr_type, is of
+ * the correct date size, and is not invalid in the PKCS\#11 sense.
+ * If multiple attributes exist for the given attribute type, then the first
+ * one is returned.
+ *
+ * Returns: whether a valid date attribute was found
+ */
 gboolean
 gck_builder_find_date (GckBuilder *builder,
                        gulong attr_type,
@@ -885,7 +1358,8 @@ gck_builder_steal (GckBuilder *builder)
  * Complete the #GckBuilder, and return the attributes contained in the builder.
  * The #GckBuilder will be cleared after this function call, and it is no
  * longer necessary to use gck_builder_clear() on it, although it is also
- * permitted.
+ * permitted. The builder may be used again to build another set of attributes
+ * after this function call.
  *
  * The returned set of attributes is floating, and should either be passed to
  * another gck library function which consumes this floating reference, or if
@@ -910,6 +1384,16 @@ gck_builder_end (GckBuilder *builder)
 	return attrs;
 }
 
+/**
+ * gck_builder_clear:
+ * @builder: the builder
+ *
+ * Clear the builder and release all allocated memory. The builder may be used
+ * again to build another set of attributes after this function call.
+ *
+ * If memory is shared between this builder and other attributes, then that
+ * memory is only freed when both of them are cleared or unreferenced.
+ */
 void
 gck_builder_clear (GckBuilder *builder)
 {
@@ -1787,7 +2271,7 @@ gck_attributes_find_date (GckAttributes *attrs, gulong attr_type, GDate *value)
  *
  * Reference this attributes array.
  *
- * Returns: (transfer full): the attributes
+ * Returns: the attributes
  **/
 GckAttributes *
 gck_attributes_ref (GckAttributes *attrs)
@@ -1797,6 +2281,30 @@ gck_attributes_ref (GckAttributes *attrs)
 	return attrs;
 }
 
+/**
+ * gck_attributes_ref_sink:
+ * @attrs: an attribute array
+ *
+ * #GckAttributes uses a floating reference count system. gck_builder_end()
+ * and gck_attributes_new_empty() both return floating references.
+ *
+ * Calling gck_attributes_ref_sink() on a #GckAttributes with a floating
+ * reference will convert the floating reference into a full reference.
+ * Calling gck_attributes_ref_sink() on a non-floating #GckAttributes results
+ * in an additional normal reference being added.
+ *
+ * In other words, if the @attrs is floating, then this call "assumes
+ * ownership" of the floating reference, converting it to a normal
+ * reference.  If the @attrs is not floating, then this call adds a
+ * new normal reference increasing the reference count by one.
+ *
+ * All Gck library functions that assume ownership of floating references
+ * are documented as such. Essentially any Gck function that performs
+ * an operation using a #GckAttributes argument rather than operating on the
+ * atributes themselves, will accept a floating reference.
+ *
+ * Returns: the referenced attributes
+ */
 GckAttributes *
 gck_attributes_ref_sink (GckAttributes *attrs)
 {
@@ -1814,11 +2322,11 @@ gck_attributes_ref_sink (GckAttributes *attrs)
 
 /**
  * gck_attributes_unref:
- * @attrs: An attribute array
+ * @attrs: (allow-none): (type Gck.Attributes): An attribute array
  *
  * Unreference this attribute array.
  *
- * When all outstanding references are NULL, the array will be freed.
+ * When all outstanding references are gone, the array will be freed.
  */
 void
 gck_attributes_unref (gpointer attrs)
diff --git a/gck/gck-enumerator.c b/gck/gck-enumerator.c
index 4e60f71..1945797 100644
--- a/gck/gck-enumerator.c
+++ b/gck/gck-enumerator.c
@@ -864,7 +864,7 @@ gck_enumerator_get_object_type (GckEnumerator *self)
  * Set the type of objects to be created by this enumerator. The type must
  * always be either #GckObject or derived from it.
  *
- * If the #GckObjectAttributes interface is implemented on the derived class
+ * If the #GckObjectCache interface is implemented on the derived class
  * and the attribute_types field is set, then the enumerator will retrieve
  * attributes for each object.
  */
diff --git a/gck/gck-misc.c b/gck/gck-misc.c
index 1049142..42780ff 100644
--- a/gck/gck-misc.c
+++ b/gck/gck-misc.c
@@ -48,6 +48,7 @@ EGG_SECURE_DEFINE_GLIB_GLOBALS ();
  * @title: Private, not used in docs
  * @short_description: Should not show up in docs
  *
+ * Should not show up in the docs
  */
 
 /**
diff --git a/gck/gck-module.c b/gck/gck-module.c
index d0fcd46..e5503fa 100644
--- a/gck/gck-module.c
+++ b/gck/gck-module.c
@@ -250,7 +250,7 @@ gck_module_class_init (GckModuleClass *klass)
 	 * @string: A displayable label which describes the object.
 	 * @password: A gchar** where a password should be returned.
 	 *
-	 * Use gck_slot_set_interaction() instead of connecting to this signal.
+	 * Use gck_session_set_interaction() instead of connecting to this signal.
 	 *
 	 * Deprecated: Since 3.4
 	 */
@@ -266,7 +266,7 @@ gck_module_class_init (GckModuleClass *klass)
 	 * @label: A displayable label which describes the object.
 	 * @password: A gchar** where a password should be returned.
 	 *
-	 * Use gck_slot_set_interaction() instead of connecting to this signal.
+	 * Use gck_session_set_interaction() instead of connecting to this signal.
 	 *
 	 * Deprecated: Since 3.4
 	 */
diff --git a/gck/gck-modules.c b/gck/gck-modules.c
index 2cc821b..06301e1 100644
--- a/gck/gck-modules.c
+++ b/gck/gck-modules.c
@@ -196,13 +196,15 @@ gck_modules_get_slots (GList *modules, gboolean token_present)
 /**
  * gck_modules_enumerate_objects:
  * @modules: (element-type Gck.Module): The modules
- * @attrs: Attributes that the objects must have, or empty for all objects
+ * @attrs: attributes that the objects must have, or empty for all objects
  * @session_options: Options from GckSessionOptions
  *
  * Setup an enumerator for listing matching objects on the modules.
  *
  * This call will not block but will return an enumerator immediately.
-
+ *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
  * Return value: (transfer full): A new enumerator, which should be released
  * with g_object_unref().
  **/
diff --git a/gck/gck-object-cache.c b/gck/gck-object-cache.c
index 38b912e..07a4dbc 100644
--- a/gck/gck-object-cache.c
+++ b/gck/gck-object-cache.c
@@ -40,15 +40,25 @@
  */
 
 /**
+ * GckObjectCache:
+ *
+ * An interface implemented on an #GckObject which contains a cache of attributes.
+ */
+
+/**
  * GckObjectCacheIface:
  * @interface: parent interface
  * @default_types: (array length=n_default_types): attribute types that an
  *                   enumerator should retrieve
  * @n_default_types: number of attribute types to be retrieved
+ * @fill: virtual method to add attributes to the cache
  *
  * Interface for #GckObjectCache. If the @default_types field is set by
  * a implementing class, then the a #GckEnumerator which has been setup using
  * gck_enumerator_set_object_type()
+ *
+ * The implementation for @populate should add the attributes to the
+ * cache. It must be thread safe.
  */
 
 typedef GckObjectCacheIface GckObjectCacheInterface;
@@ -75,7 +85,7 @@ gck_object_cache_default_init (GckObjectCacheIface *iface)
 
 /**
  * gck_object_cache_get_attributes:
- * @object: an object with attributes
+ * @object: an object with an attribute cache
  *
  * Gets the attributes cached on this object.
  *
@@ -90,41 +100,71 @@ gck_object_cache_get_attributes (GckObjectCache *object)
 	return attributes;
 }
 
+/**
+ * gck_object_cache_set_attributes:
+ * @object: an object with an attribute cache
+ * @attrs: (allow-none): the attributes to set
+ *
+ * Sets the attributes cached on this object.
+ *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
+ */
 void
 gck_object_cache_set_attributes (GckObjectCache *object,
-                                 GckAttributes *attributes)
+                                 GckAttributes *attrs)
 {
 	g_return_if_fail (GCK_IS_OBJECT_CACHE (object));
 
-	gck_attributes_ref_sink (attributes);
-	g_object_set (object, "attributes", attributes, NULL);
-	gck_attributes_unref (attributes);
+	gck_attributes_ref_sink (attrs);
+	g_object_set (object, "attributes", attrs, NULL);
+	gck_attributes_unref (attrs);
 }
 
 /**
- * gck_object_cache_add_attributes:
- * @object: an object with attributes
- * @attributes: the attributes to cache
+ * gck_object_cache_fill:
+ * @object: an object with the cache
+ * @attrs: the attributes to cache
+ *
+ * Adds the attributes to the set cached on this object. If an attribute is
+ * already present in the cache it will be overridden by this value.
  *
- * Adds the attributes to the set cached on this object.
+ * This will be done in a thread-safe manner.
+ *
+ * If the @attrs #GckAttributes is floating, it is consumed.
  */
 void
-gck_object_cache_add_attributes (GckObjectCache *object,
-                                 GckAttributes *attributes)
+gck_object_cache_fill (GckObjectCache *object,
+                       GckAttributes *attrs)
 {
 	GckObjectCacheIface *iface;
 
 	g_return_if_fail (GCK_IS_OBJECT_CACHE (object));
-	g_return_if_fail (attributes != NULL);
+	g_return_if_fail (attrs != NULL);
 
 	iface = GCK_OBJECT_CACHE_GET_INTERFACE (object);
-	g_return_if_fail (iface->add_attributes != NULL);
+	g_return_if_fail (iface->fill != NULL);
 
-	gck_attributes_ref_sink (attributes);
-	(iface->add_attributes) (object, attributes);
-	gck_attributes_unref (attributes);
+	gck_attributes_ref_sink (attrs);
+	(iface->fill) (object, attrs);
+	gck_attributes_unref (attrs);
 }
 
+/**
+ * gck_object_cache_update:
+ * @object: the object with the cache
+ * @attr_types: (array length=n_attr_types): the types of attributes to update
+ * @n_attr_types: the number of attribute types
+ * @cancellable: optional cancellation object
+ * @error: location to place an error
+ *
+ * Update the object cache with given attributes. If an attribute already
+ * exists in the cache, it will be updated, and if it doesn't it will be added.
+ *
+ * This may block, use the asynchronous version when this is not desirable
+ *
+ * Returns: whether the cache update was successful
+ */
 gboolean
 gck_object_cache_update (GckObjectCache *object,
                          const gulong *attr_types,
@@ -158,7 +198,7 @@ gck_object_cache_update (GckObjectCache *object,
 	                             cancellable, error);
 
 	if (attrs != NULL) {
-		gck_object_cache_add_attributes (object, attrs);
+		gck_object_cache_fill (object, attrs);
 		gck_attributes_unref (attrs);
 	}
 
@@ -176,7 +216,7 @@ on_cache_object_get (GObject *source,
 
 	attrs = gck_object_get_finish (GCK_OBJECT (source), result, &error);
 	if (error == NULL) {
-		gck_object_cache_add_attributes (GCK_OBJECT_CACHE (source), attrs);
+		gck_object_cache_fill (GCK_OBJECT_CACHE (source), attrs);
 		gck_attributes_unref (attrs);
 	} else {
 		g_simple_async_result_take_error (res, error);
@@ -185,6 +225,21 @@ on_cache_object_get (GObject *source,
 	g_simple_async_result_complete (res);
 	g_object_unref (res);
 }
+
+/**
+ * gck_object_cache_update_async:
+ * @object: the object with the cache
+ * @attr_types: (array length=n_attr_types): the types of attributes to update
+ * @n_attr_types: the number of attribute types
+ * @cancellable: optional cancellation object
+ * @callback: called when the operation completes
+ * @user_data: data to be passed to the callback
+ *
+ * Update the object cache with given attributes. If an attribute already
+ * exists in the cache, it will be updated, and if it doesn't it will be added.
+ *
+ * This call will return immediately and complete asynchronously.
+ */
 void
 gck_object_cache_update_async (GckObjectCache *object,
                                const gulong *attr_types,
@@ -222,6 +277,17 @@ gck_object_cache_update_async (GckObjectCache *object,
 	g_object_unref (res);
 }
 
+/**
+ * gck_object_cache_update_finish:
+ * @object: the object with the cache
+ * @result: the asynchronous result passed to the callback
+ * @error: location to place an error
+ *
+ * Complete an asynchronous operation to update the object cache with given
+ * attributes.
+ *
+ * Returns: whether the cache update was successful
+ */
 gboolean
 gck_object_cache_update_finish (GckObjectCache *object,
                                 GAsyncResult *result,
@@ -256,6 +322,27 @@ check_have_attributes (GckAttributes *attrs,
 	return TRUE;
 }
 
+/**
+ * gck_object_cache_lookup:
+ * @object: the object
+ * @attr_types: (array length=n_attr_types): the types of attributes to update
+ * @n_attr_types: the number of attribute types
+ * @cancellable: optional cancellation object
+ * @error: location to place an error
+ *
+ * Lookup attributes in the cache, or retrieve them from the object if necessary.
+ *
+ * If @object is a #GckObjectCache then this will lookup the attributes there
+ * first if available, otherwise will read them from the object and update
+ * the cache.
+ *
+ * If @object is not a #GckObjectCache, then the attributes will simply be
+ * read from the object.
+ *
+ * This may block, use the asynchronous version when this is not desirable
+ *
+ * Returns: (transfer full): the attributes retrieved or %NULL on failure
+ */
 GckAttributes *
 gck_object_cache_lookup (GckObject *object,
                          const gulong *attr_types,
@@ -290,6 +377,26 @@ gck_object_cache_lookup (GckObject *object,
 	}
 }
 
+/**
+ * gck_object_cache_lookup_async:
+ * @object: the object
+ * @attr_types: (array length=n_attr_types): the types of attributes to update
+ * @n_attr_types: the number of attribute types
+ * @cancellable: optional cancellation object
+ * @callback: called when the operation completes
+ * @user_data: data to pass to the callback
+ *
+ * Lookup attributes in the cache, or retrieve them from the object if necessary.
+ *
+ * If @object is a #GckObjectCache then this will lookup the attributes there
+ * first if available, otherwise will read them from the object and update
+ * the cache.
+ *
+ * If @object is not a #GckObjectCache, then the attributes will simply be
+ * read from the object.
+ *
+ * This will return immediately and complete asynchronously
+ */
 void
 gck_object_cache_lookup_async (GckObject *object,
                                const gulong *attr_types,
@@ -328,6 +435,17 @@ gck_object_cache_lookup_async (GckObject *object,
 	}
 }
 
+/**
+ * gck_object_cache_lookup_finish:
+ * @object: the object
+ * @result: the asynchrounous result passed to the callback
+ * @error: location to place an error
+ *
+ * Complete an operation to lookup attributes in the cache or retrieve them
+ * from the object if necessary.
+ *
+ * Returns: (transfer full): the attributes retrieved or %NULL on failure
+ */
 GckAttributes *
 gck_object_cache_lookup_finish (GckObject *object,
                                 GAsyncResult *result,
diff --git a/gck/gck-object.c b/gck/gck-object.c
index 0052393..87c0e7b 100644
--- a/gck/gck-object.c
+++ b/gck/gck-object.c
@@ -507,6 +507,8 @@ free_set_attributes (SetAttributes *args)
  *
  * Set PKCS\#11 attributes on an object. This call may block for an indefinite period.
  *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
  * Return value: Whether the call was successful or not.
  **/
 gboolean
@@ -543,6 +545,8 @@ gck_object_set (GckObject *self, GckAttributes *attrs,
  *
  * Set PKCS\#11 attributes on an object. This call will return
  * immediately and completes asynchronously.
+ *
+ * If the @attrs #GckAttributes is floating, it is consumed.
  **/
 void
 gck_object_set_async (GckObject *self, GckAttributes *attrs, GCancellable *cancellable,
@@ -1057,6 +1061,8 @@ free_set_template (set_template_args *args)
  * Set an attribute template on the object. The attr_type must be for
  * an attribute which contains a template.
  *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
  * This call may block for an indefinite period.
  *
  * Return value: TRUE if the operation succeeded.
@@ -1098,6 +1104,8 @@ gck_object_set_template (GckObject *self, gulong attr_type, GckAttributes *attrs
  * Set an attribute template on the object. The attr_type must be for
  * an attribute which contains a template.
  *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
  * This call will return immediately and complete asynchronously.
  **/
 void
diff --git a/gck/gck-session.c b/gck/gck-session.c
index 055c193..abf8226 100644
--- a/gck/gck-session.c
+++ b/gck/gck-session.c
@@ -1419,6 +1419,8 @@ perform_create_object (CreateObject *args)
  * Create a new PKCS\#11 object. This call may block for an
  * indefinite period.
  *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
  * Returns: (transfer full): the newly created object or %NULL if an error occurred
  **/
 GckObject *
@@ -1451,6 +1453,8 @@ gck_session_create_object (GckSession *self, GckAttributes *attrs,
  *
  * Create a new PKCS\#11 object. This call will return immediately
  * and complete asynchronously.
+ *
+ * If the @attrs #GckAttributes is floating, it is consumed.
  **/
 void
 gck_session_create_object_async (GckSession *self, GckAttributes *attrs,
@@ -1582,6 +1586,8 @@ perform_find_objects (FindObjects *args)
  * Find the objects matching the passed attributes. This call may
  * block for an indefinite period.
  *
+ * If the @match #GckAttributes is floating, it is consumed.
+ *
  * Returns: (transfer full) (array length=n_handles) (allow-none): a list of
  *          the matching objects, which may be empty
  **/
@@ -1623,6 +1629,8 @@ gck_session_find_handles (GckSession *self,
  *
  * Find the objects matching the passed attributes. This call will
  * return immediately and complete asynchronously.
+ *
+ * If the @match #GckAttributes is floating, it is consumed.
  **/
 void
 gck_session_find_handles_async (GckSession *self,
@@ -1688,6 +1696,8 @@ gck_session_find_handles_finish (GckSession *self,
  * Find the objects matching the passed attributes. This call may
  * block for an indefinite period.
  *
+ * If the @match #GckAttributes is floating, it is consumed.
+ *
  * Returns: (transfer full) (element-type Gck.Object): a list of the matching
  *          objects, which may be empty
  **/
@@ -1725,6 +1735,8 @@ gck_session_find_objects (GckSession *self,
  *
  * Find the objects matching the passed attributes. This call will
  * return immediately and complete asynchronously.
+ *
+ * If the @match #GckAttributes is floating, it is consumed.
  **/
 void
 gck_session_find_objects_async (GckSession *self,
@@ -1780,6 +1792,8 @@ gck_session_find_objects_finish (GckSession *self,
  *
  * Setup an enumerator for listing matching objects available via this session.
  *
+ * If the @match #GckAttributes is floating, it is consumed.
+ *
  * This call will not block but will return an enumerator immediately.
  *
  * Returns: (transfer full): a new enumerator
@@ -1852,6 +1866,9 @@ perform_generate_key_pair (GenerateKeyPair *args)
  * Generate a new key pair of public and private keys. This call may block for an
  * indefinite period.
  *
+ * If the @public_attrs and/or @private_attrs #GckAttributes is floating, it is
+ * consumed.
+ *
  * Return value: TRUE if the operation succeeded.
  **/
 gboolean
@@ -1878,6 +1895,9 @@ gck_session_generate_key_pair (GckSession *self, gulong mech_type,
  * Generate a new key pair of public and private keys. This call may block for an
  * indefinite period.
  *
+ * If the @public_attrs and/or @private_attrs #GckAttributes is floating, it is
+ * consumed.
+ *
  * Return value: TRUE if the operation succeeded.
  **/
 gboolean
@@ -1931,6 +1951,9 @@ gck_session_generate_key_pair_full (GckSession *self,
  *
  * Generate a new key pair of public and private keys. This call will
  * return immediately and complete asynchronously.
+ *
+ * If the @public_attrs and/or @private_attrs #GckAttributes is floating, it is
+ * consumed.
  **/
 void
 gck_session_generate_key_pair_async (GckSession *self, GckMechanism *mechanism,
@@ -2230,6 +2253,8 @@ perform_unwrap_key (UnwrapKey *args)
  * Unwrap a key from a byte stream. This call may block for an
  * indefinite period.
  *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
  * Returns: (transfer full): the new unwrapped key or NULL if the
  *          operation failed
  **/
@@ -2261,6 +2286,8 @@ gck_session_unwrap_key (GckSession *self,
  * Unwrap a key from a byte stream. This call may block for an
  * indefinite period.
  *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
  * Returns: (transfer full): the new unwrapped key or NULL if the operation
  *          failed
  **/
@@ -2314,6 +2341,8 @@ gck_session_unwrap_key_full (GckSession *self,
  *
  * Unwrap a key from a byte stream. This call will
  * return immediately and complete asynchronously.
+ *
+ * If the @attrs #GckAttributes is floating, it is consumed.
  **/
 void
 gck_session_unwrap_key_async (GckSession *self,
@@ -2418,6 +2447,8 @@ perform_derive_key (DeriveKey *args)
  * Derive a key from another key. This call may block for an
  * indefinite period.
  *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
  * Returns: (transfer full): the new derived key or NULL if the operation
  *          failed
  **/
@@ -2441,6 +2472,8 @@ gck_session_derive_key (GckSession *self, GckObject *base, gulong mech_type,
  * Derive a key from another key. This call may block for an
  * indefinite period.
  *
+ * If the @attrs #GckAttributes is floating, it is consumed.
+ *
  * Returns: (transfer full): the new derived key or NULL if the operation
  *          failed
  **/
@@ -2486,6 +2519,8 @@ gck_session_derive_key_full (GckSession *self, GckObject *base, GckMechanism *me
  *
  * Derive a key from another key. This call will
  * return immediately and complete asynchronously.
+ *
+ * If the @attrs #GckAttributes is floating, it is consumed.
  **/
 void
 gck_session_derive_key_async (GckSession *self, GckObject *base, GckMechanism *mechanism,
diff --git a/gck/gck-slot.c b/gck/gck-slot.c
index 7ad1f5a..7dd3c2a 100644
--- a/gck/gck-slot.c
+++ b/gck/gck-slot.c
@@ -888,6 +888,8 @@ gck_slot_has_flags (GckSlot *self, gulong flags)
  *
  * Setup an enumerator for listing matching objects on the slot.
  *
+ * If the @match #GckAttributes is floating, it is consumed.
+ *
  * This call will not block but will return an enumerator immediately.
  *
  * Returns: (transfer full): a new enumerator
@@ -918,6 +920,8 @@ gck_slot_enumerate_objects (GckSlot *self,
  *
  * Setup an enumerator for listing matching objects on the slots.
  *
+ * If the @match #GckAttributes is floating, it is consumed.
+ *
  * This call will not block but will return an enumerator immediately.
  *
  * Returns: (transfer full): a new enumerator
diff --git a/gck/gck.h b/gck/gck.h
index c0f67dd..3d9cc3a 100644
--- a/gck/gck.h
+++ b/gck/gck.h
@@ -1405,8 +1405,8 @@ struct _GckObjectCacheIface {
 	const gulong *  default_types;
 	gint            n_default_types;
 
-	void            (* add_attributes)                 (GckObjectCache *object,
-	                                                    GckAttributes *attributes);
+	void         (* fill)                              (GckObjectCache *object,
+	                                                    GckAttributes *attrs);
 
 	/*< private >*/
 	gpointer reserved[6];
@@ -1417,10 +1417,10 @@ GType               gck_object_cache_get_type              (void) G_GNUC_CONST;
 GckAttributes *     gck_object_cache_get_attributes        (GckObjectCache *object);
 
 void                gck_object_cache_set_attributes        (GckObjectCache *object,
-                                                            GckAttributes *attributes);
+                                                            GckAttributes *attrs);
 
-void                gck_object_cache_add_attributes        (GckObjectCache *object,
-                                                            GckAttributes *attributes);
+void                gck_object_cache_fill                  (GckObjectCache *object,
+                                                            GckAttributes *attrs);
 
 gboolean            gck_object_cache_update                (GckObjectCache *object,
                                                             const gulong *attr_types,
diff --git a/gck/gck.symbols b/gck/gck.symbols
index 6258dee..e84ae27 100644
--- a/gck/gck.symbols
+++ b/gck/gck.symbols
@@ -131,7 +131,7 @@ gck_modules_object_for_uri
 gck_modules_objects_for_uri
 gck_modules_token_for_uri
 gck_modules_tokens_for_uri
-gck_object_cache_add_attributes
+gck_object_cache_fill
 gck_object_cache_get_attributes
 gck_object_cache_get_type
 gck_object_cache_lookup
diff --git a/gck/tests/test-gck-enumerator.c b/gck/tests/test-gck-enumerator.c
index 1ed1ab5..2d5df63 100644
--- a/gck/tests/test-gck-enumerator.c
+++ b/gck/tests/test-gck-enumerator.c
@@ -480,8 +480,8 @@ mock_object_class_init (MockObjectClass *klass)
 }
 
 static void
-mock_object_add_attributes (GckObjectCache *object,
-                            GckAttributes *attrs)
+mock_object_fill (GckObjectCache *object,
+                  GckAttributes *attrs)
 {
 	GckBuilder builder = GCK_BUILDER_INIT;
 	MockObject *self = MOCK_OBJECT (object);
@@ -498,7 +498,7 @@ mock_object_cache_init (GckObjectCacheIface *iface)
 {
 	iface->default_types = mock_attribute_types;
 	iface->n_default_types = G_N_ELEMENTS (mock_attribute_types);
-	iface->add_attributes = mock_object_add_attributes;
+	iface->fill = mock_object_fill;
 }
 
 static void
diff --git a/gcr/tests/test-subject-public-key.c b/gcr/tests/test-subject-public-key.c
index bcd232c..e8273ef 100644
--- a/gcr/tests/test-subject-public-key.c
+++ b/gcr/tests/test-subject-public-key.c
@@ -471,8 +471,8 @@ mock_object_class_init (MockObjectClass *klass)
 }
 
 static void
-mock_object_add_attributes (GckObjectCache *object,
-                            GckAttributes *attrs)
+mock_object_fill (GckObjectCache *object,
+                  GckAttributes *attrs)
 {
 	GckBuilder builder = GCK_BUILDER_INIT;
 	MockObject *self = (MockObject *)object;
@@ -489,7 +489,7 @@ mock_object_cache_init (GckObjectCacheIface *iface)
 {
 	iface->default_types = NULL;
 	iface->n_default_types = 0;
-	iface->add_attributes = mock_object_add_attributes;
+	iface->fill = mock_object_fill;
 }
 
 static void
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]