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

21
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
*/ */
@ -75,6 +67,12 @@
* 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
*/ */

17
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.
@ -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.

51
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.
* *
@ -600,8 +604,10 @@ secret_service_search_for_dbus_paths_finish (SecretService *self,
* @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 *
@ -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.
* *
@ -2379,9 +2389,10 @@ secret_service_set_alias_to_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
* *
* 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

29
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
*/ */
@ -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
* *

76
libsecret/secret-schema.c
View File

@ -22,6 +22,69 @@
#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
@ -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

35
libsecret/secret-service.c
View File

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

39
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) || \