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

Merge branch 'doc-fixes' into 'master'

Browse Source 
Improvements to documentation and annotations

See merge request GNOME/libsecret!103
This commit is contained in:
Niels De Graef 2022-02-12 10:52:27 +00:00
commit e984e7bb67
17 changed files with 312 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -12,7 +12,7 @@ https://specifications.freedesktop.org/secret-service/.
Documentation Documentation
-------- --------
You can find the nighlt documentation at https://gnome.pages.gitlab.gnome.org/libsecret/. You can find the nightly documentation at https://gnome.pages.gitlab.gnome.org/libsecret/.
Building Building
-------- --------

55
docs/reference/libsecret/libsecret-simple-api.md
View File

@ -20,61 +20,6 @@ the [struct@Schema] structure.
Each of the functions accept a variable list of attributes names and their Each of the functions accept a variable list of attributes names and their
values. Include a `NULL` to terminate the list of attributes. values. Include a `NULL` to terminate the list of attributes.
## SecretSchema
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 [struct@GLib.HashTable] with
string keys and values. Even for values that defined as an integer or boolean in
the schema, the attribute values in the [struct@GLib.HashTable] 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.
Additional schemas can be defined via the %SecretSchema structure like this:
```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;
}
```
## Secret Attributes ## Secret Attributes
Each item has a set of attributes, which are used to locate the item later. Each item has a set of attributes, which are used to locate the item later.

2
docs/reference/libsecret/libsecret.toml.in
View File

@ -32,7 +32,7 @@ show_index_summary = true
show_class_hierarchy = true show_class_hierarchy = true
[source-location] [source-location]
base_url = "https://gitlab.gnome.org/GNOME/libsecret/-/blob/master" base_url = "https://gitlab.gnome.org/GNOME/libsecret/-/blob/master/"
[extra] [extra]
# The same order will be used when generating the index # The same order will be used when generating the index

1
libsecret/meson.build
View File

@ -132,6 +132,7 @@ if get_option('introspection')
'secret-types.h', 'secret-types.h',
'secret-value.c', 'secret-value.c',
'secret-value.h', 'secret-value.h',
'secret-util.c',
] ]
libsecret_gir_sources += version_h libsecret_gir_sources += version_h
libsecret_gir_sources += _enums_generated libsecret_gir_sources += _enums_generated

25
libsecret/secret-backend.c
View File

@ -25,20 +25,12 @@
#include "libsecret/secret-enum-types.h" #include "libsecret/secret-enum-types.h"
/** /**
* SecretBackend * SecretBackend:
*
* A backend implementation of password storage
* *
* #SecretBackend represents a backend implementation of password * #SecretBackend represents a backend implementation of password
* storage. * storage.
* *
* Stability: Stable * Stability: Stable
*/
/**
* SecretBackend:
*
* An object representing a backend implementation of password storage.
* *
* Since: 0.19.0 * Since: 0.19.0
*/ */
@ -66,15 +58,21 @@
* SecretBackendFlags: * SecretBackendFlags:
* @SECRET_BACKEND_NONE: no flags for initializing the #SecretBackend * @SECRET_BACKEND_NONE: no flags for initializing the #SecretBackend
* @SECRET_BACKEND_OPEN_SESSION: establish a session for transfer of secrets * @SECRET_BACKEND_OPEN_SESSION: establish a session for transfer of secrets
* while initializing the #SecretBackend * while initializing the #SecretBackend
* @SECRET_BACKEND_LOAD_COLLECTIONS: load collections while initializing the * @SECRET_BACKEND_LOAD_COLLECTIONS: load collections while initializing the
* #SecretBackend * #SecretBackend
* *
* Flags which determine which parts of the #SecretBackend are initialized. * Flags which determine which parts of the #SecretBackend are initialized.
* *
* Since: 0.19.0 * Since: 0.19.0
*/ */
/**
* SECRET_BACKEND_EXTENSION_POINT_NAME:
*
* Extension point for the secret backend.
*/
G_DEFINE_INTERFACE_WITH_CODE (SecretBackend, secret_backend, G_TYPE_OBJECT, G_DEFINE_INTERFACE_WITH_CODE (SecretBackend, secret_backend, G_TYPE_OBJECT,
g_type_interface_add_prerequisite(g_define_type_id, G_TYPE_ASYNC_INITABLE); g_type_interface_add_prerequisite(g_define_type_id, G_TYPE_ASYNC_INITABLE);
); );
@ -208,8 +206,9 @@ on_ensure_for_flags (GObject *source_object,
* @callback: called when the operation completes * @callback: called when the operation completes
* @user_data: data to be passed to the callback * @user_data: data to be passed to the callback
* *
* Get a #SecretBackend instance. If such a backend already exists, * Get a #SecretBackend instance.
* then the same backend is returned. *
* If such a backend already exists, then the same backend is returned.
* *
* If @flags contains any flags of which parts of the secret backend to * If @flags contains any flags of which parts of the secret backend to
* ensure are initialized, then those will be initialized before completing. * ensure are initialized, then those will be initialized before completing.

28
libsecret/secret-collection.c
View File

@ -70,16 +70,19 @@
/** /**
* SECRET_COLLECTION_DEFAULT: * SECRET_COLLECTION_DEFAULT:
* *
* An alias to the default collection. This can be passed to * An alias to the default collection.
* [func@password_store] [func@Collection.for_alias]. *
* This can be passed to [func@password_store] [func@Collection.for_alias].
*/ */
/** /**
* SECRET_COLLECTION_SESSION: * SECRET_COLLECTION_SESSION:
* *
* An alias to the session collection, which will be cleared when the user ends * An alias to the session collection, which will be cleared when the user ends
* the session. This can be passed to [func@password_store], * the session.
* [func@Collection.for_alias] or similar functions. *
* This can be passed to [func@password_store], [func@Collection.for_alias] or
* similar functions.
*/ */
enum { enum {
@ -759,8 +762,9 @@ on_load_item (GObject *source,
* @user_data: data to be passed to the callback * @user_data: data to be passed to the callback
* *
* Ensure that the #SecretCollection proxy has loaded all the items present * Ensure that the #SecretCollection proxy has loaded all the items present
* in the Secret Service. This affects the result of * in the Secret Service.
* [method@Collection.get_items]. *
* This affects the result of [method@Collection.get_items].
* *
* For collections returned from [method@Service.get_collections] the items will * For collections returned from [method@Service.get_collections] the items will
* have already been loaded. * have already been loaded.
@ -1922,8 +1926,10 @@ secret_collection_get_locked (SecretCollection *self)
* secret_collection_get_created: (attributes org.gtk.Method.get_property=created) * secret_collection_get_created: (attributes org.gtk.Method.get_property=created)
* @self: a collection * @self: a collection
* *
* Get the created date and time of the collection. The return value is * Get the created date and time of the collection.
* the number of seconds since the unix epoch, January 1st 1970. *
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
* *
* Returns: the created date and time * Returns: the created date and time
*/ */
@ -1948,8 +1954,10 @@ secret_collection_get_created (SecretCollection *self)
* secret_collection_get_modified: (attributes org.gtk.Method.get_property=modified) * secret_collection_get_modified: (attributes org.gtk.Method.get_property=modified)
* @self: a collection * @self: a collection
* *
* Get the modified date and time of the collection. The return value is * Get the modified date and time of the collection.
* the number of seconds since the unix epoch, January 1st 1970. *
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
* *
* Returns: the modified date and time * Returns: the modified date and time
*/ */

34
libsecret/secret-item.c
View File

@ -353,7 +353,9 @@ secret_item_class_init (SecretItemClass *klass)
* SecretItem:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full) * SecretItem:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full)
* *
* The attributes set on this item. Attributes are used to locate an * The attributes set on this item. Attributes are used to locate an
* item. They are not guaranteed to be stored or transferred securely. * item.
*
* They are not guaranteed to be stored or transferred securely.
*/ */
g_object_class_override_property (gobject_class, PROP_ATTRIBUTES, "attributes"); g_object_class_override_property (gobject_class, PROP_ATTRIBUTES, "attributes");
@ -371,8 +373,10 @@ secret_item_class_init (SecretItemClass *klass)
/** /**
* SecretItem:locked: (attributes org.gtk.Property.get=secret_item_get_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 * Whether the item is locked or not.
* lockable separate from other items in its collection. *
* An item may not be independently lockable separate from other items in
* its collection.
* *
* To lock or unlock a item use the [method@Service.lock] or * To lock or unlock a item use the [method@Service.lock] or
* [method@Service.unlock] functions. * [method@Service.unlock] functions.
@ -588,8 +592,10 @@ secret_item_async_initable_iface (GAsyncInitableIface *iface)
* secret_item_refresh: * secret_item_refresh:
* @self: the collection * @self: the collection
* *
* Refresh the properties on this item. This fires off a request to * Refresh the properties on this item.
* refresh, and the properties will be updated later. *
* This fires off a request to refresh, and the properties will be updated
* later.
* *
* Calling this method is not normally necessary, as the secret service * Calling this method is not normally necessary, as the secret service
* will notify the client when properties change. * will notify the client when properties change.
@ -1046,8 +1052,10 @@ secret_item_get_service (SecretItem *self)
* secret_item_get_secret: * secret_item_get_secret:
* @self: an item * @self: an item
* *
* Get the secret value of this item. If this item is locked or the secret * Get the secret value of this item.
* has not yet been loaded then this will return %NULL. *
* If this item is locked or the secret has not yet been loaded then this will
* return %NULL.
* *
* To load the secret call the [method@Item.load_secret] method. * To load the secret call the [method@Item.load_secret] method.
* *
@ -1988,8 +1996,10 @@ secret_item_get_locked (SecretItem *self)
* secret_item_get_created: * secret_item_get_created:
* @self: an item * @self: an item
* *
* Get the created date and time of the item. The return value is * Get the created date and time of the item.
* the number of seconds since the unix epoch, January 1st 1970. *
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
* *
* Returns: the created date and time * Returns: the created date and time
*/ */
@ -2014,8 +2024,10 @@ secret_item_get_created (SecretItem *self)
* secret_item_get_modified: * secret_item_get_modified:
* @self: an item * @self: an item
* *
* Get the modified date and time of the item. The return value is * Get the modified date and time of the item.
* the number of seconds since the unix epoch, January 1st 1970. *
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
* *
* Returns: the modified date and time * Returns: the modified date and time
*/ */

29
libsecret/secret-methods.c
View File

@ -270,8 +270,10 @@ on_search_service (GObject *source,
* @callback: called when the operation completes * @callback: called when the operation completes
* @user_data: data to pass to the callback * @user_data: data to pass to the callback
* *
* Search for items matching the @attributes. All collections are searched. * Search for items matching the @attributes.
* The @attributes should be a table of string keys and string values. *
* All collections are searched. The @attributes should be a table of string
* keys and string values.
* *
* If @service is %NULL, then [func@Service.get] will be called to get * If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy. * the default [class@Service] proxy.
@ -410,8 +412,10 @@ service_load_items_sync (SecretService *service,
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @error: location to place error on failure * @error: location to place error on failure
* *
* Search for items matching the @attributes. All collections are searched. * Search for items matching the @attributes.
* The @attributes should be a table of string keys and string values. *
* All collections are searched. The @attributes should be a table of string
* keys and string values.
* *
* If @service is %NULL, then [func@Service.get_sync] will be called to get * If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy. * the default [class@Service] proxy.
@ -760,7 +764,7 @@ secret_service_lock (SecretService *service,
* @service: (nullable): the secret service * @service: (nullable): the secret service
* @result: asynchronous result passed to the callback * @result: asynchronous result passed to the callback
* @locked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional): * @locked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
* location to place list of items or collections that were locked * location to place list of items or collections that were locked
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Complete asynchronous operation to lock items or collections in the secret * Complete asynchronous operation to lock items or collections in the secret
@ -789,7 +793,7 @@ secret_service_lock_finish (SecretService *service,
* @objects: (element-type Gio.DBusProxy): the items or collections to lock * @objects: (element-type Gio.DBusProxy): the items or collections to lock
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @locked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional): * @locked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
* location to place list of items or collections that were locked * location to place list of items or collections that were locked
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Lock items or collections in the secret service. * Lock items or collections in the secret service.
@ -874,7 +878,7 @@ secret_service_unlock (SecretService *service,
* @service: (nullable): the secret service * @service: (nullable): the secret service
* @result: asynchronous result passed to the callback * @result: asynchronous result passed to the callback
* @unlocked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional): * @unlocked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
* location to place list of items or collections that were unlocked * location to place list of items or collections that were unlocked
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Complete asynchronous operation to unlock items or collections in the secret * Complete asynchronous operation to unlock items or collections in the secret
@ -903,7 +907,7 @@ secret_service_unlock_finish (SecretService *service,
* @objects: (element-type Gio.DBusProxy): the items or collections to unlock * @objects: (element-type Gio.DBusProxy): the items or collections to unlock
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @unlocked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional): * @unlocked: (out) (element-type Gio.DBusProxy) (transfer full) (nullable) (optional):
* location to place list of items or collections that were unlocked * location to place list of items or collections that were unlocked
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Unlock items or collections in the secret service. * Unlock items or collections in the secret service.
@ -1117,7 +1121,7 @@ on_store_service (GObject *source,
* @schema: (nullable): the schema to use to check attributes * @schema: (nullable): the schema to use to check attributes
* @attributes: (element-type utf8 utf8): the attribute keys and values * @attributes: (element-type utf8 utf8): the attribute keys and values
* @collection: (nullable): a collection alias, or D-Bus object path of the * @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 * @label: label for the secret
* @value: the secret value * @value: the secret value
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -1237,7 +1241,7 @@ secret_service_store_finish (SecretService *service,
* @schema: (nullable): the schema for the attributes * @schema: (nullable): the schema for the attributes
* @attributes: (element-type utf8 utf8): the attribute keys and values * @attributes: (element-type utf8 utf8): the attribute keys and values
* @collection: (nullable): a collection alias, or D-Bus object path of the * @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 * @label: label for the secret
* @value: the secret value * @value: the secret value
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -1875,8 +1879,9 @@ on_set_alias_service (GObject *source,
* @callback: called when the operation completes * @callback: called when the operation completes
* @user_data: data to pass to the callback * @user_data: data to pass to the callback
* *
* Assign a collection to this alias. Aliases help determine * Assign a collection to this alias.
* well known collections, such as 'default'. *
* Aliases help determine well known collections, such as 'default'.
* *
* If @service is %NULL, then [func@Service.get] will be called to get * If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy. * the default [class@Service] proxy.

14
libsecret/secret-password.c
View File

@ -27,7 +27,7 @@
* secret_password_store: (skip) * secret_password_store: (skip)
* @schema: the schema for attributes * @schema: the schema for attributes
* @collection: (nullable): a collection alias, or D-Bus object path of the * @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 * @label: label for the secret
* @password: the null-terminated password to store * @password: the null-terminated password to store
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -159,7 +159,7 @@ on_store_backend (GObject *source,
* @schema: (nullable): the schema for attributes * @schema: (nullable): the schema for attributes
* @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values * @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values
* @collection: (nullable): a collection alias, or D-Bus object path of the * @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 * @label: label for the secret
* @password: the null-terminated password to store * @password: the null-terminated password to store
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -273,7 +273,7 @@ secret_password_store_binary (const SecretSchema *schema,
* @schema: (nullable): the schema for attributes * @schema: (nullable): the schema for attributes
* @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values * @attributes: (element-type utf8 utf8) (transfer full): the attribute keys and values
* @collection: (nullable): a collection alias, or D-Bus object path of the * @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 * @label: label for the secret
* @value: a [struct@Value] * @value: a [struct@Value]
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -348,7 +348,7 @@ secret_password_store_finish (GAsyncResult *result,
* secret_password_store_sync: * secret_password_store_sync:
* @schema: the schema for attributes * @schema: the schema for attributes
* @collection: (nullable): a collection alias, or D-Bus object path of the * @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 * @label: label for the secret
* @password: the null-terminated password to store * @password: the null-terminated password to store
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -413,7 +413,7 @@ secret_password_store_sync (const SecretSchema *schema,
* @schema: (nullable): the schema for attributes * @schema: (nullable): the schema for attributes
* @attributes: (element-type utf8 utf8): the attribute keys and values * @attributes: (element-type utf8 utf8): the attribute keys and values
* @collection: (nullable): a collection alias, or D-Bus object path of the * @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 * @label: label for the secret
* @password: the null-terminated password to store * @password: the null-terminated password to store
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -477,7 +477,7 @@ secret_password_storev_sync (const SecretSchema *schema,
* secret_password_store_binary_sync: * secret_password_store_binary_sync:
* @schema: the schema for attributes * @schema: the schema for attributes
* @collection: (nullable): a collection alias, or D-Bus object path of the * @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 * @label: label for the secret
* @value: a [struct@Value] * @value: a [struct@Value]
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -535,7 +535,7 @@ secret_password_store_binary_sync (const SecretSchema *schema,
* @schema: (nullable): the schema for attributes * @schema: (nullable): the schema for attributes
* @attributes: (element-type utf8 utf8): the attribute keys and values * @attributes: (element-type utf8 utf8): the attribute keys and values
* @collection: (nullable): a collection alias, or D-Bus object path of the * @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 * @label: label for the secret
* @value: a [struct@Value] * @value: a [struct@Value]
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object

105
libsecret/secret-paths.c
View File

@ -112,7 +112,7 @@ secret_collection_new_for_dbus_path_finish (GAsyncResult *result,
* *
* Get a new collection proxy for a collection in the secret service. * Get a new collection proxy for a collection in the secret service.
* *
* If @service is %NULL, then [funcService.get_sync] will be called to get * If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy. * the default [class@Service] proxy.
* *
* This method may block indefinitely and should not be used in user interface * This method may block indefinitely and should not be used in user interface
@ -163,7 +163,7 @@ secret_collection_new_for_dbus_path_sync (SecretService *service,
* *
* Get a new item proxy for a secret item in the secret service. * Get a new item proxy for a secret item in the secret service.
* *
* If @service is %NULL, then [funcService.get] will be called to get * If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy. * the default [class@Service] proxy.
* *
* This method will return immediately and complete asynchronously. * This method will return immediately and complete asynchronously.
@ -240,7 +240,7 @@ secret_item_new_for_dbus_path_finish (GAsyncResult *result,
* *
* Get a new item proxy for a secret item in the secret service. * Get a new item proxy for a secret item in the secret service.
* *
* If @service is %NULL, then [funcService.get_sync] will be called to get * If @service is %NULL, then [func@Service.get_sync] will be called to get
* the default [class@Service] proxy. * the default [class@Service] proxy.
* *
* This method may block indefinitely and should not be used in user interface * This method may block indefinitely and should not be used in user interface
@ -311,8 +311,10 @@ on_search_items_complete (GObject *source,
* @user_data: data to pass to the callback * @user_data: data to pass to the callback
* *
* Search for items in @collection matching the @attributes, and return their * Search for items in @collection matching the @attributes, and return their
* DBus object paths. Only the specified collection is searched. The @attributes * DBus object paths.
* should be a table of string keys and string values. *
* Only the specified collection is searched. The @attributes should be a table
* of string keys and string values.
* *
* This function returns immediately and completes asynchronously. * This function returns immediately and completes asynchronously.
* *
@ -406,8 +408,9 @@ secret_collection_search_for_dbus_paths_finish (SecretCollection *collection,
* @error: location to place error on failure * @error: location to place error on failure
* *
* Search for items matching the @attributes in @collection, and return their * Search for items matching the @attributes in @collection, and return their
* DBus object paths. The @attributes should be a table of string keys and * DBus object paths.
* string values. *
* The @attributes should be a table of string keys and string values.
* *
* This function may block indefinitely. Use the asynchronous version * This function may block indefinitely. Use the asynchronous version
* in user interface threads. * in user interface threads.
@ -462,6 +465,7 @@ secret_collection_search_for_dbus_paths_sync (SecretCollection *collection,
* @user_data: data to pass to the callback * @user_data: data to pass to the callback
* *
* Search for items matching the @attributes, and return their D-Bus object paths. * Search for items matching the @attributes, and return their D-Bus object paths.
*
* All collections are searched. The @attributes should be a table of string keys * All collections are searched. The @attributes should be a table of string keys
* and string values. * and string values.
* *
@ -528,11 +532,11 @@ _secret_service_search_for_paths_variant (SecretService *self,
* @self: the secret service * @self: the secret service
* @result: asynchronous result passed to callback * @result: asynchronous result passed to callback
* @unlocked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable): * @unlocked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
* location to place an array of D-Bus object paths for matching * location to place an array of D-Bus object paths for matching
* items which were locked. * items which were locked.
* @locked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable): * @locked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
* location to place an array of D-Bus object paths for matching * location to place an array of D-Bus object paths for matching
* items which were locked. * items which were locked.
* @error: location to place error on failure * @error: location to place error on failure
* *
* Complete asynchronous operation to search for items, and return their * Complete asynchronous operation to search for items, and return their
@ -592,16 +596,18 @@ secret_service_search_for_dbus_paths_finish (SecretService *self,
* @attributes: (element-type utf8 utf8): search for items matching these attributes * @attributes: (element-type utf8 utf8): search for items matching these attributes
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @unlocked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable): * @unlocked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
* location to place an array of D-Bus object paths for matching * location to place an array of D-Bus object paths for matching
* items which were locked. * items which were locked.
* @locked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable): * @locked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
* location to place an array of D-Bus object paths for matching * location to place an array of D-Bus object paths for matching
* items which were locked. * items which were locked.
* @error: location to place error on failure * @error: location to place error on failure
* *
* Search for items matching the @attributes, and return their D-Bus object * Search for items matching the @attributes, and return their D-Bus object
* paths. All collections are searched. The @attributes should be a table of * paths.
* string keys and string values. *
* All collections are searched. The @attributes should be a table of string
* keys and string values.
* *
* This function may block indefinitely. Use the asynchronous version * This function may block indefinitely. Use the asynchronous version
* in user interface threads. * in user interface threads.
@ -904,7 +910,7 @@ secret_service_get_secrets_for_dbus_paths (SecretService *self,
* Stability: Unstable * Stability: Unstable
* *
* Returns: (transfer full) (element-type utf8 Secret.Value): a newly * Returns: (transfer full) (element-type utf8 Secret.Value): a newly
* allocated hash table of item_path keys to [struct@Value] * allocated hash table of item path keys to [struct@Value]
* values. * values.
*/ */
GHashTable * GHashTable *
@ -1135,8 +1141,8 @@ _secret_service_xlock_paths_finish (SecretService *self,
* @paths: (array zero-terminated=1): the D-Bus object paths of the items or collections to lock * @paths: (array zero-terminated=1): the D-Bus object paths of the items or collections to lock
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @locked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable): * @locked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
* location to place array of D-Bus paths of items or collections * location to place array of D-Bus paths of items or collections
* that were locked * that were locked
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Lock items or collections in the secret service. * Lock items or collections in the secret service.
@ -1231,8 +1237,8 @@ secret_service_lock_dbus_paths (SecretService *self,
* @self: the secret service * @self: the secret service
* @result: asynchronous result passed to the callback * @result: asynchronous result passed to the callback
* @locked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable): * @locked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
* location to place array of D-Bus paths of items or collections * location to place array of D-Bus paths of items or collections
* that were locked * that were locked
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Complete asynchronous operation to lock items or collections in the secret * Complete asynchronous operation to lock items or collections in the secret
@ -1262,11 +1268,11 @@ secret_service_lock_dbus_paths_finish (SecretService *self,
* secret_service_unlock_dbus_paths_sync: (skip) * secret_service_unlock_dbus_paths_sync: (skip)
* @self: the secret service * @self: the secret service
* @paths: (array zero-terminated=1): the D-Bus object paths of the items or * @paths: (array zero-terminated=1): the D-Bus object paths of the items or
* collections to unlock * collections to unlock
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @unlocked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable): * @unlocked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
* location to place array of D-Bus paths of items or collections * location to place array of D-Bus paths of items or collections
* that were unlocked * that were unlocked
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Unlock items or collections in the secret service. * Unlock items or collections in the secret service.
@ -1322,7 +1328,7 @@ secret_service_unlock_dbus_paths_sync (SecretService *self,
* secret_service_unlock_dbus_paths: (skip) * secret_service_unlock_dbus_paths: (skip)
* @self: the secret service * @self: the secret service
* @paths: (array zero-terminated=1): the D-Bus paths for items or * @paths: (array zero-terminated=1): the D-Bus paths for items or
* collections to unlock * collections to unlock
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @callback: called when the operation completes * @callback: called when the operation completes
* @user_data: data to pass to the callback * @user_data: data to pass to the callback
@ -1363,8 +1369,8 @@ secret_service_unlock_dbus_paths (SecretService *self,
* @self: the secret service * @self: the secret service
* @result: asynchronous result passed to the callback * @result: asynchronous result passed to the callback
* @unlocked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable): * @unlocked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
* location to place array of D-Bus paths of items or collections * location to place array of D-Bus paths of items or collections
* that were unlocked * that were unlocked
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Complete asynchronous operation to unlock items or collections in the secret * Complete asynchronous operation to unlock items or collections in the secret
@ -1688,9 +1694,9 @@ on_create_collection_called (GObject *source,
* secret_service_create_collection_dbus_path: (skip) * secret_service_create_collection_dbus_path: (skip)
* @self: a secret service object * @self: a secret service object
* @properties: (element-type utf8 GLib.Variant): hash table of properties for * @properties: (element-type utf8 GLib.Variant): hash table of properties for
* the new collection * the new collection
* @alias: (nullable): an alias to check for before creating the new * @alias: (nullable): an alias to check for before creating the new
* collection, or to assign to the new collection * collection, or to assign to the new collection
* @flags: not currently used * @flags: not currently used
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @callback: called when the operation completes * @callback: called when the operation completes
@ -1805,9 +1811,9 @@ secret_service_create_collection_dbus_path_finish (SecretService *self,
* secret_service_create_collection_dbus_path_sync: (skip) * secret_service_create_collection_dbus_path_sync: (skip)
* @self: a secret service object * @self: a secret service object
* @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties
* for the new collection * for the new collection
* @alias: (nullable): an alias to check for before creating the new * @alias: (nullable): an alias to check for before creating the new
* collection, or to assign to the new collection * collection, or to assign to the new collection
* @flags: not currently used * @flags: not currently used
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @error: location to place an error on failure * @error: location to place an error on failure
@ -1837,7 +1843,7 @@ secret_service_create_collection_dbus_path_finish (SecretService *self,
* Stability: Unstable * Stability: Unstable
* *
* Returns: (transfer full): a new string containing the D-Bus object path * Returns: (transfer full): a new string containing the D-Bus object path
* of the collection * of the collection
*/ */
gchar * gchar *
secret_service_create_collection_dbus_path_sync (SecretService *self, secret_service_create_collection_dbus_path_sync (SecretService *self,
@ -1992,7 +1998,7 @@ on_create_item_session (GObject *source,
* @self: a secret service object * @self: a secret service object
* @collection_path: the D-Bus object path of the collection in which to create item * @collection_path: the D-Bus object path of the collection in which to create item
* @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties
* for the new collection * for the new collection
* @value: the secret value to store in the item * @value: the secret value to store in the item
* @flags: flags for the creation of the new item * @flags: flags for the creation of the new item
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -2114,7 +2120,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result,
* @self: a secret service object * @self: a secret service object
* @collection_path: the D-Bus path of the collection in which to create item * @collection_path: the D-Bus path of the collection in which to create item
* @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties * @properties: (element-type utf8 GLib.Variant): hash table of D-Bus properties
* for the new collection * for the new collection
* @value: the secret value to store in the item * @value: the secret value to store in the item
* @flags: flags for the creation of the new item * @flags: flags for the creation of the new item
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
@ -2143,7 +2149,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result,
* Stability: Unstable * Stability: Unstable
* *
* Returns: (transfer full): a new string containing the D-Bus object path * Returns: (transfer full): a new string containing the D-Bus object path
* of the item * of the item
*/ */
gchar * gchar *
secret_service_create_item_dbus_path_sync (SecretService *self, secret_service_create_item_dbus_path_sync (SecretService *self,
@ -2187,9 +2193,10 @@ secret_service_create_item_dbus_path_sync (SecretService *self,
* @callback: called when the operation completes * @callback: called when the operation completes
* @user_data: data to pass to the callback * @user_data: data to pass to the callback
* *
* Lookup which collection is assigned to this alias. Aliases help determine * Lookup which collection is assigned to this alias.
* well known collections, such as 'default'. This method looks up the *
* dbus object path of the well known collection. * Aliases help determine well known collections, such as 'default'. This method
* looks up the dbus object path of the well known collection.
* *
* This method will return immediately and complete asynchronously. * This method will return immediately and complete asynchronously.
* *
@ -2219,7 +2226,9 @@ secret_service_read_alias_dbus_path (SecretService *self,
* @error: location to place error on failure * @error: location to place error on failure
* *
* Finish an asynchronous operation to lookup which collection is assigned * Finish an asynchronous operation to lookup which collection is assigned
* to an alias. This method returns the DBus object path of the collection * to an alias.
*
* This method returns the DBus object path of the collection
* *
* Stability: Unstable * Stability: Unstable
* *
@ -2258,9 +2267,10 @@ secret_service_read_alias_dbus_path_finish (SecretService *self,
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @error: location to place error on failure * @error: location to place error on failure
* *
* Lookup which collection is assigned to this alias. Aliases help determine * Lookup which collection is assigned to this alias.
* well known collections, such as 'default'. This method returns the dbus *
* object path of the collection. * Aliases help determine well known collections, such as 'default'. This method
* returns the dbus object path of the collection.
* *
* This method may block and should not be used in user interface threads. * This method may block and should not be used in user interface threads.
* *
@ -2375,13 +2385,14 @@ secret_service_set_alias_to_dbus_path_finish (SecretService *self,
* @self: a secret service object * @self: a secret service object
* @alias: the alias to assign the collection to * @alias: the alias to assign the collection to
* @collection_path: (nullable): the D-Bus object path of the collection to * @collection_path: (nullable): the D-Bus object path of the collection to
* assign to the alias * assign to the alias
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @error: location to place error on failure * @error: location to place error on failure
* *
* Assign a collection to this alias. Aliases help determine * Assign a collection to this alias.
* well known collections, such as 'default'. This method takes the dbus object *
* path of the collection to assign to the alias. * Aliases help determine well known collections, such as 'default'. This method
* takes the dbus object path of the collection to assign to the alias.
* *
* This method may block and should not be used in user interface threads. * This method may block and should not be used in user interface threads.
* *

23
libsecret/secret-prompt.c
View File

@ -119,10 +119,11 @@ _secret_prompt_instance (SecretService *service,
* @return_type: the variant type of the prompt result * @return_type: the variant type of the prompt result
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Runs a prompt and performs the prompting. Returns a variant result if the * Runs a prompt and performs the prompting.
* 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 * Returns a variant result if the prompt was completed and not dismissed. The
* API specification. * type of result depends on the action the prompt is completing, and is defined
* in the Secret Service DBus API specification.
* *
* If @window_id is non-null then it is used as an XWindow id on Linux. The API * 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 `%d` printf format. The * expects this id to be converted to a string using the `%d` printf format. The
@ -179,10 +180,11 @@ secret_prompt_run (SecretPrompt *self,
* @return_type: the variant type of the prompt result * @return_type: the variant type of the prompt result
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Runs a prompt and performs the prompting. Returns a variant result if the * Runs a prompt and performs the prompting.
* 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 * Returns a variant result if the prompt was completed and not dismissed. The
* API specification. * type of result depends on the action the prompt is completing, and is defined
* in the Secret Service DBus API specification.
* *
* If @window_id is non-null then it is used as an XWindow id on Linux. The API * 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 `%d` printf format. The * expects this id to be converted to a string using the `%d` printf format. The
@ -402,8 +404,9 @@ on_prompt_cancelled (GCancellable *cancellable,
* @callback: called when the operation completes * @callback: called when the operation completes
* @user_data: data to be passed to the callback * @user_data: data to be passed to the callback
* *
* Runs a prompt and performs the prompting. Returns %TRUE if the prompt * Runs a prompt and performs the prompting.
* was completed and not dismissed. *
* Returns %TRUE if the prompt was completed and not dismissed.
* *
* If @window_id is non-null then it is used as an XWindow id on Linux. The API * 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 `%d` printf format. The * expects this id to be converted to a string using the `%d` printf format. The

33
libsecret/secret-retrievable.c
View File

@ -18,9 +18,9 @@
#include "secret-private.h" #include "secret-private.h"
/** /**
* SecretRetrievable * SecretRetrievable:
* *
* A read-only secret item * A read-only view of a secret item in the Secret Service.
* *
* #SecretRetrievable provides a read-only view of a secret item * #SecretRetrievable provides a read-only view of a secret item
* stored in the Secret Service. * stored in the Secret Service.
@ -30,13 +30,6 @@
* [method@Retrievable.retrieve_secret_finish]. * [method@Retrievable.retrieve_secret_finish].
* *
* Stability: Stable * Stability: Stable
*/
/**
* SecretRetrievable:
*
* An object representing a read-only view of a secret item in the
* Secret Service.
* *
* Since: 0.19.0 * Since: 0.19.0
*/ */
@ -45,9 +38,9 @@
* SecretRetrievableInterface: * SecretRetrievableInterface:
* @parent_iface: the parent interface * @parent_iface: the parent interface
* @retrieve_secret: implementation of [method@Retrievable.retrieve_secret], * @retrieve_secret: implementation of [method@Retrievable.retrieve_secret],
* required * required
* @retrieve_secret_finish: implementation of * @retrieve_secret_finish: implementation of
* [method@Retrievable.retrieve_secret_finish], required * [method@Retrievable.retrieve_secret_finish], required
* *
* The interface for #SecretRetrievable. * The interface for #SecretRetrievable.
* *
@ -62,8 +55,10 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface)
/** /**
* SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full) (attributes org.gtk.Property.get=secret_retrievable_get_attributes) * 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 * The attributes set on this item.
* item. They are not guaranteed to be stored or transferred securely. *
* Attributes are used to locate an item. They are not guaranteed to be
* stored or transferred securely.
* *
* Since: 0.19.0 * Since: 0.19.0
*/ */
@ -266,8 +261,10 @@ secret_retrievable_get_label (SecretRetrievable *self)
* secret_retrievable_get_created: (attributes org.gtk.Method.get_property=created) * secret_retrievable_get_created: (attributes org.gtk.Method.get_property=created)
* @self: a retrievable object * @self: a retrievable object
* *
* Get the created date and time of the object. The return value is * Get the created date and time of the object.
* the number of seconds since the unix epoch, January 1st 1970. *
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
* *
* Returns: the created date and time * Returns: the created date and time
* *
@ -288,8 +285,10 @@ secret_retrievable_get_created (SecretRetrievable *self)
* secret_retrievable_get_modified: (attributes org.gtk.Method.get_property=modified) * secret_retrievable_get_modified: (attributes org.gtk.Method.get_property=modified)
* @self: a retrievable object * @self: a retrievable object
* *
* Get the modified date and time of the object. The return value is * Get the modified date and time of the object.
* the number of seconds since the unix epoch, January 1st 1970. *
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
* *
* Returns: the modified date and time * Returns: the modified date and time
* *

78
libsecret/secret-schema.c
View File

@ -22,11 +22,74 @@
#include "egg/egg-secure-memory.h" #include "egg/egg-secure-memory.h"
/**
* 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 [struct@GLib.HashTable] with
* string keys and values. Even for values that defined as an integer or boolean in
* the schema, the attribute values in the [struct@GLib.HashTable] 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.
*
* Additional schemas can be defined via the %SecretSchema structure like this:
*
* ```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;
* }
* ```
*
* Stability: Stable
*/
/** /**
* SecretSchemaFlags: * SecretSchemaFlags:
* @SECRET_SCHEMA_NONE: no flags for the schema * @SECRET_SCHEMA_NONE: no flags for the schema
* @SECRET_SCHEMA_DONT_MATCH_NAME: don't match the schema name when looking up or * @SECRET_SCHEMA_DONT_MATCH_NAME: don't match the schema name when looking up or
* removing passwords * removing passwords
* *
* Flags for a #SecretSchema definition. * Flags for a #SecretSchema definition.
*/ */
@ -45,9 +108,11 @@
* @SECRET_SCHEMA_ATTRIBUTE_INTEGER: an integer attribute, stored as a decimal * @SECRET_SCHEMA_ATTRIBUTE_INTEGER: an integer attribute, stored as a decimal
* @SECRET_SCHEMA_ATTRIBUTE_STRING: a utf-8 string attribute * @SECRET_SCHEMA_ATTRIBUTE_STRING: a utf-8 string attribute
* *
* The type of an attribute in a #SecretSchema. Attributes are stored as strings * The type of an attribute in a [struct@SecretSchema].
* in the Secret Service, and the attribute types simply define standard ways *
* to store integer and boolean values as strings. * 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.
*/ */
static SecretSchemaAttribute * static SecretSchemaAttribute *
@ -269,8 +334,9 @@ _secret_schema_ref_if_nonstatic (const SecretSchema *schema)
* secret_schema_unref: * secret_schema_unref:
* @schema: the schema to reference * @schema: the schema to reference
* *
* Releases a reference to the #SecretSchema. If the last reference is * Releases a reference to the #SecretSchema.
* released then the schema will be freed. *
* If the last reference is released then the schema will be freed.
* *
* It is not normally necessary to call this function from C code, and is * It is not normally necessary to call this function from C code, and is
* mainly present for the sake of bindings. It is an error to call this for * mainly present for the sake of bindings. It is an error to call this for

49
libsecret/secret-service.c
View File

@ -76,16 +76,16 @@
* SecretServiceClass: * SecretServiceClass:
* @parent_class: the parent class * @parent_class: the parent class
* @collection_gtype: the [alias@GLib.Type] of the [class@Collection] objects instantiated * @collection_gtype: the [alias@GLib.Type] of the [class@Collection] objects instantiated
* by the #SecretService proxy * by the #SecretService proxy
* @item_gtype: the [alias@GLib.Type] of the [class@Item] objects instantiated by the * @item_gtype: the [alias@GLib.Type] of the [class@Item] objects instantiated by the
* #SecretService proxy * #SecretService proxy
* @prompt_async: called to perform asynchronous prompting when necessary * @prompt_async: called to perform asynchronous prompting when necessary
* @prompt_finish: called to complete an asynchronous prompt operation * @prompt_finish: called to complete an asynchronous prompt operation
* @prompt_sync: called to perform synchronous prompting when necessary * @prompt_sync: called to perform synchronous prompting when necessary
* @get_collection_gtype: called to get the GObject type for collections * @get_collection_gtype: called to get the GObject type for collections
* instantiated by the #SecretService proxy * instantiated by the #SecretService proxy
* @get_item_gtype: called to get the GObject type for collections * @get_item_gtype: called to get the GObject type for collections
* instantiated by the #SecretService proxy * instantiated by the #SecretService proxy
* *
* The class for #SecretService. * The class for #SecretService.
*/ */
@ -94,9 +94,9 @@
* SecretServiceFlags: * SecretServiceFlags:
* @SECRET_SERVICE_NONE: no flags for initializing the #SecretService * @SECRET_SERVICE_NONE: no flags for initializing the #SecretService
* @SECRET_SERVICE_OPEN_SESSION: establish a session for transfer of secrets * @SECRET_SERVICE_OPEN_SESSION: establish a session for transfer of secrets
* while initializing the #SecretService * while initializing the #SecretService
* @SECRET_SERVICE_LOAD_COLLECTIONS: load collections while initializing the * @SECRET_SERVICE_LOAD_COLLECTIONS: load collections while initializing the
* #SecretService * #SecretService
* *
* Flags which determine which parts of the #SecretService proxy are initialized * Flags which determine which parts of the #SecretService proxy are initialized
* during a [func@Service.get] or [func@Service.open] operation. * during a [func@Service.get] or [func@Service.open] operation.
@ -585,8 +585,9 @@ secret_service_class_init (SecretServiceClass *klass)
* SecretService:collections: (attributes org.gtk.Property.get=secret_service_get_collections) * SecretService:collections: (attributes org.gtk.Property.get=secret_service_get_collections)
* *
* A list of [class@Collection] 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 * the Secret Service.
* not been loaded. *
* This list may be %NULL if the collections have not been loaded.
* *
* To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS * To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS
* initialization flag when calling the [func@Service.get] or * initialization flag when calling the [func@Service.get] or
@ -946,8 +947,9 @@ secret_service_backend_iface (SecretBackendInterface *iface)
* @callback: called when the operation completes * @callback: called when the operation completes
* @user_data: data to be passed to the callback * @user_data: data to be passed to the callback
* *
* Get a #SecretService proxy for the Secret Service. If such a proxy object * Get a #SecretService proxy for the Secret Service.
* already exists, then the same proxy is returned. *
* If such a proxy object already exists, then the same proxy is returned.
* *
* If @flags contains any flags of which parts of the secret service to * If @flags contains any flags of which parts of the secret service to
* ensure are initialized, then those will be initialized before completing. * ensure are initialized, then those will be initialized before completing.
@ -1043,8 +1045,9 @@ secret_service_get_finish (GAsyncResult *result,
* @cancellable: (nullable): optional cancellation object * @cancellable: (nullable): optional cancellation object
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Get a #SecretService proxy for the Secret Service. If such a proxy object * Get a #SecretService proxy for the Secret Service.
* already exists, then the same proxy is returned. *
* If such a proxy object already exists, then the same proxy is returned.
* *
* If @flags contains any flags of which parts of the secret service to * If @flags contains any flags of which parts of the secret service to
* ensure are initialized, then those will be initialized before returning. * ensure are initialized, then those will be initialized before returning.
@ -1362,7 +1365,7 @@ _secret_service_take_session (SecretService *self,
* [method@Service.ensure_session] to establish a session. * [method@Service.ensure_session] to establish a session.
* *
* Returns: (nullable): a string representing the algorithms for transferring * Returns: (nullable): a string representing the algorithms for transferring
* secrets * secrets
*/ */
const gchar * const gchar *
secret_service_get_session_algorithms (SecretService *self) secret_service_get_session_algorithms (SecretService *self)
@ -1419,7 +1422,9 @@ secret_service_get_session_dbus_path (SecretService *self)
* @user_data: data to be passed to the callback * @user_data: data to be passed to the callback
* *
* Ensure that the #SecretService proxy has established a session with the * Ensure that the #SecretService proxy has established a session with the
* Secret Service. This session is used to transfer secrets. * Secret Service.
*
* This session is used to transfer secrets.
* *
* It is not normally necessary to call this method, as the session is * 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 * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION
@ -1491,7 +1496,9 @@ secret_service_ensure_session_finish (SecretService *self,
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Ensure that the #SecretService proxy has established a session with the * Ensure that the #SecretService proxy has established a session with the
* Secret Service. This session is used to transfer secrets. * Secret Service.
*
* This session is used to transfer secrets.
* *
* It is not normally necessary to call this method, as the session is * 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 * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION
@ -1632,8 +1639,9 @@ on_ensure_collection (GObject *source,
* @user_data: data to be passed to the callback * @user_data: data to be passed to the callback
* *
* Ensure that the #SecretService proxy has loaded all the collections present * Ensure that the #SecretService proxy has loaded all the collections present
* in the Secret Service. This affects the result of * in the Secret Service.
* [method@Service.get_collections]. *
* This affects the result of [method@Service.get_collections].
* *
* You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to
* [func@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
@ -1729,8 +1737,9 @@ secret_service_load_collections_finish (SecretService *self,
* @error: location to place an error on failure * @error: location to place an error on failure
* *
* Ensure that the #SecretService proxy has loaded all the collections present * Ensure that the #SecretService proxy has loaded all the collections present
* in the Secret Service. This affects the result of * in the Secret Service.
* [method@Service.get_collections]. *
* This affects the result of [method@Service.get_collections].
* *
* You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to
* [func@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
@ -1908,6 +1917,7 @@ secret_service_prompt_finish (SecretService *self,
* @self: the secret service * @self: the secret service
* *
* Get the GObject type for collections instantiated by this service. * Get the GObject type for collections instantiated by this service.
*
* This will always be either [class@Collection] or derived from it. * This will always be either [class@Collection] or derived from it.
* *
* Returns: the gobject type for collections * Returns: the gobject type for collections
@ -1936,6 +1946,7 @@ secret_service_get_collection_gtype (SecretService *self)
* @self: the service * @self: the service
* *
* Get the GObject type for items instantiated by this service. * Get the GObject type for items instantiated by this service.
*
* This will always be either [class@Item] or derived from it. * This will always be either [class@Item] or derived from it.
* *
* Returns: the gobject type for items * Returns: the gobject type for items

43
libsecret/secret-util.c
View File

@ -19,37 +19,23 @@
#include <string.h> #include <string.h>
/**
* 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
* to the application to handle them appropriately.
*
* Stability: Stable
*/
/**
* SECRET_ERROR:
*
* The error domain quark which denotes libsecret specific errors from the
* #SecretError enumeration.
*/
/** /**
* SecretError: * SecretError:
* @SECRET_ERROR_PROTOCOL: received an invalid data or message from the Secret * @SECRET_ERROR_PROTOCOL: received an invalid data or message from the Secret
* Service * Service
* @SECRET_ERROR_IS_LOCKED: the item or collection is locked and the operation * @SECRET_ERROR_IS_LOCKED: the item or collection is locked and the operation
* cannot be performed * cannot be performed
* @SECRET_ERROR_NO_SUCH_OBJECT: no such item or collection found in the * @SECRET_ERROR_NO_SUCH_OBJECT: no such item or collection found in the Secret
* Secret Service * Service
* @SECRET_ERROR_ALREADY_EXISTS: a relevant item or collection already exists * @SECRET_ERROR_ALREADY_EXISTS: a relevant item or collection already exists
* @SECRET_ERROR_INVALID_FILE_FORMAT: the file format is not valid
* *
* Errors returned by the Secret Service. None of the errors are appropriate * Errors returned by the Secret Service.
* for display to the user. *
* None of the errors are appropriate for display to the user. It is up to the
* application to handle them appropriately.
*
* Stability: Stable
*/ */
static void static void
@ -86,6 +72,13 @@ _secret_list_get_type (void)
} }
/**
* secret_error_get_quark:
*
* Get the error quark.
*
* Returns: the quark
*/
GQuark GQuark
secret_error_get_quark (void) secret_error_get_quark (void)
{ {

36
libsecret/secret-value.c
View File

@ -75,8 +75,9 @@ secret_value_get_type (void)
* @length: the length of the data * @length: the length of the data
* @content_type: the content type of the data * @content_type: the content type of the data
* *
* Create a #SecretValue for the secret data passed in. The secret data is * Create a #SecretValue for the secret data passed in.
* copied into non-pageable 'secure' memory. *
* The secret data is copied into non-pageable 'secure' memory.
* *
* If the length is less than zero, then @secret is assumed to be * If the length is less than zero, then @secret is assumed to be
* null-terminated. * null-terminated.
@ -110,8 +111,10 @@ secret_value_new (const gchar *secret,
* @content_type: the content type of the data * @content_type: the content type of the data
* @destroy: function to call to free the secret data * @destroy: function to call to free the secret data
* *
* Create a #SecretValue for the secret data passed in. The secret data is * Create a #SecretValue for the secret data passed in.
* not copied, and will later be freed with the @destroy function. *
* The secret data is not copied, and will later be freed with the @destroy
* function.
* *
* If the length is less than zero, then @secret is assumed to be * If the length is less than zero, then @secret is assumed to be
* null-terminated. * null-terminated.
@ -146,9 +149,11 @@ secret_value_new_full (gchar *secret,
* @value: the value * @value: the value
* @length: the length of the secret * @length: the length of the secret
* *
* Get the secret data in the #SecretValue. The value is not necessarily * Get the secret data in the #SecretValue.
* null-terminated unless it was created with [ctor@Value.new] or a *
* null-terminated string was passed to [ctor@Value.new_full]. * The value is not necessarily 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 * Returns: (array length=length) (element-type guint8): the secret data
*/ */
@ -167,7 +172,9 @@ secret_value_get (SecretValue *value,
* @value: the value * @value: the value
* *
* Get the secret data in the #SecretValue if it contains a textual * Get the secret data in the #SecretValue if it contains a textual
* value. The content type must be `text/plain`. * value.
*
* The content type must be `text/plain`.
* *
* Returns: (nullable): the content type * Returns: (nullable): the content type
*/ */
@ -202,8 +209,10 @@ secret_value_get_content_type (SecretValue *value)
* secret_value_ref: * secret_value_ref:
* @value: value to reference * @value: value to reference
* *
* Add another reference to the #SecretValue. For each reference * Add another reference to the #SecretValue.
* [method@Value.unref] should be called to unreference the value. *
* For each reference [method@Value.unref] should be called to unreference the
* value.
* *
* Returns: (transfer full): the value * Returns: (transfer full): the value
*/ */
@ -219,8 +228,9 @@ secret_value_ref (SecretValue *value)
* secret_value_unref: * secret_value_unref:
* @value: (type Secret.Value): value to unreference * @value: (type Secret.Value): value to unreference
* *
* Unreference a #SecretValue. When the last reference is gone, then * Unreference a #SecretValue.
* the value will be freed. *
* When the last reference is gone, then the value will be freed.
*/ */
void void
secret_value_unref (gpointer value) secret_value_unref (gpointer value)
@ -253,7 +263,7 @@ is_password_value (SecretValue *value)
/** /**
* secret_value_unref_to_password: * secret_value_unref_to_password:
* @value: the value * @value: the value
* @length: the length of the secret * @length: (inout): the length of the secret
* *
* Unreference a #SecretValue and steal the secret data in * Unreference a #SecretValue and steal the secret data in
* #SecretValue as nonpageable memory. * #SecretValue as nonpageable memory.

4
libsecret/secret-version.h.in
View File

@ -46,8 +46,8 @@
* @minor: minor version to be satisfied * @minor: minor version to be satisfied
* @micro: micro version to be satisfied * @micro: micro version to be satisfied
* *
* Returns: %TRUE if using libsecret is newer than or equal to the * Returns `TRUE` if using libsecret is newer than or equal to the
* given version * given version.
*/ */
#define SECRET_CHECK_VERSION(major, minor, micro) \ #define SECRET_CHECK_VERSION(major, minor, micro) \
(SECRET_MAJOR_VERSION > (major) || \ (SECRET_MAJOR_VERSION > (major) || \