From add0a1a55ddab6f31059296df314dedf355caee1 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Sat, 24 Mar 2012 13:31:14 +0100 Subject: [PATCH] More documentation clarifications * Document how the 'paths' variants of functions work * Add more about aliases * Document @properties arguments --- docs/reference/libsecret/libsecret-docs.sgml | 1 - library/secret-collection.c | 18 +- library/secret-item.c | 6 +- library/secret-methods.c | 248 ++++++++++++++----- library/secret-password.c | 22 +- library/secret-service.c | 10 +- 6 files changed, 215 insertions(+), 90 deletions(-) diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml index ce974a6..8225e61 100644 --- a/docs/reference/libsecret/libsecret-docs.sgml +++ b/docs/reference/libsecret/libsecret-docs.sgml @@ -28,7 +28,6 @@ - diff --git a/library/secret-collection.c b/library/secret-collection.c index ce3354c..b52369a 100644 --- a/library/secret-collection.c +++ b/library/secret-collection.c @@ -529,7 +529,7 @@ secret_collection_class_init (SecretCollectionClass *klass) * SecretCollection:service: * * The #SecretService object that this collection is associated with and - * uses to interact with the actual DBus Secret Service. + * uses to interact with the actual D-Bus Secret Service. */ g_object_class_install_property (gobject_class, PROP_SERVICE, g_param_spec_object ("service", "Service", "Secret Service", @@ -737,7 +737,7 @@ secret_collection_async_initable_iface (GAsyncInitableIface *iface) /** * secret_collection_new: * @service: a secret service object - * @collection_path: the dbus path of the collection + * @collection_path: the D-Bus path of the collection * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback @@ -808,7 +808,7 @@ secret_collection_new_finish (GAsyncResult *result, /** * secret_collection_new_sync: * @service: a secret service object - * @collection_path: the dbus path of the collection + * @collection_path: the D-Bus path of the collection * @cancellable: optional cancellation object * @error: location to place an error on failure * @@ -951,6 +951,12 @@ collection_properties_new (const gchar *label) * This method returns immediately and completes asynchronously. The secret * service may prompt the user. secret_service_prompt() will be used to handle * any prompts that are required. + * + * An @alias is a well-known tag for a collection, such as 'default' (ie: the + * default collection to store items in). This allows other applications to + * easily identify and share a collection. If you specify an @alias, and a + * collection with that alias already exists, then a new collection will not + * be created. The previous one will be returned instead. */ void secret_collection_create (SecretService *service, @@ -1030,6 +1036,12 @@ secret_collection_create_finish (GAsyncResult *result, * threads. The secret service may prompt the user. secret_service_prompt() * will be used to handle any prompts that are required. * + * An @alias is a well-known tag for a collection, such as 'default' (ie: the + * default collection to store items in). This allows other applications to + * easily identify and share a collection. If you specify an @alias, and a + * collection with that alias already exists, then a new collection will not + * be created. The previous one will be returned instead. + * * Returns: (transfer full): the new collection, which should be unreferenced * with g_object_unref() */ diff --git a/library/secret-item.c b/library/secret-item.c index 4ad21cc..62b0d0e 100644 --- a/library/secret-item.c +++ b/library/secret-item.c @@ -277,7 +277,7 @@ secret_item_class_init (SecretItemClass *klass) * SecretItem:service: * * The #SecretService object that this item is associated with and - * uses to interact with the actual DBus Secret Service. + * uses to interact with the actual D-Bus Secret Service. */ g_object_class_install_property (gobject_class, PROP_SERVICE, g_param_spec_object ("service", "Service", "Secret Service", @@ -442,7 +442,7 @@ secret_item_async_initable_iface (GAsyncInitableIface *iface) /** * secret_item_new: * @service: a secret service object - * @item_path: the dbus path of the collection + * @item_path: the D-Bus path of the collection * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback @@ -510,7 +510,7 @@ secret_item_new_finish (GAsyncResult *result, /** * secret_item_new_sync: * @service: a secret service object - * @item_path: the dbus path of the item + * @item_path: the D-Bus path of the item * @cancellable: optional cancellation object * @error: location to place an error on failure * diff --git a/library/secret-methods.c b/library/secret-methods.c index 48f7e77..4065a81 100644 --- a/library/secret-methods.c +++ b/library/secret-methods.c @@ -49,10 +49,16 @@ on_search_items_complete (GObject *source, * @callback: called when the operation completes * @user_data: data to pass to the callback * - * Search for items matching the @attributes. All collections are searched. - * The @attributes should be a table of string keys and string values. + * Search for items matching the @attributes, and return their D-Bus object paths. + * All collections are searched. The @attributes should be a table of string keys + * and string values. * * This function returns immediately and completes asynchronously. + * + * When your callback is called use secret_service_search_for_paths_finish() + * to get the results of this function. Only the D-Bus object paths of the + * items will be returned. If you would like #SecretItem objects to be returned + * instead, then use the secret_service_search() function. */ void secret_service_search_for_paths (SecretService *self, @@ -98,18 +104,24 @@ _secret_service_search_for_paths_variant (SecretService *self, * @self: the secret service * @result: asynchronous result passed to callback * @unlocked: (out) (transfer full) (array zero-terminated=1) (allow-none): - * location to place an array of dbus object paths for matching + * location to place an array of D-Bus object paths for matching * items which were locked. * @locked: (out) (transfer full) (array zero-terminated=1) (allow-none): - * location to place an array of dbus object paths for matching + * location to place an array of D-Bus object paths for matching * items which were locked. * @error: location to place error on failure * - * Complete asynchronous operation to search for items. + * Complete asynchronous operation to search for items, and return their + * D-Bus object paths. * - * Matching items that are locked or unlocked, have their dbus paths placed + * Matching items that are locked or unlocked, have their D-Bus paths placed * in the @locked or @unlocked arrays respectively. * + * D-Bus object paths of the items will be returned in the @unlocked or + * @locked arrays. If you would to have #SecretItem objects to be returned + * instead, then us the secret_service_search() and + * secret_service_search_finish() functions. + * * Returns: whether the search was successful or not */ gboolean @@ -150,22 +162,27 @@ secret_service_search_for_paths_finish (SecretService *self, * @attributes: (element-type utf8 utf8): search for items matching these attributes * @cancellable: optional cancellation object * @unlocked: (out) (transfer full) (array zero-terminated=1) (allow-none): - * location to place an array of dbus object paths for matching + * location to place an array of D-Bus object paths for matching * items which were locked. * @locked: (out) (transfer full) (array zero-terminated=1) (allow-none): - * location to place an array of dbus object paths for matching + * location to place an array of D-Bus object paths for matching * items which were locked. * @error: location to place error on failure * - * Search for items matching the @attributes. All collections are searched. - * The @attributes should be a table of string keys and string values. + * Search for items matching the @attributes, and return their D-Bus object + * paths. All collections are searched. The @attributes should be a table of + * string keys and string values. * * This function may block indefinetely. Use the asynchronous version * in user interface threads. * - * Matching items that are locked or unlocked, have their dbus paths placed + * Matching items that are locked or unlocked, have their D-Bus paths placed * in the @locked or @unlocked arrays respectively. * + * D-Bus object paths of the items will be returned in the @unlocked or + * @locked arrays. If you would to have #SecretItem objects to be returned + * instead, then use the secret_service_search_sync() function. + * * Returns: whether the search was successful or not */ gboolean @@ -315,6 +332,11 @@ on_search_paths (GObject *source, * The @attributes should be a table of string keys and string values. * * This function returns immediately and completes asynchronously. + * + * When your callback is called use secret_service_search_finish() + * to get the results of this function. #SecretItem proxy objects will be + * returned. If you prefer to only have the items D-Bus object paths returned, + * then then use the secret_service_search_for_paths() function. */ void secret_service_search (SecretService *self, @@ -372,8 +394,12 @@ search_finish_build (gchar **paths, * * Complete asynchronous operation to search for items. * - * Matching items that are locked or unlocked are placed - * in the @locked or @unlocked lists respectively. + * Matching items that are locked or unlocked are placed in the @locked or + * @unlocked lists respectively. + * + * #SecretItem proxy objects will be returned. If you prefer to only have + * the items' D-Bus object paths returned, then then use the + * secret_service_search_for_paths() function. * * Returns: whether the search was successful or not */ @@ -453,6 +479,10 @@ service_load_items_sync (SecretService *self, * Matching items that are locked or unlocked are placed * in the @locked or @unlocked lists respectively. * + * #SecretItem proxy objects will be returned. If you prefer to only have + * the items' D-Bus object paths returned, then then use the + * secret_service_search_sync() function. + * * Returns: whether the search was successful or not */ gboolean @@ -554,13 +584,17 @@ on_get_secrets_session (GObject *source, /** * secret_service_get_secret_for_path: * @self: the secret service - * @item_path: the dbus path to item to retrieve secret for + * @item_path: the D-Bus path to item to retrieve secret for * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to pass to the callback * * Get the secret value for an secret item stored in the service. * + * The item is represented by its D-Bus object path. If you already have a + * #SecretItem proxy object, use use secret_item_get_secret() to more simply + * get its secret value. + * * This function returns immediately and completes asynchronously. */ void @@ -675,12 +709,16 @@ secret_service_get_secret_for_path_finish (SecretService *self, /** * secret_service_get_secret_for_path_sync: * @self: the secret service - * @item_path: the dbus path to item to retrieve secret for + * @item_path: the D-Bus path to item to retrieve secret for * @cancellable: optional cancellation object * @error: location to place an error on failure * * Get the secret value for an secret item stored in the service. * + * The item is represented by its D-Bus object path. If you already have a + * #SecretItem proxy object, use use secret_item_get_secret_sync() to more simply + * get its secret value. + * * This method may block indefinitely and should not be used in user interface * threads. * @@ -722,13 +760,17 @@ secret_service_get_secret_for_path_sync (SecretService *self, /** * secret_service_get_secrets_for_paths: * @self: the secret service - * @item_paths: the dbus paths to items to retrieve secrets for + * @item_paths: the D-Bus paths to items to retrieve secrets for * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to pass to the callback * * Get the secret values for an secret items stored in the service. * + * The items are represented by their D-Bus object paths. If you already have + * #SecretItem proxy objects, use use secret_service_get_secrets() to more simply + * get their secret values. + * * This function returns immediately and completes asynchronously. */ void @@ -798,12 +840,16 @@ secret_service_get_secrets_for_paths_finish (SecretService *self, /** * secret_service_get_secrets_for_paths_sync: * @self: the secret service - * @item_paths: the dbus paths to items to retrieve secrets for + * @item_paths: the D-Bus paths to items to retrieve secrets for * @cancellable: optional cancellation object * @error: location to place an error on failure * * Get the secret values for an secret items stored in the service. * + * The items are represented by their D-Bus object paths. If you already have + * #SecretItem proxy objects, use use secret_service_get_secrets_sync() to more + * simply get their secret values. + * * This method may block indefinitely and should not be used in user interface * threads. * @@ -852,6 +898,10 @@ secret_service_get_secrets_for_paths_sync (SecretService *self, * * Get the secret values for an secret items stored in the service. * + * This method takes a list of #SecretItem proxy objects. If you only have the + * D-Bus object paths of the items, use secret_service_get_secrets_for_paths() + * instead. + * * This function returns immediately and completes asynchronously. */ void @@ -962,6 +1012,10 @@ secret_service_get_secrets_finish (SecretService *self, * * Get the secret values for an secret items stored in the service. * + * This method takes a list of #SecretItem proxy objects. If you only have the + * D-Bus object paths of the items, use secret_service_get_secrets_for_paths_sync() + * instead. + * * This method may block indefinitely and should not be used in user interface * threads. * @@ -1220,6 +1274,10 @@ service_xlock_finish (SecretService *self, * * Lock items or collections in the secret service. * + * This method takes a list of #SecretItem or #SecretCollection proxy objects. + * If you only have the D-Bus object paths of the items or collections, use + * secret_service_lock_paths() instead. + * * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * @@ -1279,6 +1337,10 @@ secret_service_lock_finish (SecretService *self, * * Lock items or collections in the secret service. * + * This method takes a list of #SecretItem or #SecretCollection proxy objects. + * If you only have the D-Bus object paths of the items or collections, use + * secret_service_lock_paths_sync() instead. + * * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * @@ -1321,15 +1383,19 @@ secret_service_lock_sync (SecretService *self, /** * secret_service_lock_paths_sync: * @self: the secret service - * @paths: the dbus paths for items or collections to lock + * @paths: the D-Bus object paths of the items or collections to lock * @cancellable: optional cancellation object * @locked: (out) (array zero-terminated=1) (transfer full) (allow-none): - * location to place array of dbus paths of items or collections + * location to place array of D-Bus paths of items or collections * that were locked * @error: location to place an error on failure * * Lock items or collections in the secret service. * + * The items or collections are represented by their D-Bus object paths. If you + * already have #SecretItem and #SecretCollection proxy objects, use use + * secret_service_lock_sync() instead. + * * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * @@ -1374,13 +1440,17 @@ secret_service_lock_paths_sync (SecretService *self, /** * secret_service_lock_paths: * @self: the secret service - * @paths: the dbus paths for items or collections to lock + * @paths: the D-Bus paths for items or collections to lock * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to pass to the callback * * Lock items or collections in the secret service. * + * The items or collections are represented by their D-Bus object paths. If you + * already have #SecretItem and #SecretCollection proxy objects, use use + * secret_service_lock() instead. + * * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * @@ -1412,7 +1482,7 @@ secret_service_lock_paths (SecretService *self, * @self: the secret service * @result: asynchronous result passed to the callback * @locked: (out) (array zero-terminated=1) (transfer full) (allow-none): - * location to place array of dbus paths of items or collections + * location to place array of D-Bus paths of items or collections * that were locked * @error: location to place an error on failure * @@ -1440,15 +1510,19 @@ secret_service_lock_paths_finish (SecretService *self, /** * secret_service_unlock_paths_sync: * @self: the secret service - * @paths: the dbus paths for items or collections to unlock + * @paths: the D-Bus object paths of the items or collections to unlock * @cancellable: optional cancellation object * @unlocked: (out) (array zero-terminated=1) (transfer full) (allow-none): - * location to place array of dbus paths of items or collections + * location to place array of D-Bus paths of items or collections * that were unlocked * @error: location to place an error on failure * * Unlock items or collections in the secret service. * + * The items or collections are represented by their D-Bus object paths. If you + * already have #SecretItem and #SecretCollection proxy objects, use use + * secret_service_unlock_sync() instead. + * * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * @@ -1494,13 +1568,17 @@ secret_service_unlock_paths_sync (SecretService *self, /** * secret_service_unlock_paths: * @self: the secret service - * @paths: the dbus paths for items or collections to unlock + * @paths: the D-Bus paths for items or collections to unlock * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to pass to the callback * * Unlock items or collections in the secret service. * + * The items or collections are represented by their D-Bus object paths. If you + * already have #SecretItem and #SecretCollection proxy objects, use use + * secret_service_unlock() instead. + * * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * @@ -1533,7 +1611,7 @@ secret_service_unlock_paths (SecretService *self, * @self: the secret service * @result: asynchronous result passed to the callback * @unlocked: (out) (array zero-terminated=1) (transfer full) (allow-none): - * location to place array of dbus paths of items or collections + * location to place array of D-Bus paths of items or collections * that were unlocked * @error: location to place an error on failure * @@ -1568,6 +1646,10 @@ secret_service_unlock_paths_finish (SecretService *self, * * Unlock items or collections in the secret service. * + * This method takes a list of #SecretItem or #SecretCollection proxy objects. + * If you only have the D-Bus object paths of the items or collections, use + * secret_service_unlock_paths() instead. + * * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * @@ -1629,6 +1711,10 @@ secret_service_unlock_finish (SecretService *self, * * Unlock items or collections in the secret service. * + * This method takes a list of #SecretItem or #SecretCollection proxy objects. + * If you only have the D-Bus object paths of the items or collections, use + * secret_service_unlock_paths_sync() instead. + * * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * @@ -1672,8 +1758,8 @@ secret_service_unlock_sync (SecretService *self, /** * secret_service_store: * @self: the secret service - * @schema: the schema to for attributes - * @collection_path: (allow-none): the dbus path to the collection where to store the secret + * @schema: the schema for the attributes + * @collection_path: (allow-none): the D-Bus path to the collection where to store the secret * @label: label for the secret * @value: the secret value * @cancellable: optional cancellation object @@ -1729,9 +1815,9 @@ secret_service_store (SecretService *self, /** * secret_service_storev: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema to use to check attributes * @attributes: (element-type utf8 utf8): the attribute keys and values - * @collection_path: (allow-none): the dbus path to the collection where to store the secret + * @collection_path: (allow-none): the D-Bus path to the collection where to store the secret * @label: label for the secret * @value: the secret value * @cancellable: optional cancellation object @@ -1825,8 +1911,8 @@ secret_service_store_finish (SecretService *self, /** * secret_service_store_sync: * @self: the secret service - * @schema: the schema to for attributes - * @collection_path: (allow-none): the dbus path to the collection where to store the secret + * @schema: the schema for the attributes + * @collection_path: (allow-none): the D-Bus path to the collection where to store the secret * @label: label for the secret * @value: the secret value * @cancellable: optional cancellation object @@ -1888,9 +1974,9 @@ secret_service_store_sync (SecretService *self, /** * secret_service_storev_sync: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @attributes: (element-type utf8 utf8): the attribute keys and values - * @collection_path: (allow-none): the dbus path to the collection where to store the secret + * @collection_path: (allow-none): the D-Bus path to the collection where to store the secret * @label: label for the secret * @value: the secret value * @cancellable: optional cancellation object @@ -1971,7 +2057,7 @@ lookup_closure_free (gpointer data) /** * secret_service_lookup: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback @@ -2102,7 +2188,7 @@ on_lookup_searched (GObject *source, /** * secret_service_lookupv: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @attributes: (element-type utf8 utf8): the attribute keys and values * @cancellable: optional cancellation object * @callback: called when the operation completes @@ -2191,7 +2277,7 @@ secret_service_lookup_finish (SecretService *self, /** * secret_service_lookup_sync: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @cancellable: optional cancellation object * @error: location to place an error on failure * @...: the attribute keys and values, terminated with %NULL @@ -2240,7 +2326,7 @@ secret_service_lookup_sync (SecretService *self, /** * secret_service_lookupv_sync: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @attributes: (element-type utf8 utf8): the attribute keys and values * @cancellable: optional cancellation object * @error: location to place an error on failure @@ -2399,13 +2485,16 @@ _secret_service_delete_path (SecretService *self, /** * secret_service_delete_path: * @self: the secret service - * @item_path: dbus path of item to delete + * @item_path: the D-Bus path of item to delete * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback * * Delete a secret item from the secret service. * + * The item is represented by its D-Bus object path. If you already have a + * #SecretItem proxy objects, use use secret_item_delete() instead. + * * This method will return immediately and complete asynchronously. */ void @@ -2457,12 +2546,15 @@ secret_service_delete_path_finish (SecretService *self, /** * secret_service_delete_path_sync: * @self: the secret service - * @item_path: dbus path of item to delete + * @item_path: the D-Bus path of item to delete * @cancellable: optional cancellation object * @error: location to place an error on failure * * Delete a secret item from the secret service. * + * The item is represented by its D-Bus object path. If you already have a + * #SecretItem proxy objects, use use secret_item_delete_sync() instead. + * * This method may block indefinitely and should not be used in user interface * threads. * @@ -2567,7 +2659,7 @@ on_search_delete_password (GObject *source, /** * secret_service_remove: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback @@ -2612,7 +2704,7 @@ secret_service_remove (SecretService *self, /** * secret_service_removev: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @attributes: (element-type utf8 utf8): the attribute keys and values * @cancellable: optional cancellation object * @callback: called when the operation completes @@ -2698,7 +2790,7 @@ secret_service_remove_finish (SecretService *self, /** * secret_service_remove_sync: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @cancellable: optional cancellation object * @error: location to place an error on failure * @...: the attribute keys and values, terminated with %NULL @@ -2747,7 +2839,7 @@ secret_service_remove_sync (SecretService *self, /** * secret_service_removev_sync: * @self: the secret service - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @attributes: (element-type utf8 utf8): the attribute keys and values * @cancellable: optional cancellation object * @error: location to place an error on failure @@ -2879,25 +2971,34 @@ on_create_collection_called (GObject *source, /** * secret_service_create_collection_path: * @self: a secret service object - * @properties: hash table of properties for the new collection + * @properties: (element-type utf8 GLib.Variant): hash table of properties for + * the new collection * @alias: (allow-none): an alias to check for before creating the new * collection, or to assign to the new collection * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback * - * Create a new collection in the secret service. + * Create a new collection in the secret service, and return its path. * - * If a collection with the @alias already exists, then instead of creating a - * new collection, the existing collection will be returned. If no collection - * with this alias exists, then a new collection will be created and this - * alias will be assigned to it. + * Using this method requires that you setup a correct hash table of D-Bus + * properties for the new collection. You may prefer to use + * secret_collection_create() which does handles this for you. + * + * An @alias is a well-known tag for a collection, such as 'default' (ie: the + * default collection to store items in). This allows other applications to + * easily identify and share a collection. If a collection with the @alias + * already exists, then instead of creating a new collection, the existing + * collection will be returned. If no collection with this alias exists, then a + * new collection will be created and this alias will be assigned to it. * * @properties is a set of properties for the new collection. The keys in the * hash table should be interface.property strings like * org.freedesktop.Secret.Collection.Label. The values * in the hash table should be #GVariant values of the properties. * + * If you wish to have a + * * This method will return immediately and complete asynchronously. The secret * service may prompt the user. secret_service_prompt() will be used to handle * any prompts that are required. @@ -2956,7 +3057,7 @@ secret_service_create_collection_path (SecretService *self, * Finish asynchronous operation to create a new collection in the secret * service. * - * Returns: (transfer full): a new string containing the dbus object path + * Returns: (transfer full): a new string containing the D-Bus object path * of the collection */ gchar * @@ -2986,18 +3087,25 @@ secret_service_create_collection_path_finish (SecretService *self, /** * secret_service_create_collection_path_sync: * @self: a secret service object - * @properties: hash table of properties for the new collection + * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties + * for the new collection * @alias: (allow-none): an alias to check for before creating the new * collection, or to assign to the new collection * @cancellable: optional cancellation object * @error: location to place an error on failure * - * Create a new collection in the secret service. + * Create a new collection in the secret service and return its path. * - * If a collection with the @alias already exists, then instead of creating a - * new collection, the existing collection will be returned. If no collection - * with this alias exists, then a new collection will be created and this - * alias will be assigned to it. + * Using this method requires that you setup a correct hash table of D-Bus + * properties for the new collection. You may prefer to use + * secret_collection_create() which does handles this for you. + * + * An @alias is a well-known tag for a collection, such as 'default' (ie: the + * default collection to store items in). This allows other applications to + * easily identify and share a collection. If a collection with the @alias + * already exists, then instead of creating a new collection, the existing + * collection will be returned. If no collection with this alias exists, then + * a new collection will be created and this alias will be assigned to it. * * @properties is a set of properties for the new collection. The keys in the * hash table should be interface.property strings like @@ -3008,7 +3116,7 @@ secret_service_create_collection_path_finish (SecretService *self, * threads. The secret service may prompt the user. secret_service_prompt() * will be used to handle any prompts that are required. * - * Returns: (transfer full): a new string containing the dbus object path + * Returns: (transfer full): a new string containing the D-Bus object path * of the collection */ gchar * @@ -3169,18 +3277,21 @@ on_create_item_session (GObject *source, /** * secret_service_create_item_path: * @self: a secret service object - * @collection_path: (allow-none): dbus path to collection in which to create item - * @properties: hash table of properties for the new collection + * @collection_path: (allow-none): the D-Bus object path of the collection in which to create item + * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties + * for the new collection * @value: the secret value to store in the item * @replace: whether to replace an item with the matching attributes * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback * - * Create a new item in a secret service collection. + * Create a new item in a secret service collection and return its D-Bus + * object path. * * It is often easier to use secret_password_store() or secret_item_create() - * rather than using this function. + * rather than using this function. Using this method requires that you setup + * a correct hash table of D-Bus @properties for the new collection. * * If @replace is set to %TRUE, and an item already in the collection matches * the attributes (specified in @properties) then the item will be updated @@ -3247,7 +3358,7 @@ secret_service_create_item_path (SecretService *self, * Finish asynchronous operation to create a new item in the secret * service. * - * Returns: (transfer full): a new string containing the dbus object path + * Returns: (transfer full): a new string containing the D-Bus object path * of the item */ gchar * @@ -3277,17 +3388,20 @@ secret_service_create_item_path_finish (SecretService *self, /** * secret_service_create_item_path_sync: * @self: a secret service object - * @collection_path: (allow-none): dbus path to collection in which to create item - * @properties: hash table of properties for the new collection + * @collection_path: (allow-none): the D-Bus path of the collection in which to create item + * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties + * for the new collection * @value: the secret value to store in the item * @replace: whether to replace an item with the matching attributes * @cancellable: optional cancellation object * @error: location to place an error on failure * - * Create a new item in a secret service collection. + * Create a new item in a secret service collection and return its D-Bus + * object path. * * It is often easier to use secret_password_store_sync() or secret_item_create_sync() - * rather than using this function. + * rather than using this function. Using this method requires that you setup + * a correct hash table of D-Bus @properties for the new collection. * * If @replace is set to %TRUE, and an item already in the collection matches * the attributes (specified in @properties) then the item will be updated @@ -3302,7 +3416,7 @@ secret_service_create_item_path_finish (SecretService *self, * threads. The secret service may prompt the user. secret_service_prompt() * will be used to handle any prompts that are required. * - * Returns: (transfer full): a new string containing the dbus object path + * Returns: (transfer full): a new string containing the D-Bus object path * of the item */ gchar * diff --git a/library/secret-password.c b/library/secret-password.c index 62c80f9..bd5605c 100644 --- a/library/secret-password.c +++ b/library/secret-password.c @@ -112,7 +112,7 @@ on_store_connected (GObject *source, /** * secret_password_store: * @schema: the schema for attributes - * @collection_path: (allow-none): the dbus path to the collection where to store the secret + * @collection_path: (allow-none): the D-Bus object path of the collection where to store the secret * @label: label for the secret * @password: the null-terminated password to store * @cancellable: optional cancellation object @@ -168,7 +168,7 @@ secret_password_store (const SecretSchema *schema, * secret_password_storev: * @schema: the schema for attributes * @attributes: (element-type utf8 utf8): the attribute keys and values - * @collection_path: (allow-none): the dbus path to the collection where to store the secret + * @collection_path: (allow-none): the D-Bus object path of the collection where to store the secret * @label: label for the secret * @password: the null-terminated password to store * @cancellable: optional cancellation object @@ -262,7 +262,7 @@ secret_password_store_finish (GAsyncResult *result, /** * secret_password_store_sync: * @schema: the schema for attributes - * @collection_path: (allow-none): the dbus path to the collection where to store the secret + * @collection_path: (allow-none): the D-Bus object path of the collection where to store the secret * @label: label for the secret * @password: the null-terminated password to store * @cancellable: optional cancellation object @@ -322,7 +322,7 @@ secret_password_store_sync (const SecretSchema *schema, * secret_password_storev_sync: * @schema: the schema for attributes * @attributes: (element-type utf8 utf8): the attribute keys and values - * @collection_path: (allow-none): the dbus path to the collection where to store the secret + * @collection_path: (allow-none): the D-Bus object path of the collection where to store the secret * @label: label for the secret * @password: the null-terminated password to store * @cancellable: optional cancellation object @@ -406,7 +406,7 @@ lookup_closure_free (gpointer data) /** * secret_password_lookup: (skip) - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback @@ -622,7 +622,7 @@ secret_password_lookup_finish (GAsyncResult *result, /** * secret_password_lookup_sync: (skip) - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @cancellable: optional cancellation object * @error: location to place an error on failure * @...: the attribute keys and values, terminated with %NULL @@ -670,7 +670,7 @@ secret_password_lookup_sync (const SecretSchema *schema, /** * secret_password_lookup_nonpageable_sync: (skip) - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @cancellable: optional cancellation object * @error: location to place an error on failure * @...: the attribute keys and values, terminated with %NULL @@ -843,7 +843,7 @@ delete_closure_free (gpointer data) /** * secret_password_remove: - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @cancellable: optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback @@ -928,7 +928,7 @@ on_delete_connect (GObject *source, /** * secret_password_removev: - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @attributes: (element-type utf8 utf8): the attribute keys and values * @cancellable: optional cancellation object * @callback: called when the operation completes @@ -1007,7 +1007,7 @@ secret_password_remove_finish (GAsyncResult *result, /** * secret_password_remove_sync: - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @cancellable: optional cancellation object * @error: location to place an error on failure * @...: the attribute keys and values, terminated with %NULL @@ -1054,7 +1054,7 @@ secret_password_remove_sync (const SecretSchema* schema, /** * secret_password_removev_sync: - * @schema: the schema to for attributes + * @schema: the schema for the attributes * @attributes: (element-type utf8 utf8): the attribute keys and values * @cancellable: optional cancellation object * @error: location to place an error on failure diff --git a/library/secret-service.c b/library/secret-service.c index 50d6c6e..3085725 100644 --- a/library/secret-service.c +++ b/library/secret-service.c @@ -30,7 +30,7 @@ * @short_description: the Secret Service * * A #SecretService object represents the Secret Service implementation which - * runs as a DBus service. + * runs as a D-Bus service. * * Normally a single #SecretService object can be shared between multiple * callers. The secret_service_get() method is used to access this #SecretService @@ -812,7 +812,7 @@ secret_service_get_sync (SecretServiceFlags flags, /** * secret_service_new: - * @service_bus_name: (allow-none): dbus service name of the secret service + * @service_bus_name: (allow-none): the D-Bus service name of the secret service * @flags: flags for which service functionality to ensure is initialized * @cancellable: optional cancellation object * @callback: called when the operation completes @@ -887,7 +887,7 @@ secret_service_new_finish (GAsyncResult *result, /** * secret_service_new_sync: - * @service_bus_name: (allow-none): dbus service name of the secret service + * @service_bus_name: (allow-none): the D-Bus service name of the secret service * @flags: flags for which service functionality to ensure is initialized * @cancellable: optional cancellation object * @error: location to place an error on failure @@ -1089,13 +1089,13 @@ secret_service_get_session_algorithms (SecretService *self) * secret_service_get_session_path: * @self: the secret service proxy * - * Get the dbus object path of the session object being used to transfer + * Get the D-Bus object path of the session object being used to transfer * secrets between this secret service proxy and the Secret Service itself. * * This will be %NULL if no session has been established. Use * secret_service_ensure_session() to establish a session. * - * Returns: (allow-none): a string representing the dbus object path of the + * Returns: (allow-none): a string representing the D-Bus object path of the * session */ const gchar *