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

secret-schema: Add missind docs

Browse Source
This commit is contained in:
Maximiliano Sandoval R 2022-02-05 20:28:34 +01:00
parent e762e39dfc
commit 868a88ffe8
No known key found for this signature in database
GPG Key ID: D64A8D747F6FE706
2 changed files with 63 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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.

63
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