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

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

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

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

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

76
libsecret/secret-schema.c
View File

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

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

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