SecretSchema: Libsecret Library Reference Manual

## SecretSchema SecretSchema — Schema for defining which attributes are on items |

## Functions

SecretSchema * | secret_schema_new ()
SecretSchema * | secret_schema_newv ()
SecretSchema * | secret_schema_ref ()
void | secret_schema_unref ()

## Types and Values

extern const SecretSchema * | SECRET_SCHEMA_NOTE
extern const SecretSchema * | SECRET_SCHEMA_COMPAT_NETWORK
| SecretSchema
enum | SecretSchemaFlags
| SecretSchemaAttribute
enum | SecretSchemaAttributeType

## Includes

    #include <libsecret/secret.h>

## Description

Each password is associated with a set of attributes. Attribute values can be either strings, integers or booleans.

The names and types of allowed attributes for a given password are defined with a schema.

Additional schemas can be defined via the `SecretSchema` structure like this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    /* 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;
    }

## Functions

### secret_schema_new ()

    SecretSchema *
    secret_schema_new (const gchar *name,
                       SecretSchemaFlags flags,
                       ...);

Using this function is not normally necessary from C code.

A schema 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 an `name` like "org.gnome.keyring.NetworkPassword", and defines a set of attributes names, and types (string, integer, boolean) for those attributes.

The variable argument list should contain pairs of a) The attribute name as a null-terminated string, followed by b) integers from the SecretSchemaAttributeType enumeration, representing the attribute type for each attribute name. The list of attribtues should be terminated with a `NULL`.

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.

[skip]

#### Parameters

name | the dotted name of the schema |
flags | the flags for the schema |
... | the attribute names and types, terminated with `NULL` |

#### Returns

the new schema, which should be unreferenced with `secret_schema_unref()` when done.

[transfer full]

### secret_schema_newv ()

    SecretSchema *
    secret_schema_newv (const gchar *name,
                        SecretSchemaFlags flags,
                        GHashTable *attribute_names_and_types);

Using this function is not normally necessary from C code. This is useful for constructing SecretSchema structures in bindings.

A schema 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 an `name` like "org.gnome.keyring.NetworkPassword", and defines a set of attributes names, and types (string, integer, boolean) for those attributes.

Each key in the `attributes` table should be a attribute name strings, and the values in the table should be integers from the SecretSchemaAttributeType enumeration, representing the attribute type for each attribute name.

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.

[rename-to secret_schema_new]

#### Parameters

name | the dotted name of the schema |
flags | the flags for the schema |
attribute_names_and_types | the attribute names and types of those attributes. | [element-type utf8 Secret.SchemaAttributeType]

#### Returns

the new schema, which should be unreferenced with `secret_schema_unref()` when done.

[transfer full]

### secret_schema_ref ()

    SecretSchema *
    secret_schema_ref (SecretSchema *schema);

Adds a reference to the SecretSchema.

It is not normally necessary to call this function from C code, and is mainly present for the sake of bindings. If the `schema` was statically allocated, then this function will copy the schema.

#### Parameters

schema | the schema to reference |

#### Returns

the referenced schema, which should be later unreferenced with `secret_schema_unref()`.

[transfer full]

### secret_schema_unref ()

    void
    secret_schema_unref (SecretSchema *schema);

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 a `schema` that was statically allocated.

#### Parameters

schema | the schema to reference |

## Types and Values

### SECRET_SCHEMA_NOTE

    extern const SecretSchema *  SECRET_SCHEMA_NOTE;

A predefined schema for personal passwords stored by the user in the password manager. This schema has no attributes, and the items are not meant to be used automatically by applications.

When used to search for items using this schema, it will only match items that have the same schema. Items stored via libgnome-keyring with the `GNOME_KEYRING_ITEM_NOTE` item type will match.

### SECRET_SCHEMA_COMPAT_NETWORK

    extern const SecretSchema *  SECRET_SCHEMA_COMPAT_NETWORK;

A predefined schema that is compatible with items stored via the libgnome-keyring 'network password' functions. This is meant to be used by applications migrating from libgnome-keyring which stored their secrets as 'network passwords'. It is not recommended that new code use this schema.

When used to search for items using this schema, it will only match items that have the same schema. Items stored via libgnome-keyring with the `GNOME_KEYRING_ITEM_NETWORK_PASSWORD` item type will match.

The following attributes exist in the schema:

Attributes:

`user`: | The user name (string).
`domain`: | The login domain or realm (string).
`object`: | The object or path (string).
`protocol`: | The protocol (a string like 'http').
`port`: | The network port (integer).
`server`: | The hostname or server (string).
`authtype`: | The authentication type (string).

### SecretSchema

    typedef struct {
    	const gchar *name;
    	SecretSchemaFlags flags;
    	SecretSchemaAttribute attributes[32];
    } 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 GHashTable with string keys and values. Even for values that defined as an integer or boolean in the schema, the attribute values in the GHashTable are strings. Boolean values are stored as the strings 'true' and 'false'. Integer values are stored in decimal, with a preceeding 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.

#### Members

const gchar *`name`; | the dotted name of the schema |
SecretSchemaFlags `flags`; | flags for the schema |
SecretSchemaAttribute `attributes`[32]; | the attribute names and types of those attributes |

Stability Level: Stable

### enum SecretSchemaFlags

Flags for a SecretSchema definition.

#### Members

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 |

### SecretSchemaAttribute

    typedef struct {
    	const gchar* name;
    	SecretSchemaAttributeType type;
    } SecretSchemaAttribute;

An attribute in a SecretSchema.

#### Members

const gchar *`name`; | name of the attribute |
SecretSchemaAttributeType `type`; | the type of the attribute |

### enum SecretSchemaAttributeType

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.

#### Members

SECRET_SCHEMA_ATTRIBUTE_STRING | a utf-8 string attribute |
SECRET_SCHEMA_ATTRIBUTE_INTEGER | an integer attribute, stored as a decimal |
SECRET_SCHEMA_ATTRIBUTE_BOOLEAN | a boolean attribute, stored as 'true' or 'false' |