diff options
Diffstat (limited to 'libsecret/secret-paths.c')
| -rw-r--r-- | libsecret/secret-paths.c | 192 |
1 files changed, 88 insertions, 104 deletions
diff --git a/libsecret/secret-paths.c b/libsecret/secret-paths.c index 1fc3adc..f39f6c7 100644 --- a/libsecret/secret-paths.c +++ b/libsecret/secret-paths.c @@ -24,22 +24,6 @@ /** - * SECTION:secret-paths - * @title: DBus Path Related Functions - * @short_description: Secret Service functions which operate on DBus object paths - * - * These are low level functions which operate on DBus object paths of - * collections or items, instead of the #SecretCollection or #SecretItem - * objects themselves. - * - * You can use these functions if you wish to manage access to the secret - * service using the DBus API directly, and only wish to use a few calls - * in libsecret. - * - * Stability: Unstable - */ - -/** * secret_collection_new_for_dbus_path: (skip) * @service: (nullable): a secret service object * @collection_path: the D-Bus path of the collection @@ -50,8 +34,8 @@ * * Get a new collection proxy for a collection in the secret service. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get + * the default [class@Service] proxy. * * This method will return immediately and complete asynchronously. * @@ -95,7 +79,7 @@ secret_collection_new_for_dbus_path (SecretService *service, * collection in the secret service. * * Returns: (transfer full): the new collection, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretCollection * secret_collection_new_for_dbus_path_finish (GAsyncResult *result, @@ -128,8 +112,8 @@ secret_collection_new_for_dbus_path_finish (GAsyncResult *result, * * Get a new collection proxy for a collection in the secret service. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [funcService.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user interface * threads. @@ -137,7 +121,7 @@ secret_collection_new_for_dbus_path_finish (GAsyncResult *result, * Stability: Unstable * * Returns: (transfer full): the new collection, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretCollection * secret_collection_new_for_dbus_path_sync (SecretService *service, @@ -179,8 +163,8 @@ secret_collection_new_for_dbus_path_sync (SecretService *service, * * Get a new item proxy for a secret item in the secret service. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [funcService.get] will be called to get + * the default [class@Service] proxy. * * This method will return immediately and complete asynchronously. * @@ -226,7 +210,7 @@ secret_item_new_for_dbus_path (SecretService *service, * Stability: Unstable * * Returns: (transfer full): the new item, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretItem * secret_item_new_for_dbus_path_finish (GAsyncResult *result, @@ -256,8 +240,8 @@ secret_item_new_for_dbus_path_finish (GAsyncResult *result, * * Get a new item proxy for a secret item in the secret service. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [funcService.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user interface * threads. @@ -265,7 +249,7 @@ secret_item_new_for_dbus_path_finish (GAsyncResult *result, * Stability: Unstable * * Returns: (transfer full): the new item, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretItem * secret_item_new_for_dbus_path_sync (SecretService *service, @@ -332,10 +316,10 @@ on_search_items_complete (GObject *source, * * This function returns immediately and completes asynchronously. * - * When your callback is called use secret_collection_search_for_dbus_paths_finish() + * When your callback is called use [method@Collection.search_for_dbus_paths_finish] * to get the results of this function. Only the DBus object paths of the - * items will be returned. If you would like #SecretItem objects to be returned - * instead, then use the secret_collection_search() function. + * items will be returned. If you would like [class@Item] objects to be returned + * instead, then use the [method@Collection.search] function. * * Stability: Unstable */ @@ -382,13 +366,13 @@ secret_collection_search_for_dbus_paths (SecretCollection *collection, * Complete asynchronous operation to search for items in a collection. * * DBus object paths of the items will be returned. If you would to have - * #SecretItem objects to be returned instead, then use the - * secret_collection_search() and secret_collection_search_finish() functions. + * [class@Item] objects to be returned instead, then use the + * [method@Collection.search] and [method@Collection.search_finish] functions. * * Stability: Unstable * * Returns: (transfer full) (array zero-terminated=1): an array of DBus object - * paths for matching items. + * paths for matching items. */ gchar ** secret_collection_search_for_dbus_paths_finish (SecretCollection *collection, @@ -429,13 +413,13 @@ secret_collection_search_for_dbus_paths_finish (SecretCollection *collection, * in user interface threads. * * DBus object paths of the items will be returned. If you would to have - * #SecretItem objects to be returned instead, then use the - * secret_collection_search_sync() function. + * [class@Item] objects to be returned instead, then use the + * [method@Collection.search_sync] function. * * Stability: Unstable * * Returns: (transfer full) (array zero-terminated=1): an array of DBus object - * paths for matching items. + * paths for matching items. */ gchar ** secret_collection_search_for_dbus_paths_sync (SecretCollection *collection, @@ -483,10 +467,10 @@ secret_collection_search_for_dbus_paths_sync (SecretCollection *collection, * * This function returns immediately and completes asynchronously. * - * When your callback is called use secret_service_search_for_dbus_paths_finish() + * When your callback is called use [method@Service.search_for_dbus_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. + * items will be returned. If you would like [class@Item] objects to be returned + * instead, then use the [method@Service.search] function. * * Stability: Unstable */ @@ -558,9 +542,9 @@ _secret_service_search_for_paths_variant (SecretService *self, * 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. + * @locked arrays. If you would to have [class@Item] objects to be returned + * instead, then us the [method@Service.search] and + * [method@Service.search_finish] functions. * * Stability: Unstable * @@ -626,8 +610,8 @@ secret_service_search_for_dbus_paths_finish (SecretService *self, * 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. + * @locked arrays. If you would to have [class@Item] objects to be returned + * instead, then use the [method@Service.search_sync] function. * * Stability: Unstable * @@ -736,7 +720,7 @@ on_get_secrets_session (GObject *source, * Get the secret value for a 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 + * [class@Item] proxy object, use use [method@Item.get_secret] to more simply * get its secret value. * * This function returns immediately and completes asynchronously. @@ -784,7 +768,7 @@ secret_service_get_secret_for_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): the newly allocated secret value - * for the item, which should be released with secret_value_unref() + * for the item, which should be released with [method@Value.unref] */ SecretValue * secret_service_get_secret_for_dbus_path_finish (SecretService *self, @@ -818,7 +802,7 @@ secret_service_get_secret_for_dbus_path_finish (SecretService *self, * Get the secret value for a 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_load_secret_sync() to more simply + * [class@Item] proxy object, use use [method@Item.load_secret_sync] to more simply * get its secret value. * * This method may block indefinitely and should not be used in user interface @@ -829,7 +813,7 @@ secret_service_get_secret_for_dbus_path_finish (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): the newly allocated secret value - * for the item, which should be released with secret_value_unref() + * the item, which should be released with [method@Value.unref] */ SecretValue * secret_service_get_secret_for_dbus_path_sync (SecretService *self, @@ -872,7 +856,7 @@ secret_service_get_secret_for_dbus_path_sync (SecretService *self, * Get the secret values for a secret item stored in the service. * * The items are represented by their D-Bus object paths. If you already have - * #SecretItem proxy objects, use use secret_item_load_secrets() to more simply + * [class@Item] proxy objects, use use [func@Item.load_secrets] to more simply * get their secret values. * * This function returns immediately and completes asynchronously. @@ -920,8 +904,8 @@ secret_service_get_secrets_for_dbus_paths (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (element-type utf8 Secret.Value): a newly - * allocated hash table of item_path keys to #SecretValue - * values. + * allocated hash table of item_path keys to [struct@Value] + * values. */ GHashTable * secret_service_get_secrets_for_dbus_paths_finish (SecretService *self, @@ -955,7 +939,7 @@ secret_service_get_secrets_for_dbus_paths_finish (SecretService *self, * Get the secret values for a secret item stored in the service. * * The items are represented by their D-Bus object paths. If you already have - * #SecretItem proxy objects, use use secret_item_load_secrets_sync() to more + * [class@Item] proxy objects, use use [func@Item.load_secrets_sync] to more * simply get their secret values. * * This method may block indefinitely and should not be used in user interface @@ -966,8 +950,8 @@ secret_service_get_secrets_for_dbus_paths_finish (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (element-type utf8 Secret.Value): a newly - * allocated hash table of item_path keys to #SecretValue - * values. + * allocated hash table of item_path keys to [struct@Value] + * values. */ GHashTable * secret_service_get_secrets_for_dbus_paths_sync (SecretService *self, @@ -1158,15 +1142,15 @@ _secret_service_xlock_paths_finish (SecretService *self, * 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. + * already have [class@Item] and [class@Collection] proxy objects, use use + * [method@Service.lock_sync] instead. * * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * * This method may block indefinitely and should not be used in user * interface threads. The secret service may prompt the user. - * secret_service_prompt() will be used to handle any prompts that show up. + * [method@Service.prompt] will be used to handle any prompts that show up. * * Stability: Unstable * @@ -1215,14 +1199,14 @@ secret_service_lock_dbus_paths_sync (SecretService *self, * 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. + * already have [class@Item] and [class@Collection] proxy objects, use use + * [method@Service.lock] instead. * * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * * This method returns immediately and completes asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that show up. * * Stability: Unstable @@ -1288,15 +1272,15 @@ secret_service_lock_dbus_paths_finish (SecretService *self, * 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. + * already have [class@Item] and [class@Collection] proxy objects, use use + * [method@Service.unlock_sync] instead. * * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * * This method may block indefinitely and should not be used in user * interface threads. The secret service may prompt the user. - * secret_service_prompt() will be used to handle any prompts that show up. + * [method@Service.prompt] will be used to handle any prompts that show up. * * Stability: Unstable * @@ -1346,14 +1330,14 @@ secret_service_unlock_dbus_paths_sync (SecretService *self, * 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. + * already have [class@Item] and [class@Collection] proxy objects, use use + * [method@Service.unlock] instead. * * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * * This method returns immediately and completes asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that show up. * * Stability: Unstable @@ -1540,7 +1524,7 @@ _secret_service_delete_path_finish (SecretService *self, * 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. + * [class@Item] proxy objects, use use [method@Item.delete] instead. * * This method will return immediately and complete asynchronously. * @@ -1591,7 +1575,7 @@ secret_service_delete_item_dbus_path_finish (SecretService *self, * 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. + * [class@Item] proxy objects, use use [method@Item.delete_sync] instead. * * This method may block indefinitely and should not be used in user interface * threads. @@ -1716,7 +1700,7 @@ on_create_collection_called (GObject *source, * * 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. + * [func@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 @@ -1727,13 +1711,13 @@ on_create_collection_called (GObject *source, * * @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. + * `org.freedesktop.Secret.Collection.Label`. The values + * in the hash table should be [struct@GLib.Variant] 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 + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that are required. * * Stability: Unstable @@ -1794,7 +1778,7 @@ secret_service_create_collection_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full): a new string containing the D-Bus object path - * of the collection + * of the collection */ gchar * secret_service_create_collection_dbus_path_finish (SecretService *self, @@ -1832,7 +1816,7 @@ secret_service_create_collection_dbus_path_finish (SecretService *self, * * 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. + * [func@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 @@ -1843,11 +1827,11 @@ secret_service_create_collection_dbus_path_finish (SecretService *self, * * @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. + * `org.freedesktop.Secret.Collection.Label`. The values + * in the hash table should be [struct@GLib.Variant] values of the properties. * * This method may block indefinitely and should not be used in user interface - * threads. The secret service may prompt the user. secret_service_prompt() + * threads. The secret service may prompt the user. [method@Service.prompt] * will be used to handle any prompts that are required. * * Stability: Unstable @@ -2018,7 +2002,7 @@ on_create_item_session (GObject *source, * 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() + * It is often easier to use [func@password_store] or [func@Item.create] * rather than using this function. Using this method requires that you setup * a correct hash table of D-Bus @properties for the new collection. * @@ -2028,11 +2012,11 @@ on_create_item_session (GObject *source, * * @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.Item.Label</literal>. The values - * in the hash table should be #GVariant values of the properties. + * `org.freedesktop.Secret.Item.Label`. The values + * in the hash table should be [struct@GLib.Variant] values of the properties. * * This method will return immediately and complete asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that are required. * * Stability: Unstable @@ -2085,7 +2069,7 @@ secret_service_create_item_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full): a new string containing the D-Bus object path - * of the item + * of the item */ gchar * secret_service_create_item_dbus_path_finish (SecretService *self, @@ -2139,7 +2123,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result, * 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() + * It is often easier to use [func@password_store_sync] or [func@Item.create_sync] * rather than using this function. Using this method requires that you setup * a correct hash table of D-Bus @properties for the new collection. * @@ -2149,11 +2133,11 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result, * * @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.Item.Label</literal>. The values - * in the hash table should be #GVariant values of the properties. + * `org.freedesktop.Secret.Item.Label`. The values + * in the hash table should be [struct@GLib.Variant] values of the properties. * * This method may block indefinitely and should not be used in user interface - * threads. The secret service may prompt the user. secret_service_prompt() + * threads. The secret service may prompt the user. [method@Service.prompt] * will be used to handle any prompts that are required. * * Stability: Unstable @@ -2240,7 +2224,7 @@ secret_service_read_alias_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): the collection dbus object path, - * or %NULL if none assigned to the alias + * or %NULL if none assigned to the alias */ gchar * secret_service_read_alias_dbus_path_finish (SecretService *self, @@ -2449,11 +2433,11 @@ secret_service_set_alias_to_dbus_path_sync (SecretService *self, * @return_type: (nullable): the variant type of the prompt result * @error: location to place error on failure * - * Perform prompting for a #SecretPrompt. + * Perform prompting for a [class@Prompt]. * - * Override the #SecretServiceClass <literal>prompt_async</literal> virtual method + * Override the #SecretServiceClass [vfunc@Service.prompt_async] virtual method * to change the behavior of the propmting. The default behavior is to simply - * run secret_prompt_perform() on the prompt. + * run [method@Prompt.perform] on the prompt. * * Returns a variant result if the prompt was completed and not dismissed. The * type of result depends on the action the prompt is completing, and is defined @@ -2464,7 +2448,7 @@ secret_service_set_alias_to_dbus_path_sync (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): %NULL if the prompt was dismissed or an - * error occurred, a variant result if the prompt was successful + * error occurred, a variant result if the prompt was successful */ GVariant * secret_service_prompt_at_dbus_path_sync (SecretService *self, @@ -2497,14 +2481,14 @@ secret_service_prompt_at_dbus_path_sync (SecretService *self, * @callback: called when the operation completes * @user_data: data to be passed to the callback * - * Perform prompting for a #SecretPrompt. + * Perform prompting for a [class@Prompt]. * * This function is called by other parts of this library to handle prompts * for the various actions that can require prompting. * - * Override the #SecretServiceClass <literal>prompt_async</literal> virtual method + * Override the #SecretServiceClass [vfunc@Service.prompt_async] virtual method * to change the behavior of the propmting. The default behavior is to simply - * run secret_prompt_perform() on the prompt. + * run [method@Prompt.perform] on the prompt. * * Stability: Unstable */ @@ -2533,7 +2517,7 @@ secret_service_prompt_at_dbus_path (SecretService *self, * @result: the asynchronous result passed to the callback * @error: location to place an error on failure * - * Complete asynchronous operation to perform prompting for a #SecretPrompt. + * Complete asynchronous operation to perform prompting for a [class@Prompt]. * * Returns a variant result if the prompt was completed and not dismissed. The * type of result depends on the action the prompt is completing, and is defined @@ -2542,7 +2526,7 @@ secret_service_prompt_at_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): %NULL if the prompt was dismissed or an - * error occurred, a variant result if the prompt was successful + * error occurred, a variant result if the prompt was successful */ GVariant * secret_service_prompt_at_dbus_path_finish (SecretService *self, @@ -2561,12 +2545,12 @@ secret_service_prompt_at_dbus_path_finish (SecretService *self, * @service: the service * @value: the secret value * - * Encodes a #SecretValue into GVariant for use with the Secret Service - * DBus API. + * Encodes a [struct@Value] into [struct@GLib.Variant] for use with the Secret + * Service DBus API. * - * The resulting GVariant will have a <literal>(oayays)</literal> signature. + * The resulting [struct@GLib.Variant] will have a `(oayays)` signature. * - * A session must have already been established by the #SecretService. + * A session must have already been established by the [class@Service]. * * Returns: (transfer floating): the encoded secret */ @@ -2590,12 +2574,12 @@ secret_service_encode_dbus_secret (SecretService *service, * @service: the service * @value: the encoded secret * - * Decode a #SecretValue into GVariant received with the Secret Service + * Decode a [struct@Value] into [struct@GLib.Variant] received with the Secret Service * DBus API. * - * The GVariant should have a <literal>(oayays)</literal> signature. + * The [struct@GLib.Variant] should have a `(oayays)` signature. * - * A session must have already been established by the #SecretService, and + * A session must have already been established by the [class@Service], and * the encoded secret must be valid for that session. * * Returns: (transfer full): the decoded secret value |