From 868a88ffe851df3eaf65f10b39d50e58d3bd9f36 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval R Date: Sat, 5 Feb 2022 20:28:34 +0100 Subject: secret-schema: Add missind docs --- docs/reference/libsecret/libsecret-simple-api.md | 55 --------------------- libsecret/secret-schema.c | 63 ++++++++++++++++++++++++ 2 files changed, 63 insertions(+), 55 deletions(-) diff --git a/docs/reference/libsecret/libsecret-simple-api.md b/docs/reference/libsecret/libsecret-simple-api.md index b6fda5e..11cf8fe 100644 --- a/docs/reference/libsecret/libsecret-simple-api.md +++ b/docs/reference/libsecret/libsecret-simple-api.md @@ -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. diff --git a/libsecret/secret-schema.c b/libsecret/secret-schema.c index 32967bf..3c7f51a 100644 --- a/libsecret/secret-schema.c +++ b/libsecret/secret-schema.c @@ -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 -- cgit v1.2.1