diff options
Diffstat (limited to 'libsecret/secret-item.c')
| -rw-r--r-- | libsecret/secret-item.c | 80 |
1 files changed, 37 insertions, 43 deletions
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) |