Cypher_Stack/libsecret
2
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/libsecret.git synced 2024-12-22 04:38:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

More documentation clarifications

Browse Source 
* Document how the 'paths' variants of functions work
 * Add more about aliases
 * Document @properties arguments
This commit is contained in:
Stef Walter 2012-03-24 13:31:14 +01:00
parent ebb2806946
commit add0a1a55d
6 changed files with 215 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/libsecret/libsecret-docs.sgml
View File

@ -28,7 +28,6 @@
<xi:include href="xml/secret-item.xml"/>
<xi:include href="xml/secret-value.xml"/>
<xi:include href="xml/secret-prompt.xml"/>
<xi:include href="xml/secret-schema.xml"/>
<xi:include href="xml/secret-error.xml"/>
</part>

18
library/secret-collection.c
View File

@ -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()
*/

6
library/secret-item.c
View File

@ -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
*

248
library/secret-methods.c
View File

@ -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
* <literal>org.freedesktop.Secret.Collection.Label</literal>. 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 *

22
library/secret-password.c
View File

@ -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

10
library/secret-service.c
View File

@ -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 *