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

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

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
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
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
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/libsecret/-/blob/master"
base_url = "https://gitlab.gnome.org/GNOME/libsecret/-/blob/master/"
[extra]
# 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-value.c',
'secret-value.h',
'secret-util.c',
]
libsecret_gir_sources += version_h
libsecret_gir_sources += _enums_generated

25
libsecret/secret-backend.c
View File

@ -25,20 +25,12 @@
#include "libsecret/secret-enum-types.h"
/**
* SecretBackend
*
* A backend implementation of password storage
* SecretBackend:
*
* #SecretBackend represents a backend implementation of password
* storage.
*
* Stability: Stable
*/
/**
* SecretBackend:
*
* An object representing a backend implementation of password storage.
*
* Since: 0.19.0
*/
@ -66,15 +58,21 @@
* SecretBackendFlags:
* @SECRET_BACKEND_NONE: no flags for initializing the #SecretBackend
* @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
* #SecretBackend
* #SecretBackend
*
* Flags which determine which parts of the #SecretBackend are initialized.
*
* 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_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
* @user_data: data to be passed to the callback
*
* Get a #SecretBackend instance. If such a backend already exists,
* then the same backend is returned.
* Get a #SecretBackend instance.
*
* 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
* ensure are initialized, then those will be initialized before completing.

28
libsecret/secret-collection.c
View File

@ -70,16 +70,19 @@
/**
* SECRET_COLLECTION_DEFAULT:
*
* An alias to the default collection. This can be passed to
* [func@password_store] [func@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 [func@password_store],
* [func@Collection.for_alias] or similar functions.
* the session.
*
* This can be passed to [func@password_store], [func@Collection.for_alias] or
* similar functions.
*/
enum {
@ -759,8 +762,9 @@ on_load_item (GObject *source,
* @user_data: data to be passed to the callback
*
* Ensure that the #SecretCollection proxy has loaded all the items present
* in the Secret Service. This affects the result of
* [method@Collection.get_items].
* in the Secret Service.
*
* This affects the result of [method@Collection.get_items].
*
* For collections returned from [method@Service.get_collections] the items will
* 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)
* @self: a collection
*
* Get the created date and time of the collection. The return value is
* the number of seconds since the unix epoch, January 1st 1970.
* Get the created date and time of the collection.
*
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
*
* 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)
* @self: a collection
*
* Get the modified date and time of the collection. The return value is
* the number of seconds since the unix epoch, January 1st 1970.
* Get the modified date and time of the collection.
*
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
*
* 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)
*
* 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");
@ -371,8 +373,10 @@ secret_item_class_init (SecretItemClass *klass)
/**
* 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.
* 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 [method@Service.lock] or
* [method@Service.unlock] functions.
@ -588,8 +592,10 @@ secret_item_async_initable_iface (GAsyncInitableIface *iface)
* secret_item_refresh:
* @self: the collection
*
* Refresh the properties on this item. This fires off a request to
* refresh, and the properties will be updated later.
* Refresh the properties on this item.
*
* 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
* will notify the client when properties change.
@ -1046,8 +1052,10 @@ secret_item_get_service (SecretItem *self)
* secret_item_get_secret:
* @self: an item
*
* 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.
* 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 [method@Item.load_secret] method.
*
@ -1988,8 +1996,10 @@ secret_item_get_locked (SecretItem *self)
* secret_item_get_created:
* @self: an item
*
* Get the created date and time of the item. The return value is
* the number of seconds since the unix epoch, January 1st 1970.
* Get the created date and time of the item.
*
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
*
* Returns: the created date and time
*/
@ -2014,8 +2024,10 @@ secret_item_get_created (SecretItem *self)
* secret_item_get_modified:
* @self: an item
*
* Get the modified date and time of the item. The return value is
* the number of seconds since the unix epoch, January 1st 1970.
* Get the modified date and time of the item.
*
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
*
* 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
* @user_data: data to pass to the callback
*
* Search for items matching the @attributes. All collections are searched.
* The @attributes should be a table of string keys and string values.
* Search for items matching the @attributes.
*
* 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
* the default [class@Service] proxy.
@ -410,8 +412,10 @@ service_load_items_sync (SecretService *service,
* @cancellable: (nullable): optional cancellation object
* @error: location to place error on failure
*
* Search for items matching the @attributes. All collections are searched.
* The @attributes should be a table of string keys and string values.
* Search for items matching the @attributes.
*
* 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
* the default [class@Service] proxy.
@ -760,7 +764,7 @@ secret_service_lock (SecretService *service,
* @service: (nullable): the secret service
* @result: asynchronous result passed to the callback
* @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
*
* 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
* @cancellable: (nullable): optional cancellation object
* @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
*
* Lock items or collections in the secret service.
@ -874,7 +878,7 @@ secret_service_unlock (SecretService *service,
* @service: (nullable): the secret service
* @result: asynchronous result passed to the callback
* @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
*
* 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
* @cancellable: (nullable): optional cancellation object
* @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
*
* 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
* @attributes: (element-type utf8 utf8): the attribute keys and values
* @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: the secret value
* @cancellable: (nullable): optional cancellation object
@ -1237,7 +1241,7 @@ secret_service_store_finish (SecretService *service,
* @schema: (nullable): the schema for the attributes
* @attributes: (element-type utf8 utf8): the attribute keys and values
* @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: the secret value
* @cancellable: (nullable): optional cancellation object
@ -1875,8 +1879,9 @@ on_set_alias_service (GObject *source,
* @callback: called when the operation completes
* @user_data: data to pass to the callback
*
* Assign a collection to this alias. Aliases help determine
* well known collections, such as 'default'.
* Assign a collection to this alias.
*
* Aliases help determine well known collections, such as 'default'.
*
* If @service is %NULL, then [func@Service.get] will be called to get
* the default [class@Service] proxy.

14
libsecret/secret-password.c
View File

@ -27,7 +27,7 @@
* secret_password_store: (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
* @password: the null-terminated password to store
* @cancellable: (nullable): optional cancellation object
@ -159,7 +159,7 @@ on_store_backend (GObject *source,
* @schema: (nullable): the schema for attributes
* @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 where to store the secret
* collection where to store the secret
* @label: label for the secret
* @password: the null-terminated password to store
* @cancellable: (nullable): optional cancellation object
@ -273,7 +273,7 @@ secret_password_store_binary (const SecretSchema *schema,
* @schema: (nullable): the schema for attributes
* @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 where to store the secret
* collection where to store the secret
* @label: label for the secret
* @value: a [struct@Value]
* @cancellable: (nullable): optional cancellation object
@ -348,7 +348,7 @@ secret_password_store_finish (GAsyncResult *result,
* secret_password_store_sync:
* @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
* @password: the null-terminated password to store
* @cancellable: (nullable): optional cancellation object
@ -413,7 +413,7 @@ secret_password_store_sync (const SecretSchema *schema,
* @schema: (nullable): the schema for attributes
* @attributes: (element-type utf8 utf8): the attribute keys and values
* @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
* @password: the null-terminated password to store
* @cancellable: (nullable): optional cancellation object
@ -477,7 +477,7 @@ secret_password_storev_sync (const SecretSchema *schema,
* secret_password_store_binary_sync:
* @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 [struct@Value]
* @cancellable: (nullable): optional cancellation object
@ -535,7 +535,7 @@ secret_password_store_binary_sync (const SecretSchema *schema,
* @schema: (nullable): the schema for attributes
* @attributes: (element-type utf8 utf8): the attribute keys and values
* @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 [struct@Value]
* @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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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
*
* Search for items in @collection matching the @attributes, and return their
* DBus object paths. Only the specified collection is searched. The @attributes
* should be a table of string keys and string values.
* DBus object paths.
*
* 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.
*
@ -406,8 +408,9 @@ secret_collection_search_for_dbus_paths_finish (SecretCollection *collection,
* @error: location to place error on failure
*
* Search for items matching the @attributes in @collection, and return their
* DBus object paths. The @attributes should be a table of string keys and
* string values.
* DBus object paths.
*
* The @attributes should be a table of string keys and string values.
*
* This function may block indefinitely. Use the asynchronous version
* 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
*
* Search for items matching the @attributes, and return their D-Bus object paths.
*
* All collections are searched. The @attributes should be a table of string keys
* and string values.
*
@ -528,11 +532,11 @@ _secret_service_search_for_paths_variant (SecretService *self,
* @self: the secret service
* @result: asynchronous result passed to callback
* @unlocked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
* location to place an array of D-Bus object paths for matching
* items which were locked.
* location to place an array of D-Bus object paths for matching
* items which were locked.
* @locked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
* location to place an array of D-Bus object paths for matching
* items which were locked.
* location to place an array of D-Bus object paths for matching
* items which were locked.
* @error: location to place error on failure
*
* Complete asynchronous operation to search for items, 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
* @cancellable: (nullable): optional cancellation object
* @unlocked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
* location to place an array of D-Bus object paths for matching
* items which were locked.
* location to place an array of D-Bus object paths for matching
* items which were locked.
* @locked: (out) (transfer full) (array zero-terminated=1) (optional) (nullable):
* location to place an array of D-Bus object paths for matching
* items which were locked.
* location to place an array of D-Bus object paths for matching
* items which were locked.
* @error: location to place error on failure
*
* Search for items matching the @attributes, and return their D-Bus object
* paths. All collections are searched. The @attributes should be a table of
* string keys and string values.
* paths.
*
* 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
* in user interface threads.
@ -904,7 +910,7 @@ 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 [struct@Value]
* allocated hash table of item path keys to [struct@Value]
* values.
*/
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
* @cancellable: (nullable): optional cancellation object
* @locked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
* location to place array of D-Bus paths of items or collections
* that were locked
* location to place array of D-Bus paths of items or collections
* that were locked
* @error: location to place an error on failure
*
* Lock items or collections in the secret service.
@ -1231,8 +1237,8 @@ secret_service_lock_dbus_paths (SecretService *self,
* @self: the secret service
* @result: asynchronous result passed to the callback
* @locked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
* location to place array of D-Bus paths of items or collections
* that were locked
* location to place array of D-Bus paths of items or collections
* that were locked
* @error: location to place an error on failure
*
* 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)
* @self: the secret service
* @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
* @unlocked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
* location to place array of D-Bus paths of items or collections
* that were unlocked
* location to place array of D-Bus paths of items or collections
* that were unlocked
* @error: location to place an error on failure
*
* Unlock items or collections in the secret service.
@ -1322,7 +1328,7 @@ secret_service_unlock_dbus_paths_sync (SecretService *self,
* secret_service_unlock_dbus_paths: (skip)
* @self: the secret service
* @paths: (array zero-terminated=1): the D-Bus paths for items or
* collections to unlock
* collections to unlock
* @cancellable: (nullable): optional cancellation object
* @callback: called when the operation completes
* @user_data: data to pass to the callback
@ -1363,8 +1369,8 @@ secret_service_unlock_dbus_paths (SecretService *self,
* @self: the secret service
* @result: asynchronous result passed to the callback
* @unlocked: (out) (array zero-terminated=1) (transfer full) (optional) (nullable):
* location to place array of D-Bus paths of items or collections
* that were unlocked
* location to place array of D-Bus paths of items or collections
* that were unlocked
* @error: location to place an error on failure
*
* 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)
* @self: a secret service object
* @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
* collection, or to assign to the new collection
* collection, or to assign to the new collection
* @flags: not currently used
* @cancellable: (nullable): optional cancellation object
* @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)
* @self: a secret service object
* @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
* collection, or to assign to the new collection
* collection, or to assign to the new collection
* @flags: not currently used
* @cancellable: (nullable): optional cancellation object
* @error: location to place an error on failure
@ -1837,7 +1843,7 @@ secret_service_create_collection_dbus_path_finish (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_sync (SecretService *self,
@ -1992,7 +1998,7 @@ on_create_item_session (GObject *source,
* @self: a secret service object
* @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
* for the new collection
* for the new collection
* @value: the secret value to store in the item
* @flags: flags for the creation of the new item
* @cancellable: (nullable): optional cancellation object
@ -2114,7 +2120,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result,
* @self: a secret service object
* @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
* for the new collection
* for the new collection
* @value: the secret value to store in the item
* @flags: flags for the creation of the new item
* @cancellable: (nullable): optional cancellation object
@ -2143,7 +2149,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result,
* 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_sync (SecretService *self,
@ -2187,9 +2193,10 @@ secret_service_create_item_dbus_path_sync (SecretService *self,
* @callback: called when the operation completes
* @user_data: data to pass to the callback
*
* Lookup which collection is assigned to this alias. Aliases help determine
* well known collections, such as 'default'. This method looks up the
* dbus object path of the well known collection.
* Lookup which collection is assigned to this alias.
*
* 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.
*
@ -2219,7 +2226,9 @@ secret_service_read_alias_dbus_path (SecretService *self,
* @error: location to place error on failure
*
* 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
*
@ -2258,9 +2267,10 @@ secret_service_read_alias_dbus_path_finish (SecretService *self,
* @cancellable: (nullable): optional cancellation object
* @error: location to place error on failure
*
* Lookup which collection is assigned to this alias. Aliases help determine
* well known collections, such as 'default'. This method returns the dbus
* object path of the collection.
* Lookup which collection is assigned to this alias.
*
* 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.
*
@ -2375,13 +2385,14 @@ secret_service_set_alias_to_dbus_path_finish (SecretService *self,
* @self: a secret service object
* @alias: the alias to assign 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
* @error: location to place error on failure
*
* Assign a collection to this 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.
* Assign a collection to this 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.
*

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
* @error: location to place an error on failure
*
* 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
* action the prompt is completing, and is defined in the Secret Service DBus
* API specification.
* 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 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
* 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
* @error: location to place an error on failure
*
* 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
* action the prompt is completing, and is defined in the Secret Service DBus
* API specification.
* 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 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
* 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
* @user_data: data to be passed to the callback
*
* Runs a prompt and performs the prompting. Returns %TRUE if the prompt
* was completed and not dismissed.
* Runs a prompt and performs the prompting.
*
* 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
* 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"
/**
* 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
* stored in the Secret Service.
@ -30,13 +30,6 @@
* [method@Retrievable.retrieve_secret_finish].
*
* Stability: Stable
*/
/**
* SecretRetrievable:
*
* An object representing a read-only view of a secret item in the
* Secret Service.
*
* Since: 0.19.0
*/
@ -45,9 +38,9 @@
* SecretRetrievableInterface:
* @parent_iface: the parent interface
* @retrieve_secret: implementation of [method@Retrievable.retrieve_secret],
* required
* required
* @retrieve_secret_finish: implementation of
* [method@Retrievable.retrieve_secret_finish], required
* [method@Retrievable.retrieve_secret_finish], required
*
* 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)
*
* The attributes set on this item. Attributes are used to locate an
* item. They are not guaranteed to be stored or transferred securely.
* The attributes set on this item.
*
* Attributes are used to locate an item. They are not guaranteed to be
* stored or transferred securely.
*
* 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)
* @self: a retrievable object
*
* Get the created date and time of the object. The return value is
* the number of seconds since the unix epoch, January 1st 1970.
* Get the created date and time of the object.
*
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
*
* 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)
* @self: a retrievable object
*
* Get the modified date and time of the object. The return value is
* the number of seconds since the unix epoch, January 1st 1970.
* Get the modified date and time of the object.
*
* The return value is the number of seconds since the unix epoch, January 1st
* 1970.
*
* Returns: the modified date and time
*

78
libsecret/secret-schema.c
View File

@ -22,11 +22,74 @@
#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:
* @SECRET_SCHEMA_NONE: no flags for the schema
* @SECRET_SCHEMA_DONT_MATCH_NAME: don't match the schema name when looking up or
* removing passwords
* removing passwords
*
* Flags for a #SecretSchema definition.
*/
@ -45,9 +108,11 @@
* @SECRET_SCHEMA_ATTRIBUTE_INTEGER: an integer attribute, stored as a decimal
* @SECRET_SCHEMA_ATTRIBUTE_STRING: a utf-8 string attribute
*
* The type of an attribute in a #SecretSchema. 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.
* The type of an attribute in a [struct@SecretSchema].
*
* 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 *
@ -269,8 +334,9 @@ _secret_schema_ref_if_nonstatic (const SecretSchema *schema)
* secret_schema_unref:
* @schema: the schema to reference
*
* Releases a reference to the #SecretSchema. If the last reference is
* released then the schema will be freed.
* Releases a reference to the #SecretSchema.
*
* 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
* 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:
* @parent_class: the parent class
* @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
* #SecretService proxy
* #SecretService proxy
* @prompt_async: called to perform asynchronous prompting when necessary
* @prompt_finish: called to complete an asynchronous prompt operation
* @prompt_sync: called to perform synchronous prompting when necessary
* @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
* instantiated by the #SecretService proxy
* instantiated by the #SecretService proxy
*
* The class for #SecretService.
*/
@ -94,9 +94,9 @@
* SecretServiceFlags:
* @SECRET_SERVICE_NONE: no flags for initializing the #SecretService
* @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
* #SecretService
* #SecretService
*
* Flags which determine which parts of the #SecretService proxy are initialized
* 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)
*
* 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.
* 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 [func@Service.get] or
@ -946,8 +947,9 @@ secret_service_backend_iface (SecretBackendInterface *iface)
* @callback: called when the operation completes
* @user_data: data to be passed to the callback
*
* Get a #SecretService proxy for the Secret Service. If such a proxy object
* already exists, then the same proxy is returned.
* Get a #SecretService proxy for the Secret Service.
*
* 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
* 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
* @error: location to place an error on failure
*
* Get a #SecretService proxy for the Secret Service. If such a proxy object
* already exists, then the same proxy is returned.
* Get a #SecretService proxy for the Secret Service.
*
* 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
* 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.
*
* Returns: (nullable): a string representing the algorithms for transferring
* secrets
* secrets
*/
const gchar *
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
*
* 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
* 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
*
* 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
* 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
*
* Ensure that the #SecretService proxy has loaded all the collections present
* in the Secret Service. This affects the result of
* [method@Service.get_collections].
* in the Secret Service.
*
* This affects the result of [method@Service.get_collections].
*
* You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to
* [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
*
* Ensure that the #SecretService proxy has loaded all the collections present
* in the Secret Service. This affects the result of
* [method@Service.get_collections].
* in the Secret Service.
*
* This affects the result of [method@Service.get_collections].
*
* You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to
* [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
*
* Get the GObject type for collections instantiated by this service.
*
* This will always be either [class@Collection] or derived from it.
*
* Returns: the gobject type for collections
@ -1936,6 +1946,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 [class@Item] or derived from it.
*
* Returns: the gobject type for items

43
libsecret/secret-util.c
View File

@ -19,37 +19,23 @@
#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:
* @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
* cannot be performed
* @SECRET_ERROR_NO_SUCH_OBJECT: no such item or collection found in the
* Secret Service
* cannot be performed
* @SECRET_ERROR_NO_SUCH_OBJECT: no such item or collection found in the Secret
* Service
* @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
* for display to the user.
* Errors returned by the Secret Service.
*
* 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
@ -86,6 +72,13 @@ _secret_list_get_type (void)
}
/**
* secret_error_get_quark:
*
* Get the error quark.
*
* Returns: the quark
*/
GQuark
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
* @content_type: the content type of the data
*
* Create a #SecretValue for the secret data passed in. The secret data is
* copied into non-pageable 'secure' memory.
* Create a #SecretValue for the secret data passed in.
*
* The secret data is copied into non-pageable 'secure' memory.
*
* If the length is less than zero, then @secret is assumed to be
* null-terminated.
@ -110,8 +111,10 @@ secret_value_new (const gchar *secret,
* @content_type: the content type of the data
* @destroy: function to call to free the secret data
*
* Create a #SecretValue for the secret data passed in. The secret data is
* not copied, and will later be freed with the @destroy function.
* Create a #SecretValue for the secret data passed in.
*
* 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
* null-terminated.
@ -146,9 +149,11 @@ secret_value_new_full (gchar *secret,
* @value: the value
* @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 [ctor@Value.new] or a
* null-terminated string was passed to [ctor@Value.new_full].
* Get the secret data in the #SecretValue.
*
* 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
*/
@ -167,7 +172,9 @@ 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 `text/plain`.
* value.
*
* The content type must be `text/plain`.
*
* Returns: (nullable): the content type
*/
@ -202,8 +209,10 @@ secret_value_get_content_type (SecretValue *value)
* secret_value_ref:
* @value: value to reference
*
* Add another reference to the #SecretValue. For each reference
* [method@Value.unref] should be called to unreference the value.
* Add another reference to the #SecretValue.
*
* For each reference [method@Value.unref] should be called to unreference the
* value.
*
* Returns: (transfer full): the value
*/
@ -219,8 +228,9 @@ secret_value_ref (SecretValue *value)
* secret_value_unref:
* @value: (type Secret.Value): value to unreference
*
* Unreference a #SecretValue. When the last reference is gone, then
* the value will be freed.
* Unreference a #SecretValue.
*
* When the last reference is gone, then the value will be freed.
*/
void
secret_value_unref (gpointer value)
@ -253,7 +263,7 @@ is_password_value (SecretValue *value)
/**
* secret_value_unref_to_password:
* @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
* #SecretValue as nonpageable memory.

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

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