diff options
Diffstat (limited to 'libsecret')
| -rw-r--r-- | libsecret/secret-attributes.c | 17 | ||||
| -rw-r--r-- | libsecret/secret-backend.c | 24 | ||||
| -rw-r--r-- | libsecret/secret-collection.c | 142 | ||||
| -rw-r--r-- | libsecret/secret-item.c | 80 | ||||
| -rw-r--r-- | libsecret/secret-methods.c | 86 | ||||
| -rw-r--r-- | libsecret/secret-password.c | 99 | ||||
| -rw-r--r-- | libsecret/secret-paths.c | 192 | ||||
| -rw-r--r-- | libsecret/secret-prompt.c | 48 | ||||
| -rw-r--r-- | libsecret/secret-retrievable.c | 40 | ||||
| -rw-r--r-- | libsecret/secret-schema.c | 90 | ||||
| -rw-r--r-- | libsecret/secret-schemas.c | 44 | ||||
| -rw-r--r-- | libsecret/secret-schemas.h | 61 | ||||
| -rw-r--r-- | libsecret/secret-service.c | 121 | ||||
| -rw-r--r-- | libsecret/secret-util.c | 6 | ||||
| -rw-r--r-- | libsecret/secret-value.c | 32 | ||||
| -rw-r--r-- | libsecret/secret-version.h.in | 8 |
16 files changed, 471 insertions, 619 deletions
diff --git a/libsecret/secret-attributes.c b/libsecret/secret-attributes.c index be3597a..603ef7a 100644 --- a/libsecret/secret-attributes.c +++ b/libsecret/secret-attributes.c @@ -19,19 +19,6 @@ #include <string.h> -/** - * SECTION:secret-attributes - * @title: Secret Attributes - * @short_description: secret attributes - * - * Each item has a set of attributes, which are used to locate the item later. - * These are not stored or transferred in a secure manner. Each attribute has - * a string name and a string value. These attributes are represented by a - * #GHashTable with string keys and values. - * - * Use secret_attributes_build() to simply build up a set of attributes. - */ - GVariant * _secret_attributes_to_variant (GHashTable *attributes, const gchar *schema_name) @@ -87,7 +74,7 @@ _secret_attributes_for_variant (GVariant *variant) * @schema. The list of attributes should be terminated with a %NULL. * * Returns: (transfer full) (element-type utf8 utf8): a new table of - * attributes, to be released with g_hash_table_unref() + * attributes, to be released with [func@GLib.HashTable.unref] */ GHashTable * secret_attributes_build (const SecretSchema *schema, @@ -116,7 +103,7 @@ secret_attributes_build (const SecretSchema *schema, * @schema. The list of attributes should be terminated with a %NULL. * * Returns: (transfer full) (element-type utf8 utf8): a new table of - * attributes, to be released with g_hash_table_unref() + * attributes, to be released with [func@GLib.HashTable.unref] */ GHashTable * secret_attributes_buildv (const SecretSchema *schema, diff --git a/libsecret/secret-backend.c b/libsecret/secret-backend.c index 73f0fd7..c527f82 100644 --- a/libsecret/secret-backend.c +++ b/libsecret/secret-backend.c @@ -25,9 +25,9 @@ #include "libsecret/secret-enum-types.h" /** - * SECTION:secret-backend - * @title: SecretBackend - * @short_description: A backend implementation of password storage + * SecretBackend + * + * A backend implementation of password storage * * #SecretBackend represents a backend implementation of password * storage. @@ -48,14 +48,14 @@ * @parent_iface: the parent interface * @ensure_for_flags: implementation of reinitialization step in constructor, optional * @ensure_for_flags_finish: implementation of reinitialization step in constructor, optional - * @store: implementation of secret_password_store(), required - * @store_finish: implementation of secret_password_store_finish(), required - * @lookup: implementation of secret_password_lookup(), required - * @lookup_finish: implementation of secret_password_lookup_finish(), required - * @clear: implementation of secret_password_clear(), required - * @clear_finish: implementation of secret_password_clear_finish(), required - * @search: implementation of secret_password_search(), required - * @search_finish: implementation of secret_password_search_finish(), required + * @store: implementation of [func@password_store], required + * @store_finish: implementation of [func@password_store_finish], required + * @lookup: implementation of [func@password_lookup], required + * @lookup_finish: implementation of [func@password_lookup_finish], required + * @clear: implementation of [func@password_clear], required + * @clear_finish: implementation of [func@password_clear_finish], required + * @search: implementation of [func@password_search], required + * @search_finish: implementation of [func@password_search_finish], required * * The interface for #SecretBackend. * @@ -264,7 +264,7 @@ secret_backend_get (SecretBackendFlags flags, * Complete an asynchronous operation to get a #SecretBackend. * * Returns: (transfer full): a new reference to a #SecretBackend proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. * * Since: 0.19.0 */ diff --git a/libsecret/secret-collection.c b/libsecret/secret-collection.c index 5e3378d..9f426b7 100644 --- a/libsecret/secret-collection.c +++ b/libsecret/secret-collection.c @@ -27,30 +27,25 @@ #include <glib/gi18n-lib.h> /** - * SECTION:secret-collection - * @title: SecretCollection - * @short_description: A collection of secret items + * SecretCollection: + * + * A proxy object representing a collection of secrets in the Secret Service. * * #SecretCollection represents a collection of secret items stored in the * Secret Service. * - * A collection can be in a locked or unlocked state. Use secret_service_lock() - * or secret_service_unlock() to lock or unlock the collection. + * A collection can be in a locked or unlocked state. Use + * [method@SecretService.lock] or [method@SecretService.unlock] to lock or + * unlock the collection. * - * Use the SecretCollection::items property or secret_collection_get_items() to - * lookup the items in the collection. There may not be any items exposed when - * the collection is locked. + * Use the [property@SecretCollection:items] property or + * [method@SecretCollection.get_items] to lookup the items in the collection. + * There may not be any items exposed when the collection is locked. * * Stability: Stable */ /** - * SecretCollection: - * - * A proxy object representing a collection of secrets in the Secret Service. - */ - -/** * SecretCollectionClass: * @parent_class: the parent class * @@ -69,22 +64,22 @@ * SecretCollectionCreateFlags: * @SECRET_COLLECTION_CREATE_NONE: no flags * - * Flags for secret_collection_create(). + * Flags for [func@Collection.create]. */ /** * SECRET_COLLECTION_DEFAULT: * - * An alias to the default collection. This can be passed to secret_password_store() - * secret_collection_for_alias(). + * An alias to the default collection. This can be passed to + * [func@password_store] [func@Collection.for_alias]. */ /** * SECRET_COLLECTION_SESSION: * * An alias to the session collection, which will be cleared when the user ends - * the session. This can be passed to secret_password_store(), - * secret_collection_for_alias() or similar functions. + * the session. This can be passed to [func@password_store], + * [func@Collection.for_alias] or similar functions. */ enum { @@ -429,9 +424,9 @@ secret_collection_class_init (SecretCollectionClass *klass) proxy_class->g_signal = secret_collection_signal; /** - * SecretCollection:service: + * SecretCollection:service: (attributes org.gtk.Property.get=secret_collection_get_service) * - * The #SecretService object that this collection is associated with and + * The [class@Service] object that this collection is associated with and * uses to interact with the actual D-Bus Secret Service. */ g_object_class_install_property (gobject_class, PROP_SERVICE, @@ -439,7 +434,7 @@ secret_collection_class_init (SecretCollectionClass *klass) SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:flags: + * SecretCollection:flags: (attributes org.gtk.Property.get=secret_collection_get_flags) * * A set of flags describing which parts of the secret collection have * been initialized. @@ -450,9 +445,9 @@ secret_collection_class_init (SecretCollectionClass *klass) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:items: + * SecretCollection:items: (attributes org.gtk.Property.get=secret_collection_get_items) * - * A list of #SecretItem objects representing the items that are in + * A list of [class@Item] objects representing the items that are in * this collection. This list will be empty if the collection is locked. */ g_object_class_install_property (gobject_class, PROP_ITEMS, @@ -460,32 +455,32 @@ secret_collection_class_init (SecretCollectionClass *klass) _secret_list_get_type (), G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:label: + * SecretCollection:label: (attributes org.gtk.Property.get=secret_collection_get_label org.gtk.Property.set=secret_collection_set_label) * * The human readable label for the collection. * * Setting this property will result in the label of the collection being * set asynchronously. To properly track the changing of the label use the - * secret_collection_set_label() function. + * [method@Collection.set_label] function. */ g_object_class_install_property (gobject_class, PROP_LABEL, g_param_spec_string ("label", "Label", "Item label", NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:locked: + * SecretCollection:locked: (attributes org.gtk.Property.get=secret_collection_get_locked) * * Whether the collection is locked or not. * - * To lock or unlock a collection use the secret_service_lock() or - * secret_service_unlock() functions. + * To lock or unlock a collection use the [method@Service.lock] or + * [method@Service.unlock] functions. */ g_object_class_install_property (gobject_class, PROP_LOCKED, g_param_spec_boolean ("locked", "Locked", "Item locked", TRUE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:created: + * SecretCollection:created: (attributes org.gtk.Property.get=secret_collection_get_created) * * The date and time (in seconds since the UNIX epoch) that this * collection was created. @@ -495,7 +490,7 @@ secret_collection_class_init (SecretCollectionClass *klass) 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:modified: + * SecretCollection:modified: (attributes org.gtk.Property.get=secret_collection_get_modified) * * The date and time (in seconds since the UNIX epoch) that this * collection was last modified. @@ -765,10 +760,10 @@ on_load_item (GObject *source, * * Ensure that the #SecretCollection proxy has loaded all the items present * in the Secret Service. This affects the result of - * secret_collection_get_items(). + * [method@Collection.get_items]. * - * For collections returned from secret_service_get_collections() the items - * will have already been loaded. + * For collections returned from [method@Service.get_collections] the items will + * have already been loaded. * * This method will return immediately and complete asynchronously. */ @@ -859,9 +854,9 @@ secret_collection_load_items_finish (SecretCollection *self, * * Ensure that the #SecretCollection proxy has loaded all the items present * in the Secret Service. This affects the result of - * secret_collection_get_items(). + * [method@Collection.get_items]. * - * For collections returned from secret_service_get_collections() the items + * For collections returned from [method@Service.get_collections] the items * will have already been loaded. * * This method may block indefinitely and should not be used in user interface @@ -1050,7 +1045,7 @@ _secret_collection_properties_new (const gchar *label) * Create a new collection in the secret service. * * 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 are required. * * An @alias is a well-known tag for a collection, such as 'default' (ie: the @@ -1059,8 +1054,8 @@ _secret_collection_properties_new (const gchar *label) * collection with that alias already exists, then a new collection will not * be created. The previous one will be returned instead. * - * 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. */ void secret_collection_create (SecretService *service, @@ -1108,7 +1103,7 @@ secret_collection_create (SecretService *service, * Finish operation to create a new 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_create_finish (GAsyncResult *result, @@ -1140,20 +1135,20 @@ secret_collection_create_finish (GAsyncResult *result, * Create a new collection in the secret service. * * 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. * - * An @alias is a well-known tag for a collection, such as 'default' (ie: the + * 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. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get the + * default [class@Service] proxy. * * Returns: (transfer full): the new collection, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretCollection * secret_collection_create_sync (SecretService *service, @@ -1395,7 +1390,7 @@ on_search_paths (GObject *source, * search and be returned. If the unlock fails, the search does not fail. * * If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have - * their secret values loaded and available via secret_item_get_secret(). + * their secret values loaded and available via [method@Item.get_secret]. * * This function returns immediately and completes asynchronously. */ @@ -1443,7 +1438,7 @@ secret_collection_search (SecretCollection *self, * Complete asynchronous operation to search for items in a collection. * * Returns: (transfer full) (element-type Secret.Item): - * a list of items that matched the search + * a list of items that matched the search */ GList * secret_collection_search_finish (SecretCollection *self, @@ -1526,13 +1521,13 @@ collection_load_items_sync (SecretCollection *self, * search and be returned. If the unlock fails, the search does not fail. * * If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have - * their secret values loaded and available via secret_item_get_secret(). + * their secret values loaded and available via [method@Item.get_secret]. * * This function may block indefinitely. Use the asynchronous version * in user interface threads. * * Returns: (transfer full) (element-type Secret.Item): - * a list of items that matched the search + * a list of items that matched the search */ GList * secret_collection_search_sync (SecretCollection *self, @@ -1610,7 +1605,7 @@ on_service_delete_path (GObject *source, * Delete this collection. * * 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. */ void @@ -1671,9 +1666,9 @@ secret_collection_delete_finish (SecretCollection *self, * * Delete this collection. * - * 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. + * This method may block indefinitely and should not be used in user interface + * threads. The secret service may prompt the user. [method@Service.prompt] will + * be used to handle any prompts that show up. * * Returns: whether the collection was successfully deleted or not */ @@ -1705,7 +1700,7 @@ secret_collection_delete_sync (SecretCollection *self, } /** - * secret_collection_get_service: + * secret_collection_get_service: (attributes org.gtk.Method.get_property=service) * @self: a collection * * Get the Secret Service object that this collection was created with. @@ -1720,14 +1715,14 @@ secret_collection_get_service (SecretCollection *self) } /** - * secret_collection_get_flags: + * secret_collection_get_flags: (attributes org.gtk.Method.get_property=flags) * @self: the secret collection proxy * * Get the flags representing what features of the #SecretCollection proxy * have been initialized. * - * Use secret_collection_load_items() to initialize further features - * and change the flags. + * Use [method@Collection.load_items] to initialize further features and change + * the flags. * * Returns: the flags for features initialized */ @@ -1749,14 +1744,14 @@ secret_collection_get_flags (SecretCollection *self) } /** - * secret_collection_get_items: + * secret_collection_get_items: (attributes org.gtk.Method.get_property=items) * @self: a collection * * Get the list of items in this collection. * - * Returns: (transfer full) (element-type Secret.Item): a list of items, - * when done, the list should be freed with g_list_free, and each item should - * be released with g_object_unref() + * Returns: (transfer full) (element-type Secret.Item): a list of items, when + * done, the list should be freed with [func@GLib.List.free], and each item + * should be released with [method@GObject.Object.unref] */ GList * secret_collection_get_items (SecretCollection *self) @@ -1792,12 +1787,13 @@ _secret_collection_find_item_instance (SecretCollection *self, } /** - * secret_collection_get_label: + * secret_collection_get_label: (attributes org.gtk.Method.get_property=label) * @self: a collection * * Get the label of this collection. * - * Returns: (transfer full): the label, which should be freed with g_free() + * Returns: (transfer full): the label, which should be freed with + * [func@GLib.free] */ gchar * secret_collection_get_label (SecretCollection *self) @@ -1817,7 +1813,7 @@ secret_collection_get_label (SecretCollection *self) } /** - * secret_collection_set_label: + * secret_collection_set_label: (attributes org.gtk.Method.set_property=label) * @self: a collection * @label: a new label * @cancellable: (nullable): optional cancellation object @@ -1895,12 +1891,12 @@ secret_collection_set_label_sync (SecretCollection *self, } /** - * secret_collection_get_locked: + * secret_collection_get_locked: (attributes org.gtk.Method.get_property=locked) * @self: a collection * * Get whether the collection is locked or not. * - * Use secret_service_lock() or secret_service_unlock() to lock or unlock the + * Use [method@Service.lock] or [method@Service.unlock] to lock or unlock the * collection. * * Returns: whether the collection is locked or not @@ -1923,7 +1919,7 @@ secret_collection_get_locked (SecretCollection *self) } /** - * secret_collection_get_created: + * secret_collection_get_created: (attributes org.gtk.Method.get_property=created) * @self: a collection * * Get the created date and time of the collection. The return value is @@ -1949,7 +1945,7 @@ secret_collection_get_created (SecretCollection *self) } /** - * secret_collection_get_modified: + * secret_collection_get_modified: (attributes org.gtk.Method.get_property=modified) * @self: a collection * * Get the modified date and time of the collection. The return value is @@ -2091,8 +2087,8 @@ on_read_alias_service (GObject *source, * Lookup which collection is assigned to this alias. Aliases help determine * well known collections, such as 'default'. * - * 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. */ @@ -2167,10 +2163,10 @@ secret_collection_for_alias_finish (GAsyncResult *result, * @error: location to place error on failure * * Lookup which collection is assigned to this alias. Aliases help determine - * well known collections, such as 'default'. + * well known collections, such as `default`. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get the + * default [class@Service] proxy. * * This method may block and should not be used in user interface threads. * diff --git a/libsecret/secret-item.c b/libsecret/secret-item.c index efab923..3c4ddb6 100644 --- a/libsecret/secret-item.c +++ b/libsecret/secret-item.c @@ -29,39 +29,33 @@ #include <glib/gi18n-lib.h> /** - * SECTION:secret-item - * @title: SecretItem - * @short_description: A secret item + * SecretItem: + * + * A secret item * * #SecretItem represents a secret item stored in the Secret Service. * - * Each item has a value, represented by a #SecretValue, which can be - * retrieved by secret_item_get_secret() or set by secret_item_set_secret(). + * Each item has a value, represented by a [struct@Value], which can be + * retrieved by [method@Item.get_secret] or set by [method@Item.set_secret]. * The item is only available when the item is not locked. * - * Items can be locked or unlocked using the secret_service_lock() or - * secret_service_unlock() functions. The Secret Service may not be able to + * Items can be locked or unlocked using the [method@Service.lock] or + * [method@Service.unlock] functions. The Secret Service may not be able to * unlock individual items, and may unlock an entire collection when a single * item is unlocked. * * Each item has a set of attributes, which are used to locate the item later. * These are not stored or transferred in a secure manner. Each attribute has - * a string name and a string value. Use secret_service_search() to search for - * items based on their attributes, and secret_item_set_attributes() to change + * a string name and a string value. Use [method@Service.search] to search for + * items based on their attributes, and [method@Item.set_attributes] to change * the attributes associated with an item. * - * Items can be created with secret_item_create() or secret_service_store(). + * Items can be created with [func@Item.create] or [method@Service.store]. * * Stability: Stable */ /** - * SecretItem: - * - * A proxy object representing a secret item in the Secret Service. - */ - -/** * SecretItemClass: * @parent_class: the parent class * @@ -81,7 +75,7 @@ * @SECRET_ITEM_CREATE_NONE: no flags * @SECRET_ITEM_CREATE_REPLACE: replace an item with the same attributes. * - * Flags for secret_item_create(). + * Flags for [func@Item.create]. */ enum { @@ -335,9 +329,9 @@ secret_item_class_init (SecretItemClass *klass) proxy_class->g_properties_changed = secret_item_properties_changed; /** - * SecretItem:service: + * SecretItem:service: (attributes org.gtk.Property.get=secret_item_get_service) * - * The #SecretService object that this item is associated with and + * The [class@Service] object that this item is associated with and * uses to interact with the actual D-Bus Secret Service. */ g_object_class_install_property (gobject_class, PROP_SERVICE, @@ -345,7 +339,7 @@ secret_item_class_init (SecretItemClass *klass) SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); /** - * SecretItem:flags: + * SecretItem:flags: (attributes org.gtk.Property.get=secret_item_get_flags) * * A set of flags describing which parts of the secret item have * been initialized. @@ -370,18 +364,18 @@ secret_item_class_init (SecretItemClass *klass) * * Setting this property will result in the label of the item being * set asynchronously. To properly track the changing of the label use the - * secret_item_set_label() function. + * [method@Item.set_label] function. */ g_object_class_override_property (gobject_class, PROP_LABEL, "label"); /** - * SecretItem:locked: + * SecretItem:locked: (attributes org.gtk.Property.get=secret_item_get_locked) * * Whether the item is locked or not. An item may not be independently * lockable separate from other items in its collection. * - * To lock or unlock a item use the secret_service_lock() or - * secret_service_unlock() functions. + * To lock or unlock a item use the [method@Service.lock] or + * [method@Service.unlock] functions. */ g_object_class_install_property (gobject_class, PROP_LOCKED, g_param_spec_boolean ("locked", "Locked", "Item locked", @@ -734,7 +728,7 @@ item_properties_new (const gchar *label, * instead of creating a new one. * * 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. */ void @@ -790,7 +784,7 @@ secret_item_create (SecretCollection *collection, * Finish operation to create a new item in the secret service. * * Returns: (transfer full): the new item, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretItem * secret_item_create_finish (GAsyncResult *result, @@ -828,11 +822,11 @@ secret_item_create_finish (GAsyncResult *result, * instead of creating a new one. * * 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. * * Returns: (transfer full): the new item, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretItem * secret_item_create_sync (SecretCollection *collection, @@ -908,7 +902,7 @@ on_item_deleted (GObject *source, * Delete this item. * * 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. */ void @@ -971,7 +965,7 @@ secret_item_delete_finish (SecretItem *self, * * 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. * * Returns: whether the item was successfully deleted or not */ @@ -1003,13 +997,13 @@ secret_item_delete_sync (SecretItem *self, } /** - * secret_item_get_flags: + * secret_item_get_flags: (attributes org.gtk.Method.get_property=flags) * @self: the secret item proxy * * Get the flags representing what features of the #SecretItem proxy * have been initialized. * - * Use secret_item_load_secret() to initialize further features + * Use [method@Item.load_secret] to initialize further features * and change the flags. * * Returns: the flags for features initialized @@ -1033,7 +1027,7 @@ secret_item_get_flags (SecretItem *self) } /** - * secret_item_get_service: + * secret_item_get_service: (attributes org.gtk.Method.get_property=service) * @self: an item * * Get the Secret Service object that this item was created with. @@ -1055,10 +1049,10 @@ secret_item_get_service (SecretItem *self) * Get the secret value of this item. If this item is locked or the secret * has not yet been loaded then this will return %NULL. * - * To load the secret call the secret_item_load_secret() method. + * To load the secret call the [method@Item.load_secret] method. * * Returns: (transfer full) (nullable): the secret value which should be - * released with secret_value_unref(), or %NULL + * released with [method@Value.unref], or %NULL */ SecretValue * secret_item_get_secret (SecretItem *self) @@ -1189,7 +1183,7 @@ secret_item_load_secret (SecretItem *self, * Complete asynchronous operation to load the secret value of this item. * * The newly loaded secret value can be accessed by calling - * secret_item_get_secret(). + * [method@Item.get_secret]. * * Returns: whether the secret item successfully loaded or not */ @@ -1394,7 +1388,7 @@ on_loads_secrets_session (GObject *source, * * Load the secret values for a secret item stored in the service. * - * The @items must all have the same SecretItem::service property. + * The @items must all have the same [property@Item:service] property. * * This function returns immediately and completes asynchronously. */ @@ -1488,7 +1482,7 @@ secret_item_load_secrets_finish (GAsyncResult *result, * * Load the secret values for a secret item stored in the service. * - * The @items must all have the same SecretItem::service property. + * The @items must all have the same [property@Item:service] property. * * This method may block indefinitely and should not be used in user interface * threads. @@ -1698,7 +1692,7 @@ secret_item_set_secret_sync (SecretItem *self, * @self: an item * * Gets the name of the schema that this item was stored with. This is also - * available at the <literal>xdg:schema</literal> attribute. + * available at the `xdg:schema` attribute. * * Returns: (nullable) (transfer full): the schema name */ @@ -1730,11 +1724,11 @@ secret_item_get_schema_name (SecretItem *self) * or transferred securely by the secret service. * * Do not modify the attributes returned by this method. Use - * secret_item_set_attributes() instead. + * [method@Item.set_attributes] instead. * * Returns: (transfer full) (element-type utf8 utf8): a new reference - * to the attributes, which should not be modified, and - * released with g_hash_table_unref() + * to the attributes, which should not be modified, and + * released with [func@GLib.HashTable.unref] */ GHashTable * secret_item_get_attributes (SecretItem *self) @@ -1865,7 +1859,7 @@ secret_item_set_attributes_sync (SecretItem *self, * * Get the label of this item. * - * Returns: (transfer full): the label, which should be freed with g_free() + * Returns: (transfer full): the label, which should be freed with [func@GLib.free] */ gchar * secret_item_get_label (SecretItem *self) diff --git a/libsecret/secret-methods.c b/libsecret/secret-methods.c index b9b696e..1101c38 100644 --- a/libsecret/secret-methods.c +++ b/libsecret/secret-methods.c @@ -33,7 +33,7 @@ * @SECRET_SEARCH_UNLOCK: unlock locked items while searching * @SECRET_SEARCH_LOAD_SECRETS: while searching load secrets for items that are not locked * - * Various flags to be used with secret_service_search() and secret_service_search_sync(). + * Various flags to be used with [method@Service.search] and [method@Service.search_sync]. */ typedef struct { @@ -273,8 +273,8 @@ on_search_service (GObject *source, * Search for items matching the @attributes. All collections are searched. * The @attributes should be a table of string keys and string values. * - * 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. * * If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the * search will be returned. Otherwise only the first item will be returned. @@ -285,7 +285,7 @@ on_search_service (GObject *source, * search and be returned. If the unlock fails, the search does not fail. * * If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have - * their secret values loaded and available via secret_item_get_secret(). + * their secret values loaded and available via [method@Item.get_secret]. * * This function returns immediately and completes asynchronously. */ @@ -345,7 +345,7 @@ secret_service_search (SecretService *service, * Complete asynchronous operation to search for items. * * Returns: (transfer full) (element-type Secret.Item): - * a list of items that matched the search + * a list of items that matched the search */ GList * secret_service_search_finish (SecretService *service, @@ -413,8 +413,8 @@ service_load_items_sync (SecretService *service, * Search for items matching the @attributes. All collections are searched. * The @attributes should be a table of string keys and string values. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get + * the default [class@Service] proxy. * * If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the * search will be returned. Otherwise only the first item will be returned. @@ -426,14 +426,14 @@ service_load_items_sync (SecretService *service, * * If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items' secret * values will be loaded for any unlocked items. Loaded item secret values - * are available via secret_item_get_secret(). If the load of a secret values + * are available via [method@Item.get_secret]. If the load of a secret values * fail, then the * * This function may block indefinitely. Use the asynchronous version * in user interface threads. * * Returns: (transfer full) (element-type Secret.Item): - * a list of items that matched the search + * a list of items that matched the search */ GList * secret_service_search_sync (SecretService *service, @@ -735,11 +735,11 @@ service_xlock_finish (SecretService *service, * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * - * 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 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. */ void @@ -797,12 +797,12 @@ secret_service_lock_finish (SecretService *service, * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.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. 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. * * Returns: the number of items or collections that were locked */ @@ -849,12 +849,12 @@ secret_service_lock_sync (SecretService *service, * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * - * 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 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. */ void secret_service_unlock (SecretService *service, @@ -911,12 +911,12 @@ secret_service_unlock_finish (SecretService *service, * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.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. 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. * * Returns: the number of items or collections that were unlocked */ @@ -1131,11 +1131,11 @@ on_store_service (GObject *source, * If the attributes match a secret item already stored in the collection, then * the item will be updated with these new values. * - * 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. * * If @collection is not specified, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method will return immediately and complete asynchronously. @@ -1251,11 +1251,11 @@ secret_service_store_finish (SecretService *service, * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.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. @@ -1427,8 +1427,8 @@ on_lookup_service (GObject *source, * * The @attributes should be a set of key and value string pairs. * - * 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. */ @@ -1485,8 +1485,8 @@ secret_service_lookup (SecretService *service, * * If no secret is found then %NULL is returned. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found */ SecretValue * secret_service_lookup_finish (SecretService *service, @@ -1520,14 +1520,14 @@ secret_service_lookup_finish (SecretService *service, * * The @attributes should be a set of key and value string pairs. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.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. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found */ SecretValue * secret_service_lookup_sync (SecretService *service, @@ -1674,8 +1674,8 @@ on_delete_service (GObject *source, * * The @attributes should be a set of key and value string pairs. * - * 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. */ @@ -1765,8 +1765,8 @@ secret_service_clear_finish (SecretService *service, * * The @attributes should be a set of key and value string pairs. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.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. @@ -1878,8 +1878,8 @@ on_set_alias_service (GObject *source, * Assign a collection to this alias. Aliases help determine * well known collections, such as 'default'. * - * 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. */ @@ -1967,8 +1967,8 @@ secret_service_set_alias_finish (SecretService *service, * Assign a collection to this alias. Aliases help determine * well known collections, such as 'default'. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block and should not be used in user interface threads. * diff --git a/libsecret/secret-password.c b/libsecret/secret-password.c index 30c5352..deabdf3 100644 --- a/libsecret/secret-password.c +++ b/libsecret/secret-password.c @@ -24,27 +24,6 @@ #include <egg/egg-secure-memory.h> /** - * SECTION:secret-password - * @title: Password storage - * @short_description: Simple password storage and lookup - * - * This is a simple API for storing passwords and retrieving passwords in the - * Secret Service. - * - * Each password is associated with a set of attributes. Attribute values can - * be either strings, integers or booleans. - * - * The names and types of allowed attributes for a given password are defined - * with a schema. Certain schemas are predefined. Additional schemas can be - * defined via the %SecretSchema structure. - * - * Each of the functions accept a variable list of attributes names and their - * values. Include a %NULL to terminate the list of attributes. - * - * Stability: Stable - */ - -/** * secret_password_store: (skip) * @schema: the schema for attributes * @collection: (nullable): a collection alias, or D-Bus object path of the @@ -67,7 +46,7 @@ * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method will return immediately and complete asynchronously. @@ -195,7 +174,7 @@ on_store_backend (GObject *source, * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method will return immediately and complete asynchronously. @@ -240,9 +219,9 @@ secret_password_storev (const SecretSchema *schema, * secret_password_store_binary: (skip) * @schema: the schema for attributes * @collection: (nullable): a collection alias, or D-Bus object path of the - * collection where to store the secret + * collection where to store the secret * @label: label for the secret - * @value: a #SecretValue + * @value: a [struct@Value] * @cancellable: (nullable): optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback @@ -250,8 +229,8 @@ secret_password_storev (const SecretSchema *schema, * * Store a password in the secret service. * - * This is similar to secret_password_store(), but takes a - * #SecretValue as the argument instead of a null-terminated password. + * This is similar to [func@password_store], but takes a + * [struct@Value] as the argument instead of a null-terminated password. * * This method will return immediately and complete asynchronously. * @@ -296,15 +275,15 @@ secret_password_store_binary (const SecretSchema *schema, * @collection: (nullable): a collection alias, or D-Bus object path of the * collection where to store the secret * @label: label for the secret - * @value: a #SecretValue + * @value: a [struct@Value] * @cancellable: (nullable): optional cancellation object * @callback: (scope async): called when the operation completes * @user_data: data to be passed to the callback * * Store a password in the secret service. * - * This is similar to secret_password_storev(), but takes a - * #SecretValue as the argument instead of a null-terminated password. + * This is similar to [func@password_storev], but takes a + * [struct@Value] as the argument instead of a null-terminated password. * * This method will return immediately and complete asynchronously. * @@ -387,7 +366,7 @@ secret_password_store_finish (GAsyncResult *result, * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method may block indefinitely and should not be used in user interface @@ -448,7 +427,7 @@ secret_password_store_sync (const SecretSchema *schema, * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method may block indefinitely and should not be used in user interface @@ -500,15 +479,15 @@ secret_password_storev_sync (const SecretSchema *schema, * @collection: (nullable): a collection alias, or D-Bus object path of the * collection where to store the secret * @label: label for the secret - * @value: a #SecretValue + * @value: a [struct@Value] * @cancellable: (nullable): optional cancellation object * @error: location to place an error on failure * @...: the attribute keys and values, terminated with %NULL * * Store a password in the secret service. * - * This is similar to secret_password_store_sync(), but takes a - * #SecretValue as the argument instead of a null terminated password. + * This is similar to [func@password_store_sync], but takes a + * [struct@Value] as the argument instead of a null terminated password. * * This method may block indefinitely and should not be used in user interface * threads. @@ -558,14 +537,14 @@ secret_password_store_binary_sync (const SecretSchema *schema, * @collection: (nullable): a collection alias, or D-Bus object path of the * collection where to store the secret * @label: label for the secret - * @value: a #SecretValue + * @value: a [struct@Value] * @cancellable: (nullable): optional cancellation object * @error: location to place an error on failure * * Store a password in the secret service. * - * This is similar to secret_password_storev_sync(), but takes a - * #SecretValue as the argument instead of a null-terminated passwords. + * This is similar to [func@password_storev_sync], but takes a [struct@Value] as + * the argument instead of a null-terminated passwords. * * This method may block indefinitely and should not be used in user interface * threads. @@ -779,7 +758,7 @@ secret_password_lookupv (const SecretSchema *schema, * Finish an asynchronous operation to lookup a password in the secret service. * * Returns: (transfer full): a new password string stored in nonpageable memory - * which must be freed with secret_password_free() when done + * which must be freed with [func@password_free] when done */ gchar * secret_password_lookup_nonpageable_finish (GAsyncResult *result, @@ -804,8 +783,8 @@ secret_password_lookup_nonpageable_finish (GAsyncResult *result, * * Finish an asynchronous operation to lookup a password in the secret service. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found * * Since: 0.19.0 */ @@ -827,7 +806,7 @@ secret_password_lookup_binary_finish (GAsyncResult *result, * Finish an asynchronous operation to lookup a password in the secret service. * * Returns: (transfer full): a new password string which should be freed with - * secret_password_free() or may be freed with g_free() when done + * [func@password_free] or may be freed with [func@GLib.free] when done */ gchar * secret_password_lookup_finish (GAsyncResult *result, @@ -865,7 +844,7 @@ secret_password_lookup_finish (GAsyncResult *result, * threads. * * Returns: (transfer full): a new password string which should be freed with - * secret_password_free() or may be freed with g_free() when done + * [func@password_free] or may be freed with [func@GLib.free] when done */ gchar * secret_password_lookup_sync (const SecretSchema *schema, @@ -917,7 +896,7 @@ secret_password_lookup_sync (const SecretSchema *schema, * threads. * * Returns: (transfer full): a new password string stored in nonpageable memory - * which must be freed with secret_password_free() when done + * which must be freed with [func@password_free] when done */ gchar * secret_password_lookup_nonpageable_sync (const SecretSchema *schema, @@ -966,7 +945,7 @@ secret_password_lookup_nonpageable_sync (const SecretSchema *schema, * threads. * * Returns: (transfer full): a new password string stored in non pageable memory - * which should be freed with secret_password_free() when done + * which should be freed with [func@password_free] when done */ gchar * secret_password_lookupv_nonpageable_sync (const SecretSchema *schema, @@ -1010,14 +989,14 @@ secret_password_lookupv_nonpageable_sync (const SecretSchema *schema, * * Lookup a password in the secret service. * - * This is similar to secret_password_lookup_sync(), but returns a - * #SecretValue instead of a null-terminated password. + * This is similar to [func@password_lookup_sync], but returns a + * [struct@Value] instead of a null-terminated password. * * This method may block indefinitely and should not be used in user interface * threads. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found * * Since: 0.19.0 */ @@ -1060,14 +1039,14 @@ secret_password_lookup_binary_sync (const SecretSchema *schema, * * Lookup a password in the secret service. * - * This is similar to secret_password_lookupv_sync(), but returns a - * #SecretValue instead of a null-terminated password. + * This is similar to [func@password_lookupv_sync], but returns a + * [struct@Value] instead of a null-terminated password. * * This method may block indefinitely and should not be used in user interface * threads. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found * * Since: 0.19.0 */ @@ -1121,7 +1100,7 @@ secret_password_lookupv_binary_sync (const SecretSchema *schema, * threads. * * Returns: (transfer full): a new password string which should be freed with - * secret_password_free() or may be freed with g_free() when done + * [func@password_free] or may be freed with [func@GLib.free] when done */ gchar * secret_password_lookupv_sync (const SecretSchema *schema, @@ -1613,7 +1592,7 @@ secret_password_searchv (const SecretSchema *schema, * Finish an asynchronous operation to search for items in the secret service. * * Returns: (transfer full) (element-type Secret.Retrievable): a list of - * #SecretRetrievable containing attributes of the matched items + * [iface@Retrievable] containing attributes of the matched items * * Since: 0.19.0 */ @@ -1648,7 +1627,7 @@ secret_password_search_finish (GAsyncResult *result, * threads. * * Returns: (transfer full) (element-type Secret.Retrievable): a list of - * #SecretRetrievable containing attributes of the matched items + * [iface@Retrievable] containing attributes of the matched items * * Since: 0.19.0 */ @@ -1701,7 +1680,7 @@ secret_password_search_sync (const SecretSchema *schema, * threads. * * Returns: (transfer full) (element-type Secret.Retrievable): a list of - * #SecretRetrievable containing attributes of the matched items + * [iface@Retrievable] containing attributes of the matched items * * Since: 0.19.0 */ @@ -1746,9 +1725,9 @@ secret_password_searchv_sync (const SecretSchema *schema, * Clear the memory used by a password, and then free it. * * This function must be used to free nonpageable memory returned by - * secret_password_lookup_nonpageable_finish(), - * secret_password_lookup_nonpageable_sync() or - * secret_password_lookupv_nonpageable_sync(). + * [func@password_lookup_nonpageable_finish], + * [func@password_lookup_nonpageable_sync] or + * [func@password_lookupv_nonpageable_sync]. */ void secret_password_free (gchar *password) 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 diff --git a/libsecret/secret-prompt.c b/libsecret/secret-prompt.c index 24229da..c40ce5d 100644 --- a/libsecret/secret-prompt.c +++ b/libsecret/secret-prompt.c @@ -22,33 +22,27 @@ #include <glib/gi18n-lib.h> /** - * SECTION:secret-prompt - * @title: SecretPrompt - * @short_description: a prompt in the Service + * SecretPrompt: + * + * A prompt in the Service * - * A #SecretPrompt represents a prompt in the Secret Service. + * A proxy object representing a prompt that the Secret Service will display + * to the user. * * Certain actions on the Secret Service require user prompting to complete, * such as creating a collection, or unlocking a collection. When such a prompt * is necessary, then a #SecretPrompt object is created by this library, and - * passed to the secret_service_prompt() method. In this way it is handled + * passed to the [method@Service.prompt] method. In this way it is handled * automatically. * * In order to customize prompt handling, override the - * SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish - * virtual methods of the #SecretService class. + * [vfunc@Service.prompt_async] and [vfunc@Service.prompt_finish] virtual + * methods of the [class@Service] class. * * Stability: Stable */ /** - * SecretPrompt: - * - * A proxy object representing a prompt that the Secret Service will display - * to the user. - */ - -/** * SecretPromptClass: * @parent_class: the parent class * @@ -131,10 +125,10 @@ _secret_prompt_instance (SecretService *service, * API specification. * * If @window_id is non-null then it is used as an XWindow id on Linux. The API - * expects this id to be converted to a string using the <literal>%d</literal> - * printf format. The Secret Service can make its prompt transient for the window - * with this id. In some Secret Service implementations this is not possible, so - * the behavior depending on this should degrade gracefully. + * expects this id to be converted to a string using the `%d` printf format. The + * Secret Service can make its prompt transient for the window with this id. In + * some Secret Service implementations this is not possible, so the behavior + * depending on this should degrade gracefully. * * This runs the dialog in a recursive mainloop. When run from a user interface * thread, this means the user interface will remain responsive. Care should be @@ -191,10 +185,10 @@ secret_prompt_run (SecretPrompt *self, * API specification. * * If @window_id is non-null then it is used as an XWindow id on Linux. The API - * expects this id to be converted to a string using the <literal>%d</literal> - * printf format. The Secret Service can make its prompt transient for the window - * with this id. In some Secret Service implementations this is not possible, - * so the behavior depending on this should degrade gracefully. + * expects this id to be converted to a string using the `%d` printf format. The + * Secret Service can make its prompt transient for the window with this id. In + * some Secret Service implementations this is not possible, so the behavior + * depending on this should degrade gracefully. * * This method may block indefinitely and should not be used in user interface * threads. @@ -412,10 +406,10 @@ on_prompt_cancelled (GCancellable *cancellable, * was completed and not dismissed. * * If @window_id is non-null then it is used as an XWindow id on Linux. The API - * expects this id to be converted to a string using the <literal>%d</literal> - * printf format. The Secret Service can make its prompt transient for the window - * with this id. In some Secret Service implementations this is not possible, so - * the behavior depending on this should degrade gracefully. + * expects this id to be converted to a string using the `%d` printf format. The + * Secret Service can make its prompt transient for the window with this id. In + * some Secret Service implementations this is not possible, so the behavior + * depending on this should degrade gracefully. * * This method will return immediately and complete asynchronously. */ @@ -505,7 +499,7 @@ secret_prompt_perform (SecretPrompt *self, * defined in the Secret Service DBus API specification. * * Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred, - * a variant result if the prompt was successful + * a variant result if the prompt was successful */ GVariant * secret_prompt_perform_finish (SecretPrompt *self, diff --git a/libsecret/secret-retrievable.c b/libsecret/secret-retrievable.c index caa063b..d64285b 100644 --- a/libsecret/secret-retrievable.c +++ b/libsecret/secret-retrievable.c @@ -18,16 +18,16 @@ #include "secret-private.h" /** - * SECTION:secret-retrievable - * @title: SecretRetrievable - * @short_description: A read-only secret item + * SecretRetrievable + * + * A read-only secret item * * #SecretRetrievable provides a read-only view of a secret item * stored in the Secret Service. * - * Each item has a value, represented by a #SecretValue, which can be - * retrieved by secret_retrievable_retrieve_secret() and - * secret_retrievable_retrieve_secret_finish(). + * Each item has a value, represented by a [struct@Value], which can be + * retrieved by [method@Retrievable.retrieve_secret] and + * [method@Retrievable.retrieve_secret_finish]. * * Stability: Stable */ @@ -44,10 +44,10 @@ /** * SecretRetrievableInterface: * @parent_iface: the parent interface - * @retrieve_secret: implementation of secret_retrievable_retrieve_secret(), + * @retrieve_secret: implementation of [method@Retrievable.retrieve_secret], * required * @retrieve_secret_finish: implementation of - * secret_retrievable_retrieve_secret_finish(), required + * [method@Retrievable.retrieve_secret_finish], required * * The interface for #SecretRetrievable. * @@ -60,7 +60,7 @@ static void secret_retrievable_default_init (SecretRetrievableInterface *iface) { /** - * SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full) + * SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full) (attributes org.gtk.Property.get=secret_retrievable_get_attributes) * * The attributes set on this item. Attributes are used to locate an * item. They are not guaranteed to be stored or transferred securely. @@ -72,7 +72,7 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface) G_TYPE_HASH_TABLE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretRetrievable:label: + * SecretRetrievable:label: (attributes org.gtk.Property.get=secret_retrievable_get_label) * * The human readable label for the item. * @@ -83,7 +83,7 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface) NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretRetrievable:created: + * SecretRetrievable:created: (attributes org.gtk.Property.get=secret_retrievable_get_created) * * The date and time (in seconds since the UNIX epoch) that this * item was created. @@ -95,7 +95,7 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface) 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretRetrievable:modified: + * SecretRetrievable:modified: (attributes org.gtk.Property.get=secret_retrievable_get_modified) * * The date and time (in seconds since the UNIX epoch) that this * item was last modified. @@ -146,7 +146,7 @@ secret_retrievable_retrieve_secret (SecretRetrievable *self, * Complete asynchronous operation to retrieve the secret value of this object. * * Returns: (transfer full) (nullable): the secret value which should be - * released with secret_value_unref(), or %NULL + * released with [method@Value.unref], or %NULL * * Since: 0.19.0 */ @@ -178,7 +178,7 @@ secret_retrievable_retrieve_secret_finish (SecretRetrievable *self, * threads. * * Returns: (transfer full) (nullable): the secret value which should be - * released with secret_value_unref(), or %NULL + * released with [method@Value.unref], or %NULL * * Since: 0.19.0 */ @@ -213,7 +213,7 @@ secret_retrievable_retrieve_secret_sync (SecretRetrievable *self, } /** - * secret_retrievable_get_attributes: + * secret_retrievable_get_attributes: (attributes org.gtk.Method.get_property=attributes) * @self: a retrievable object * * Get the attributes of this object. @@ -225,8 +225,8 @@ secret_retrievable_retrieve_secret_sync (SecretRetrievable *self, * Do not modify the attribute returned by this method. * * Returns: (transfer full) (element-type utf8 utf8): a new reference - * to the attributes, which should not be modified, and - * released with g_hash_table_unref() + * to the attributes, which should not be modified, and + * released with [func@GLib.HashTable.unref] * * Since: 0.19.0 */ @@ -247,7 +247,7 @@ secret_retrievable_get_attributes (SecretRetrievable *self) * * Get the label of this item. * - * Returns: (transfer full): the label, which should be freed with g_free() + * Returns: (transfer full): the label, which should be freed with [func@GLib.free] * * Since: 0.19.0 */ @@ -263,7 +263,7 @@ secret_retrievable_get_label (SecretRetrievable *self) } /** - * secret_retrievable_get_created: + * secret_retrievable_get_created: (attributes org.gtk.Method.get_property=created) * @self: a retrievable object * * Get the created date and time of the object. The return value is @@ -285,7 +285,7 @@ secret_retrievable_get_created (SecretRetrievable *self) } /** - * secret_retrievable_get_modified: + * secret_retrievable_get_modified: (attributes org.gtk.Method.get_property=modified) * @self: a retrievable object * * Get the modified date and time of the object. The return value is diff --git a/libsecret/secret-schema.c b/libsecret/secret-schema.c index b04d922..32967bf 100644 --- a/libsecret/secret-schema.c +++ b/libsecret/secret-schema.c @@ -23,82 +23,6 @@ #include "egg/egg-secure-memory.h" /** - * SECTION:secret-schema - * @title: SecretSchema - * @short_description: Schema for defining which attributes are on items - * - * Each password is associated with a set of attributes. Attribute values can - * be either strings, integers or booleans. - * - * The names and types of allowed attributes for a given password are defined - * with a schema. - * - * Additional schemas can be defined via the %SecretSchema structure like this: - * - * <informalexample><programlisting language="c"> - * /<!-- -->* in a header: *<!-- -->/ - * - * const SecretSchema * example_get_schema (void) G_GNUC_CONST; - * - * #define EXAMPLE_SCHEMA example_get_schema () - * - * - * /<!-- -->* in a .c file: *<!-- -->/ - * - * const SecretSchema * - * example_get_schema (void) - * { - * static const SecretSchema the_schema = { - * "org.example.Password", SECRET_SCHEMA_NONE, - * { - * { "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER }, - * { "string", SECRET_SCHEMA_ATTRIBUTE_STRING }, - * { "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN }, - * { NULL, 0 }, - * } - * }; - * return &the_schema; - * } - * </programlisting></informalexample> - * - * Stability: Stable - */ - -/** - * SecretSchema: - * @name: the dotted name of the schema - * @flags: flags for the schema - * @attributes: the attribute names and types of those attributes - * - * Represents a set of attributes that are stored with an item. These schemas - * are used for interoperability between various services storing the same types - * of items. - * - * Each schema has a name like "org.gnome.keyring.NetworkPassword", and defines - * a set of attributes, and types (string, integer, boolean) for those attributes. - * - * Attributes are stored as strings in the Secret Service, and the attribute - * types simply define standard ways to store integer and boolean values as strings. - * Attributes are represented in libsecret via a #GHashTable with string keys and - * values. Even for values that defined as an integer or boolean in the schema, - * the attribute values in the #GHashTable are strings. Boolean values are stored - * as the strings 'true' and 'false'. Integer values are stored in decimal, with - * a preceding negative sign for negative integers. - * - * Schemas are handled entirely on the client side by this library. The name of the - * schema is automatically stored as an attribute on the item. - * - * Normally when looking up passwords only those with matching schema names are - * returned. If the schema @flags contain the %SECRET_SCHEMA_DONT_MATCH_NAME flag, - * then lookups will not check that the schema name matches that on the item, only - * the schema's attributes are matched. This is useful when you are looking up items - * that are not stored by the libsecret library. Other libraries such as libgnome-keyring - * don't store the schema name. - * - * Stability: Stable - */ - -/** * SecretSchemaFlags: * @SECRET_SCHEMA_NONE: no flags for the schema * @SECRET_SCHEMA_DONT_MATCH_NAME: don't match the schema name when looking up or @@ -161,12 +85,12 @@ G_DEFINE_BOXED_TYPE (SecretSchemaAttribute, secret_schema_attribute, * schemas are used for interoperability between various services storing the * same types of items. * - * Each schema has an @name like "org.gnome.keyring.NetworkPassword", and + * Each schema has an @name like `org.gnome.keyring.NetworkPassword`, and * defines a set of attributes names, and types (string, integer, boolean) for * those attributes. * * Each key in the @attributes table should be a attribute name strings, and - * the values in the table should be integers from the #SecretSchemaAttributeType + * the values in the table should be integers from the [enum@SchemaAttributeType] * enumeration, representing the attribute type for each attribute name. * * Normally when looking up passwords only those with matching schema names are @@ -177,7 +101,7 @@ G_DEFINE_BOXED_TYPE (SecretSchemaAttribute, secret_schema_attribute, * don't store the schema name. * * Returns: (transfer full): the new schema, which should be unreferenced with - * secret_schema_unref() when done + * [method@Schema.unref] when done */ SecretSchema * secret_schema_newv (const gchar *name, @@ -244,13 +168,13 @@ secret_schema_newv (const gchar *name, * schemas are used for interoperability between various services storing the * same types of items. * - * Each schema has an @name like "org.gnome.keyring.NetworkPassword", and + * Each schema has an @name like `org.gnome.keyring.NetworkPassword`, and * defines a set of attributes names, and types (string, integer, boolean) for * those attributes. * * The variable argument list should contain pairs of a) The attribute name as * a null-terminated string, followed by b) integers from the - * #SecretSchemaAttributeType enumeration, representing the attribute type for + * [enum@SchemaAttributeType] enumeration, representing the attribute type for * each attribute name. The list of attributes should be terminated with a %NULL. * * Normally when looking up passwords only those with matching schema names are @@ -261,7 +185,7 @@ secret_schema_newv (const gchar *name, * don't store the schema name. * * Returns: (transfer full): the new schema, which should be unreferenced with - * secret_schema_unref() when done + * [method@Schema.unref] when done */ SecretSchema * secret_schema_new (const gchar *name, @@ -304,7 +228,7 @@ secret_schema_new (const gchar *name, * allocated, then this function will copy the schema. * * Returns: (transfer full): the referenced schema, which should be later - * unreferenced with secret_schema_unref() + * unreferenced with [method@Schema.unref] */ SecretSchema * secret_schema_ref (SecretSchema *schema) diff --git a/libsecret/secret-schemas.c b/libsecret/secret-schemas.c index f07a2ac..cc51a6d 100644 --- a/libsecret/secret-schemas.c +++ b/libsecret/secret-schemas.c @@ -17,18 +17,6 @@ #include "secret-schema.h" #include "secret-schemas.h" -/** - * SECRET_SCHEMA_NOTE: (skip) - * - * A predefined schema for personal passwords stored by the user in the - * password manager. This schema has no attributes, and the items are not - * meant to be used automatically by applications. - * - * When used to search for items using this schema, it will only match - * items that have the same schema. Items stored via libgnome-keyring with the - * <literal>GNOME_KEYRING_ITEM_NOTE</literal> item type will match. - */ - static const SecretSchema note_schema = { "org.gnome.keyring.Note", SECRET_SCHEMA_NONE, @@ -39,37 +27,6 @@ static const SecretSchema note_schema = { const SecretSchema * SECRET_SCHEMA_NOTE = ¬e_schema; -/** - * SECRET_SCHEMA_COMPAT_NETWORK: (skip) - * - * A predefined schema that is compatible with items stored via the - * libgnome-keyring 'network password' functions. This is meant to be used by - * applications migrating from libgnome-keyring which stored their secrets as - * 'network passwords'. It is not recommended that new code use this schema. - * - * When used to search for items using this schema, it will only match - * items that have the same schema. Items stored via libgnome-keyring with the - * <literal>GNOME_KEYRING_ITEM_NETWORK_PASSWORD</literal> item type will match. - * - * The following attributes exist in the schema: - * <variablelist><title>Attributes:</title> - * <varlistentry><term><literal>user</literal>:</term> - * <listitem><para>The user name (string).</para></listitem></varlistentry> - * <varlistentry><term><literal>domain</literal>:</term> - * <listitem><para>The login domain or realm (string).</para></listitem></varlistentry> - * <varlistentry><term><literal>object</literal>:</term> - * <listitem><para>The object or path (string).</para></listitem></varlistentry> - * <varlistentry><term><literal>protocol</literal>:</term> - * <listitem><para>The protocol (a string like 'http').</para></listitem></varlistentry> - * <varlistentry><term><literal>port</literal>:</term> - * <listitem><para>The network port (integer).</para></listitem></varlistentry> - * <varlistentry><term><literal>server</literal>:</term> - * <listitem><para>The hostname or server (string).</para></listitem></varlistentry> - * <varlistentry><term><literal>authtype</literal>:</term> - * <listitem><para>The authentication type (string).</para></listitem></varlistentry> - * </variablelist> - */ - static const SecretSchema network_schema = { "org.gnome.keyring.NetworkPassword", SECRET_SCHEMA_NONE, @@ -97,6 +54,7 @@ const SecretSchema * SECRET_SCHEMA_COMPAT_NETWORK = &network_schema; * language bindings cannot, and must use this accessor. * * Returns: (transfer none): schema type + * * Since: 0.18.6 */ const SecretSchema * diff --git a/libsecret/secret-schemas.h b/libsecret/secret-schemas.h index c78a001..c61ee97 100644 --- a/libsecret/secret-schemas.h +++ b/libsecret/secret-schemas.h @@ -39,12 +39,67 @@ extern const SecretSchema * SECRET_SCHEMA_COMPAT_NETWORK; /** * SecretSchemaType: - * @SECRET_SCHEMA_TYPE_NOTE: Personal passwords; see %SECRET_SCHEMA_NOTE + * @SECRET_SCHEMA_TYPE_NOTE: Personal passwords * @SECRET_SCHEMA_TYPE_COMPAT_NETWORK: Network passwords from older - * libgnome-keyring storage; see %SECRET_SCHEMA_COMPAT_NETWORK + * libgnome-keyring storage * * Different types of schemas for storing secrets, intended for use with - * secret_get_schema(). + * [func@get_schema]. + * + * ## @SECRET_SCHEMA_NOTE + * + * A predefined schema for personal passwords stored by the user in the + * password manager. This schema has no attributes, and the items are not + * meant to be used automatically by applications. + * + * When used to search for items using this schema, it will only match + * items that have the same schema. Items stored via libgnome-keyring with the + * `GNOME_KEYRING_ITEM_NOTE` item type will match. + * + * ## @SECRET_SCHEMA_COMPAT_NETWORK + * + * A predefined schema that is compatible with items stored via the + * libgnome-keyring 'network password' functions. This is meant to be used by + * applications migrating from libgnome-keyring which stored their secrets as + * 'network passwords'. It is not recommended that new code use this schema. + * + * When used to search for items using this schema, it will only match + * items that have the same schema. Items stored via libgnome-keyring with the + * `GNOME_KEYRING_ITEM_NETWORK_PASSWORD` item type will match. + * + * The following attributes exist in the schema: + * + * ### Attributes: + * + * <table> + * <tr> + * <td><tt>user</tt>:</td> + * <td>The user name (string).</td> + * </tr> + * <tr> + * <td><tt>domain</tt>:</td> + * <td>The login domain or realm (string).</td></tr> + * <tr> + * <td><tt>object</tt>:</td> + * <td>The object or path (string).</td> + * </tr> + * <tr> + * <td><tt>protocol</tt>:</td> + * <td>The protocol (a string like 'http').</td> + * </tr> + * <tr> + * <td><tt>port</tt>:</td> + * <td>The network port (integer).</td> + * </tr> + * <tr> + * <td><tt>server</tt>:</td> + * <td>The hostname or server (string).</td> + * </tr> + * <tr> + * <td><tt>authtype</tt>:</td> + * <td>The authentication type (string).</td> + * </tr> + * </table> * * Since: 0.18.6 */ diff --git a/libsecret/secret-service.c b/libsecret/secret-service.c index 455248c..bdb8bd7 100644 --- a/libsecret/secret-service.c +++ b/libsecret/secret-service.c @@ -30,59 +30,54 @@ #include "egg/egg-secure-memory.h" /** - * SECTION:secret-service - * @title: SecretService - * @short_description: the Secret Service + * SecretService: + * + * A proxy object representing the Secret Service. * * A #SecretService object represents the Secret Service implementation which * 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 + * callers. The [func@Service.get] method is used to access this #SecretService * object. If a new independent #SecretService object is required, use - * secret_service_open(). + * [func@Service.open]. * * In order to securely transfer secrets to the Sercret Service, a session * is established. This session can be established while initializing a * #SecretService object by passing the %SECRET_SERVICE_OPEN_SESSION flag - * to the secret_service_get() or secret_service_open() functions. In order to + * to the [func@Service.get] or [func@Service.open] functions. In order to * establish a session on an already existing #SecretService, use the - * secret_service_ensure_session() function. + * [method@Service.ensure_session] function. * - * To search for items, use the secret_service_search() method. + * To search for items, use the [method@Service.search] method. * * Multiple collections can exist in the Secret Service, each of which contains - * secret items. In order to instantiate #SecretCollection objects which + * secret items. In order to instantiate [class@Collection] objects which * represent those collections while initializing a #SecretService then pass - * the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the secret_service_get() or - * secret_service_open() functions. In order to establish a session on an already - * existing #SecretService, use the secret_service_load_collections() function. - * To access the list of collections use secret_service_get_collections(). + * the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the [func@Service.get] or + * [func@Service.open] functions. In order to establish a session on an already + * existing #SecretService, use the [method@Service.load_collections] function. + * To access the list of collections use [method@Service.get_collections]. * * Certain actions on the Secret Service require user prompting to complete, * such as creating a collection, or unlocking a collection. When such a prompt - * is necessary, then a #SecretPrompt object is created by this library, and - * passed to the secret_service_prompt() method. In this way it is handled + * is necessary, then a [class@Prompt] object is created by this library, and + * passed to the [method@Service.prompt] method. In this way it is handled * automatically. * - * In order to customize prompt handling, override the <literal>prompt_async</literal> - * and <literal>prompt_finish</literal> virtual methods of the #SecretService class. + * In order to customize prompt handling, override the + * [vfunc@Service.prompt_async] and [vfunc@Service.prompt_finish] virtual + * methods of the #SecretService class. * * Stability: Stable */ /** - * SecretService: - * - * A proxy object representing the Secret Service. - */ - -/** * SecretServiceClass: * @parent_class: the parent class - * @collection_gtype: the #GType of the #SecretCollection objects instantiated + * @collection_gtype: the [alias@GLib.Type] of the [class@Collection] objects instantiated * by the #SecretService proxy - * @item_gtype: the #GType of the #SecretItem objects instantiated by the + * @item_gtype: the [alias@GLib.Type] of the [class@Item] objects instantiated by the * #SecretService proxy * @prompt_async: called to perform asynchronous prompting when necessary * @prompt_finish: called to complete an asynchronous prompt operation @@ -104,7 +99,7 @@ * #SecretService * * Flags which determine which parts of the #SecretService proxy are initialized - * during a secret_service_get() or secret_service_open() operation. + * during a [func@Service.get] or [func@Service.open] operation. */ EGG_SECURE_DEFINE_GLIB_GLOBALS (); @@ -587,15 +582,15 @@ secret_service_class_init (SecretServiceClass *klass) g_object_class_override_property (object_class, PROP_FLAGS, "flags"); /** - * SecretService:collections: + * SecretService:collections: (attributes org.gtk.Property.get=secret_service_get_collections) * - * A list of #SecretCollection objects representing the collections in + * A list of [class@Collection] objects representing the collections in * the Secret Service. This list may be %NULL if the collections have * not been loaded. * * To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS - * initialization flag when calling the secret_service_get() or - * secret_service_open() functions. Or call the secret_service_load_collections() + * initialization flag when calling the [func@Service.get] or + * [func@Service.open] functions. Or call the [method@Service.load_collections] * method. */ g_object_class_install_property (object_class, PROP_COLLECTIONS, @@ -1002,7 +997,7 @@ secret_service_get (SecretServiceFlags flags, * Secret Service. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_get_finish (GAsyncResult *result, @@ -1058,7 +1053,7 @@ secret_service_get_finish (GAsyncResult *result, * threads. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_get_sync (SecretServiceFlags flags, @@ -1090,8 +1085,8 @@ secret_service_get_sync (SecretServiceFlags flags, /** * secret_service_disconnect: * - * Disconnect the default #SecretService proxy returned by secret_service_get() - * and secret_service_get_sync(). + * Disconnect the default #SecretService proxy returned by [func@Service.get] + * and [func@Service.get_sync]. * * It is not necessary to call this function, but you may choose to do so at * program exit. It is useful for testing that memory is not leaked. @@ -1117,7 +1112,7 @@ secret_service_disconnect (void) * * Create a new #SecretService proxy for the Secret Service. * - * This function is rarely used, see secret_service_get() instead. + * This function is rarely used, see [func@Service.get] instead. * * The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the type * of a derived class. @@ -1155,7 +1150,7 @@ secret_service_open (GType service_gtype, * the Secret Service. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_open_finish (GAsyncResult *result, @@ -1188,7 +1183,7 @@ secret_service_open_finish (GAsyncResult *result, * * Create a new #SecretService proxy for the Secret Service. * - * This function is rarely used, see secret_service_get_sync() instead. + * This function is rarely used, see [func@Service.get_sync] instead. * * The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the * type of a derived class. @@ -1202,7 +1197,7 @@ secret_service_open_finish (GAsyncResult *result, * threads. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_open_sync (GType service_gtype, @@ -1226,7 +1221,7 @@ secret_service_open_sync (GType service_gtype, * Get the flags representing what features of the #SecretService proxy * have been initialized. * - * Use secret_service_ensure_session() or secret_service_load_collections() + * Use [method@Service.ensure_session] or [method@Service.load_collections] * to initialize further features and change the flags. * * Returns: the flags for features initialized @@ -1251,18 +1246,18 @@ secret_service_get_flags (SecretService *self) } /** - * secret_service_get_collections: + * secret_service_get_collections: (attributes org.gtk.Method.get_property=collections) * @self: the secret service proxy * - * Get a list of #SecretCollection objects representing all the collections + * Get a list of [class@Collection] objects representing all the collections * in the secret service. * * If the %SECRET_SERVICE_LOAD_COLLECTIONS flag was not specified when * initializing #SecretService proxy object, then this method will return - * %NULL. Use secret_service_load_collections() to load the collections. + * %NULL. Use [method@Service.load_collections] to load the collections. * * Returns: (transfer full) (element-type Secret.Collection) (nullable): a - * list of the collections in the secret service + * list of the collections in the secret service */ GList * secret_service_get_collections (SecretService *self) @@ -1364,7 +1359,7 @@ _secret_service_take_session (SecretService *self, * 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. + * [method@Service.ensure_session] to establish a session. * * Returns: (nullable): a string representing the algorithms for transferring * secrets @@ -1394,10 +1389,10 @@ secret_service_get_session_algorithms (SecretService *self) * 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. + * [method@Service.ensure_session] to establish a session. * * Returns: (nullable): a string representing the D-Bus object path of the - * session + * session */ const gchar * secret_service_get_session_dbus_path (SecretService *self) @@ -1428,7 +1423,7 @@ secret_service_get_session_dbus_path (SecretService *self) * * It is not normally necessary to call this method, as the session is * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION - * to secret_service_get() in order to ensure that a session has been established + * to [func@Service.get] in order to ensure that a session has been established * by the time you get the #SecretService proxy. * * This method will return immediately and complete asynchronously. @@ -1500,7 +1495,7 @@ secret_service_ensure_session_finish (SecretService *self, * * It is not normally necessary to call this method, as the session is * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION - * to secret_service_get_sync() in order to ensure that a session has been + * to [func@Service.get_sync] in order to ensure that a session has been * established by the time you get the #SecretService proxy. * * This method may block indefinitely and should not be used in user interface @@ -1638,10 +1633,10 @@ on_ensure_collection (GObject *source, * * Ensure that the #SecretService proxy has loaded all the collections present * in the Secret Service. This affects the result of - * secret_service_get_collections(). + * [method@Service.get_collections]. * * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to - * secret_service_get_sync() in order to ensure that the collections have been + * [func@Service.get_sync] in order to ensure that the collections have been * loaded by the time you get the #SecretService proxy. * * This method will return immediately and complete asynchronously. @@ -1735,10 +1730,10 @@ secret_service_load_collections_finish (SecretService *self, * * Ensure that the #SecretService proxy has loaded all the collections present * in the Secret Service. This affects the result of - * secret_service_get_collections(). + * [method@Service.get_collections]. * * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to - * secret_service_get_sync() in order to ensure that the collections have been + * [func@Service.get_sync] in order to ensure that the collections have been * loaded by the time you get the #SecretService proxy. * * This method may block indefinitely and should not be used in user interface @@ -1801,7 +1796,7 @@ secret_service_load_collections_sync (SecretService *self, * @return_type: the variant type of the prompt result * @error: location to place an error on failure * - * Perform prompting for a #SecretPrompt. + * Perform prompting for a [class@Prompt]. * * Runs a prompt and performs the prompting. Returns a variant result if the * prompt was completed and not dismissed. The type of result depends on the @@ -1811,12 +1806,12 @@ secret_service_load_collections_sync (SecretService *self, * 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_sync</literal> virtual method + * Override the #SecretServiceClass [vfunc@Service.prompt_sync] virtual method * to change the behavior of the prompting. The default behavior is to simply - * run secret_prompt_perform_sync() on the prompt with a %NULL <literal>window_id</literal>. + * run [method@Prompt.perform_sync] on the prompt with a %NULL `window_id`. * * Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred, - * a variant result if the prompt was successful + * a variant result if the prompt was successful */ GVariant * secret_service_prompt_sync (SecretService *self, @@ -1847,14 +1842,14 @@ secret_service_prompt_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 prompting. The default behavior is to simply - * run secret_prompt_perform() on the prompt. + * run [method@Prompt.perform] on the prompt. */ void secret_service_prompt (SecretService *self, @@ -1882,14 +1877,14 @@ secret_service_prompt (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 * in the Secret Service DBus API specification. * * Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred, - * a variant result if the prompt was successful + * a variant result if the prompt was successful */ GVariant * secret_service_prompt_finish (SecretService *self, @@ -1913,7 +1908,7 @@ secret_service_prompt_finish (SecretService *self, * @self: the secret service * * Get the GObject type for collections instantiated by this service. - * This will always be either #SecretCollection or derived from it. + * This will always be either [class@Collection] or derived from it. * * Returns: the gobject type for collections */ @@ -1941,7 +1936,7 @@ secret_service_get_collection_gtype (SecretService *self) * @self: the service * * Get the GObject type for items instantiated by this service. - * This will always be either #SecretItem or derived from it. + * This will always be either [class@Item] or derived from it. * * Returns: the gobject type for items */ diff --git a/libsecret/secret-util.c b/libsecret/secret-util.c index f011728..3b601bc 100644 --- a/libsecret/secret-util.c +++ b/libsecret/secret-util.c @@ -20,9 +20,9 @@ #include <string.h> /** - * SECTION:secret-error - * @title: SecretError - * @short_description: libsecret errors + * SecretError + * + * libsecret errors * * Various errors reported by the libsecret library. No error returned from * the libsecret API is suitable for direct display to the user. It is up diff --git a/libsecret/secret-value.c b/libsecret/secret-value.c index d58feb3..19a2131 100644 --- a/libsecret/secret-value.c +++ b/libsecret/secret-value.c @@ -22,33 +22,27 @@ #include <string.h> /** - * SECTION:secret-value - * @title: SecretValue - * @short_description: a value containing a secret + * SecretValue: + * + * A value containing a secret * * A #SecretValue contains a password or other secret value. * - * Use secret_value_get() to get the actual secret data, such as a password. + * Use [method@Value.get] to get the actual secret data, such as a password. * The secret data is not necessarily null-terminated, unless the content type * is "text/plain". * - * Each #SecretValue has a content type. For passwords, this is "text/plain". - * Use secret_value_get_content_type() to look at the content type. + * Each #SecretValue has a content type. For passwords, this is `text/plain`. + * Use [method@Value.get_content_type] to look at the content type. * * #SecretValue is reference counted and immutable. The secret data is only - * freed when all references have been released via secret_value_unref(). + * freed when all references have been released via [method@Value.unref]. * * Stability: Stable */ static gboolean is_password_value (SecretValue *value); -/** - * SecretValue: - * - * A secret value, like a password or other binary secret. - */ - EGG_SECURE_DECLARE (secret_value); struct _SecretValue { @@ -153,8 +147,8 @@ secret_value_new_full (gchar *secret, * @length: the length of the secret * * Get the secret data in the #SecretValue. The value is not necessarily - * null-terminated unless it was created with secret_value_new() or a - * null-terminated string was passed to secret_value_new_full(). + * null-terminated unless it was created with [ctor@Value.new] or a + * null-terminated string was passed to [ctor@Value.new_full]. * * Returns: (array length=length) (element-type guint8): the secret data */ @@ -173,7 +167,7 @@ secret_value_get (SecretValue *value, * @value: the value * * Get the secret data in the #SecretValue if it contains a textual - * value. The content type must be <literal>text/plain</literal>. + * value. The content type must be `text/plain`. * * Returns: (nullable): the content type */ @@ -193,7 +187,7 @@ secret_value_get_text (SecretValue *value) * @value: the value * * Get the content type of the secret value, such as - * <literal>text/plain</literal>. + * `text/plain`. * * Returns: the content type */ @@ -209,7 +203,7 @@ secret_value_get_content_type (SecretValue *value) * @value: value to reference * * Add another reference to the #SecretValue. For each reference - * secret_value_unref() should be called to unreference the value. + * [method@Value.unref] should be called to unreference the value. * * Returns: (transfer full): the value */ @@ -265,7 +259,7 @@ is_password_value (SecretValue *value) * #SecretValue as nonpageable memory. * * Returns: (transfer full): a new password string stored in nonpageable memory - * which must be freed with secret_password_free() when done + * which must be freed with [func@password_free] when done * * Since: 0.19.0 */ diff --git a/libsecret/secret-version.h.in b/libsecret/secret-version.h.in index 4c89d7f..8dae6a5 100644 --- a/libsecret/secret-version.h.in +++ b/libsecret/secret-version.h.in @@ -20,14 +20,6 @@ #define __SECRET_VERSION_H__ /** - * SECTION:secret-version - * @short_description: Variables and macros to check the libsecret version - * @title: Version Information - * - * Stability: Stable - */ - -/** * SECRET_MAJOR_VERSION: * * The major version of libsecret. |