SecretService: Libsecret Library Reference Manual

## SecretService SecretService — the Secret Service |

## Functions

void | secret_service_get ()
SecretService * | secret_service_get_sync ()
SecretService * | secret_service_get_finish ()
void | secret_service_disconnect ()
void | secret_service_open ()
SecretService * | secret_service_open_finish ()
SecretService * | secret_service_open_sync ()
GList * | secret_service_get_collections ()
SecretServiceFlags | secret_service_get_flags ()
const gchar * | secret_service_get_session_algorithms ()
void | secret_service_ensure_session ()
gboolean | secret_service_ensure_session_finish ()
gboolean | secret_service_ensure_session_sync ()
void | secret_service_load_collections ()
gboolean | secret_service_load_collections_finish ()
gboolean | secret_service_load_collections_sync ()
void | secret_service_search ()
GList * | secret_service_search_finish ()
GList * | secret_service_search_sync ()
void | secret_service_lock ()
gint | secret_service_lock_finish ()
gint | secret_service_lock_sync ()
void | secret_service_unlock ()
gint | secret_service_unlock_finish ()
gint | secret_service_unlock_sync ()
void | secret_service_store ()
gboolean | secret_service_store_finish ()
gboolean | secret_service_store_sync ()
void | secret_service_lookup ()
SecretValue * | secret_service_lookup_finish ()
SecretValue * | secret_service_lookup_sync ()
void | secret_service_clear ()
gboolean | secret_service_clear_finish ()
gboolean | secret_service_clear_sync ()
void | secret_service_prompt ()
GVariant * | secret_service_prompt_finish ()
GVariant * | secret_service_prompt_sync ()
void | secret_service_set_alias ()
gboolean | secret_service_set_alias_finish ()
gboolean | secret_service_set_alias_sync ()
GType | secret_service_get_collection_gtype ()
GType | secret_service_get_item_gtype ()

## Properties

SecretObjectList * | collections | Read

## Types and Values

struct | SecretService
struct | SecretServiceClass
enum | SecretServiceFlags
enum | SecretSearchFlags

## Object Hierarchy

        GFlags
        ╰── SecretServiceFlags
        GObject
        ╰── GDBusProxy
            ╰── SecretService

## Implemented Interfaces

SecretService implements GDBusInterface, GInitable, GAsyncInitable and SecretBackend.

## Includes

    #include <libsecret/secret.h>

## Description

A SecretService object represents the Secret Service implementation which runs as a D-Bus service.

Normally a single SecretService object can be shared between multiple callers. The `secret_service_get()` method is used to access this SecretService object. If a new independent SecretService object is required, use `secret_service_open()`.

In order to securely transfer secrets to the Sercret Service, a session is established. This session can be established while initializing a SecretService object by passing the `SECRET_SERVICE_OPEN_SESSION` flag to the `secret_service_get()` or `secret_service_open()` functions. In order to establish a session on an already existing SecretService, use the `secret_service_ensure_session()` function.

To search for items, use the `secret_service_search()` method.

Multiple collections can exist in the Secret Service, each of which contains secret items. In order to instantiate SecretCollection objects which represent those collections while initializing a SecretService then pass the `SECRET_SERVICE_LOAD_COLLECTIONS` flag to the `secret_service_get()` or `secret_service_open()` functions. In order to establish a session on an already existing SecretService, use the `secret_service_load_collections()` function. To access the list of collections use `secret_service_get_collections()`.

Certain actions on the Secret Service require user prompting to complete, such as creating a collection, or unlocking a collection. When such a prompt is necessary, then a SecretPrompt object is created by this library, and passed to the `secret_service_prompt()` method. In this way it is handled automatically.

In order to customize prompt handling, override the `prompt_async` and `prompt_finish` virtual methods of the SecretService class.

## Functions

### secret_service_get ()

    void
    secret_service_get (SecretServiceFlags flags,
                        GCancellable *cancellable,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

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.

This method will return immediately and complete asynchronously.

#### Parameters

flags | flags for which service functionality to ensure is initialized |
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to be passed to the callback |

### secret_service_get_sync ()

    SecretService *
    secret_service_get_sync (SecretServiceFlags flags,
                             GCancellable *cancellable,
                             GError **error);

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.

This method may block indefinitely and should not be used in user interface threads.

#### Parameters

flags | flags for which service functionality to ensure is initialized |
cancellable | optional cancellation object |
error | location to place an error on failure |

#### Returns

a new reference to a SecretService proxy, which should be released with `g_object_unref()`.

[transfer full]

### secret_service_get_finish ()

    SecretService *
    secret_service_get_finish (GAsyncResult *result,
                               GError **error);

Complete an asynchronous operation to get a SecretService proxy for the Secret Service.

#### Parameters

result | the asynchronous result passed to the callback |
error | location to place an error on failure |

#### Returns

a new reference to a SecretService proxy, which should be released with `g_object_unref()`.

[transfer full]

### secret_service_disconnect ()

    void
    secret_service_disconnect (void);

Disconnect the default SecretService proxy returned by `secret_service_get()` and `secret_service_get_sync()`.

It is not necessary to call this function, but you may choose to do so at program exit. It is useful for testing that memory is not leaked.

This function is safe to call at any time. But if other objects in this library are still referenced, then this will not result in all memory being freed.

### secret_service_open ()

    void
    secret_service_open (GType service_gtype,
                         const gchar *service_bus_name,
                         SecretServiceFlags flags,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Create a new SecretService proxy for the Secret Service.

This function is rarely used, see `secret_service_get()` instead.

The `service_gtype` argument should be set to `SECRET_TYPE_SERVICE` or a the type of a derived class.

If `flags` contains any flags of which parts of the secret service to ensure are initialized, then those will be initialized before returning.

If `service_bus_name` is `NULL` then the default is used.

This method will return immediately and complete asynchronously.

#### Parameters

service_gtype | the GType of the new secret service |
service_bus_name | the D-Bus service name of the secret service. | [allow-none]
flags | flags for which service functionality to ensure is initialized |
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to be passed to the callback |

### secret_service_open_finish ()

    SecretService *
    secret_service_open_finish (GAsyncResult *result,
                                GError **error);

Complete an asynchronous operation to create a new SecretService proxy for the Secret Service.

#### Parameters

result | the asynchronous result passed to the callback |
error | location to place an error on failure |

#### Returns

a new reference to a SecretService proxy, which should be released with `g_object_unref()`.

[transfer full]

### secret_service_open_sync ()

    SecretService *
    secret_service_open_sync (GType service_gtype,
                              const gchar *service_bus_name,
                              SecretServiceFlags flags,
                              GCancellable *cancellable,
                              GError **error);

Create a new SecretService proxy for the Secret Service.

This function is rarely used, see `secret_service_get_sync()` instead.

The `service_gtype` argument should be set to `SECRET_TYPE_SERVICE` or a the type of a derived class.

If `flags` contains any flags of which parts of the secret service to ensure are initialized, then those will be initialized before returning.

If `service_bus_name` is `NULL` then the default is used.

This method may block indefinitely and should not be used in user interface threads.

#### Parameters

service_gtype | the GType of the new secret service |
service_bus_name | the D-Bus service name of the secret service. | [allow-none]
flags | flags for which service functionality to ensure is initialized |
cancellable | optional cancellation object |
error | location to place an error on failure |

#### Returns

a new reference to a SecretService proxy, which should be released with `g_object_unref()`.

[transfer full]

### secret_service_get_collections ()

    GList *
    secret_service_get_collections (SecretService *self);

Get a list of SecretCollection objects representing all the collections in the secret service.

If the `SECRET_SERVICE_LOAD_COLLECTIONS` flag was not specified when initializing SecretService proxy object, then this method will return `NULL`. Use `secret_service_load_collections()` to load the collections.

#### Parameters

self | the secret service proxy |

#### Returns

a list of the collections in the secret service.

[transfer full][element-type Secret.Collection][allow-none]

### secret_service_get_flags ()

    SecretServiceFlags
    secret_service_get_flags (SecretService *self);

Get the flags representing what features of the SecretService proxy have been initialized.

Use `secret_service_ensure_session()` or `secret_service_load_collections()` to initialize further features and change the flags.

#### Parameters

self | the secret service proxy |

#### Returns

the flags for features initialized

### secret_service_get_session_algorithms ()

    const gchar *
    secret_service_get_session_algorithms (SecretService *self);

Get the set of algorithms being used to transfer secrets between this secret service proxy and the Secret Service itself.

This will be `NULL` if no session has been established. Use `secret_service_ensure_session()` to establish a session.

#### Parameters

self | the secret service proxy |

#### Returns

a string representing the algorithms for transferring secrets.

[allow-none]

### secret_service_ensure_session ()

    void
    secret_service_ensure_session (SecretService *self,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Ensure that the SecretService proxy has established a session with the 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` to `secret_service_get()` in order to ensure that a session has been established by the time you get the SecretService proxy.

This method will return immediately and complete asynchronously.

#### Parameters

self | the secret service |
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to be passed to the callback |

### secret_service_ensure_session_finish ()

    gboolean
    secret_service_ensure_session_finish (SecretService *self,
                                          GAsyncResult *result,
                                          GError **error);

Finish an asynchronous operation to ensure that the SecretService proxy has established a session with the Secret Service.

#### Parameters

self | the secret service |
result | the asynchronous result passed to the callback |
error | location to place an error on failure |

#### Returns

whether a session is established or not

### secret_service_ensure_session_sync ()

    gboolean
    secret_service_ensure_session_sync (SecretService *self,
                                        GCancellable *cancellable,
                                        GError **error);

Ensure that the SecretService proxy has established a session with the 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` to `secret_service_get_sync()` in order to ensure that a session has been established by the time you get the SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

#### Parameters

self | the secret service |
cancellable | optional cancellation object |
error | location to place an error on failure |

#### Returns

whether a session is established or not

### secret_service_load_collections ()

    void
    secret_service_load_collections (SecretService *self,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Ensure that the SecretService proxy has loaded all the collections present in the Secret Service. This affects the result of `secret_service_get_collections()`.

You can also pass the `SECRET_SERVICE_LOAD_COLLECTIONS` to `secret_service_get_sync()` in order to ensure that the collections have been loaded by the time you get the SecretService proxy.

This method will return immediately and complete asynchronously.

#### Parameters

self | the secret service |
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to be passed to the callback |

### secret_service_load_collections_finish ()

    gboolean
    secret_service_load_collections_finish
                                   (SecretService *self,
                                    GAsyncResult *result,
                                    GError **error);

Complete an asynchronous operation to ensure that the SecretService proxy has loaded all the collections present in the Secret Service.

#### Parameters

self | the secret service |
result | the asynchronous result passed to the callback |
error | location to place an error on failure |

#### Returns

whether the load was successful or not

### secret_service_load_collections_sync ()

    gboolean
    secret_service_load_collections_sync (SecretService *self,
                                          GCancellable *cancellable,
                                          GError **error);

Ensure that the SecretService proxy has loaded all the collections present in the Secret Service. This affects the result of `secret_service_get_collections()`.

You can also pass the `SECRET_SERVICE_LOAD_COLLECTIONS` to `secret_service_get_sync()` in order to ensure that the collections have been loaded by the time you get the SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

#### Parameters

self | the secret service |
cancellable | optional cancellation object |
error | location to place an error on failure |

#### Returns

whether the load was successful or not

### secret_service_search ()

    void
    secret_service_search (SecretService *service,
                           const SecretSchema *schema,
                           GHashTable *attributes,
                           SecretSearchFlags flags,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

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 `secret_service_get()` will be called to get the default SecretService proxy.

If `SECRET_SEARCH_ALL` is set in `flags` , then all the items matching the search will be returned. Otherwise only the first item will be returned. This is almost always the unlocked item that was most recently stored.

If `SECRET_SEARCH_UNLOCK` is set in `flags` , then items will be unlocked if necessary. In either case, locked and unlocked items will match the search and be returned. If the unlock fails, the search does not fail.

If `SECRET_SEARCH_LOAD_SECRETS` is set in `flags` , then the items will have their secret values loaded and available via `secret_item_get_secret()`.

This function returns immediately and completes asynchronously.

#### Parameters

service | the secret service. | [allow-none]
schema | the schema for the attributes. | [allow-none]
attributes | search for items matching these attributes. | [element-type utf8 utf8]
flags | search option flags |
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to pass to the callback |

### secret_service_search_finish ()

    GList *
    secret_service_search_finish (SecretService *service,
                                  GAsyncResult *result,
                                  GError **error);

Complete asynchronous operation to search for items.

#### Parameters

service | the secret service. | [allow-none]
result | asynchronous result passed to callback |
error | location to place error on failure |

#### Returns

a list of items that matched the search.

[transfer full][element-type Secret.Item]

### secret_service_search_sync ()

    GList *
    secret_service_search_sync (SecretService *service,
                                const SecretSchema *schema,
                                GHashTable *attributes,
                                SecretSearchFlags flags,
                                GCancellable *cancellable,
                                GError **error);

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 `secret_service_get_sync()` will be called to get the default SecretService proxy.

If `SECRET_SEARCH_ALL` is set in `flags` , then all the items matching the search will be returned. Otherwise only the first item will be returned. This is almost always the unlocked item that was most recently stored.

If `SECRET_SEARCH_UNLOCK` is set in `flags` , then items will be unlocked if necessary. In either case, locked and unlocked items will match the search and be returned. If the unlock fails, the search does not fail.

If `SECRET_SEARCH_LOAD_SECRETS` is set in `flags` , then the items' secret values will be loaded for any unlocked items. Loaded item secret values are available via `secret_item_get_secret()`. If the load of a secret values fail, then the

This function may block indefinitely. Use the asynchronous version in user interface threads.

#### Parameters

service | the secret service. | [allow-none]
schema | the schema for the attributes. | [allow-none]
attributes | search for items matching these attributes. | [element-type utf8 utf8]
flags | search option flags |
cancellable | optional cancellation object |
error | location to place error on failure |

#### Returns

a list of items that matched the search.

[transfer full][element-type Secret.Item]

### secret_service_lock ()

    void
    secret_service_lock (SecretService *service,
                         GList *objects,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Lock items or collections in the secret service.

The secret service may not be able to lock items individually, and may lock an entire collection instead.

If `service` is NULL, then `secret_service_get()` will be called to get the default SecretService proxy.

This method returns immediately and completes asynchronously. The secret service may prompt the user. `secret_service_prompt()` will be used to handle any prompts that show up.

#### Parameters

service | the secret service. | [allow-none]
objects | the items or collections to lock. | [element-type Gio.DBusProxy]
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to pass to the callback |

### secret_service_lock_finish ()

    gint
    secret_service_lock_finish (SecretService *service,
                                GAsyncResult *result,
                                GList **locked,
                                GError **error);

Complete asynchronous operation to lock items or collections in the secret service.

The secret service may not be able to lock items individually, and may lock an entire collection instead.

#### Parameters

service | the secret service. | [allow-none]
result | asynchronous result passed to the callback |
locked | location to place list of items or collections that were locked. | [out][element-type Gio.DBusProxy][transfer full][allow-none]
error | location to place an error on failure |

#### Returns

the number of items or collections that were locked

### secret_service_lock_sync ()

    gint
    secret_service_lock_sync (SecretService *service,
                              GList *objects,
                              GCancellable *cancellable,
                              GList **locked,
                              GError **error);

Lock items or collections in the secret service.

The secret service may not be able to lock items individually, and may lock an entire collection instead.

If `service` is NULL, then `secret_service_get_sync()` will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. `secret_service_prompt()` will be used to handle any prompts that show up.

#### Parameters

service | the secret service. | [allow-none]
objects | the items or collections to lock. | [element-type Gio.DBusProxy]
cancellable | optional cancellation object |
locked | location to place list of items or collections that were locked. | [out][element-type Gio.DBusProxy][transfer full][allow-none]
error | location to place an error on failure |

#### Returns

the number of items or collections that were locked

### secret_service_unlock ()

    void
    secret_service_unlock (SecretService *service,
                           GList *objects,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Unlock items or collections in the secret service.

The secret service may not be able to unlock items individually, and may unlock an entire collection instead.

If `service` is NULL, then `secret_service_get()` will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. `secret_service_prompt()` will be used to handle any prompts that show up.

#### Parameters

service | the secret service. | [allow-none]
objects | the items or collections to unlock. | [element-type Gio.DBusProxy]
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to pass to the callback |

### secret_service_unlock_finish ()

    gint
    secret_service_unlock_finish (SecretService *service,
                                  GAsyncResult *result,
                                  GList **unlocked,
                                  GError **error);

Complete asynchronous operation to unlock items or collections in the secret service.

The secret service may not be able to unlock items individually, and may unlock an entire collection instead.

#### Parameters

service | the secret service. | [allow-none]
result | asynchronous result passed to the callback |
unlocked | location to place list of items or collections that were unlocked. | [out][element-type Gio.DBusProxy][transfer full][allow-none]
error | location to place an error on failure |

#### Returns

the number of items or collections that were unlocked

### secret_service_unlock_sync ()

    gint
    secret_service_unlock_sync (SecretService *service,
                                GList *objects,
                                GCancellable *cancellable,
                                GList **unlocked,
                                GError **error);

Unlock items or collections in the secret service.

The secret service may not be able to unlock items individually, and may unlock an entire collection instead.

If `service` is NULL, then `secret_service_get_sync()` will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. `secret_service_prompt()` will be used to handle any prompts that show up.

#### Parameters

service | the secret service. | [allow-none]
objects | the items or collections to unlock. | [element-type Gio.DBusProxy]
cancellable | optional cancellation object |
unlocked | location to place list of items or collections that were unlocked. | [out][element-type Gio.DBusProxy][transfer full][allow-none]
error | location to place an error on failure |

#### Returns

the number of items or collections that were unlocked

### secret_service_store ()

    void
    secret_service_store (SecretService *service,
                          const SecretSchema *schema,
                          GHashTable *attributes,
                          const gchar *collection,
                          const gchar *label,
                          SecretValue *value,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Store a secret value in the secret service.

The `attributes` should be a set of key and value string pairs.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If `service` is NULL, then `secret_service_get()` will be called to get the default SecretService proxy.

If `collection` is not specified, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

This method will return immediately and complete asynchronously.

#### Parameters

service | the secret service. | [allow-none]
schema | the schema to use to check attributes. | [allow-none]
attributes | the attribute keys and values. | [element-type utf8 utf8]
collection | a collection alias, or D-Bus object path of the collection where to store the secret. | [allow-none]
label | label for the secret |
value | the secret value |
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to be passed to the callback |

### secret_service_store_finish ()

    gboolean
    secret_service_store_finish (SecretService *service,
                                 GAsyncResult *result,
                                 GError **error);

Finish asynchronous operation to store a secret value in the secret service.

#### Parameters

service | the secret service. | [allow-none]
result | the asynchronous result passed to the callback |
error | location to place an error on failure |

#### Returns

whether the storage was successful or not

### secret_service_store_sync ()

    gboolean
    secret_service_store_sync (SecretService *service,
                               const SecretSchema *schema,
                               GHashTable *attributes,
                               const gchar *collection,
                               const gchar *label,
                               SecretValue *value,
                               GCancellable *cancellable,
                               GError **error);

Store a secret value in the secret service.

The `attributes` should be a set of key and value string pairs.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If `collection` is `NULL`, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

If `service` is NULL, then `secret_service_get_sync()` will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

#### Parameters

service | the secret service. | [allow-none]
schema | the schema for the attributes. | [allow-none]
attributes | the attribute keys and values. | [element-type utf8 utf8]
collection | a collection alias, or D-Bus object path of the collection where to store the secret. | [allow-none]
label | label for the secret |
value | the secret value |
cancellable | optional cancellation object |
error | location to place an error on failure |

#### Returns

whether the storage was successful or not

### secret_service_lookup ()

    void
    secret_service_lookup (SecretService *service,
                           const SecretSchema *schema,
                           GHashTable *attributes,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Lookup a secret value in the secret service.

The `attributes` should be a set of key and value string pairs.

If `service` is NULL, then `secret_service_get()` will be called to get the default SecretService proxy.

This method will return immediately and complete asynchronously.

#### Parameters

service | the secret service. | [allow-none]
schema | the schema for the attributes. | [allow-none]
attributes | the attribute keys and values. | [element-type utf8 utf8]
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to be passed to the callback |

### secret_service_lookup_finish ()

    SecretValue *
    secret_service_lookup_finish (SecretService *service,
                                  GAsyncResult *result,
                                  GError **error);

Finish asynchronous operation to lookup a secret value in the secret service.

If no secret is found then `NULL` is returned.

#### Parameters

service | the secret service. | [allow-none]
result | the asynchronous result passed to the callback |
error | location to place an error on failure |

#### Returns

a newly allocated SecretValue, which should be released with `secret_value_unref()`, or `NULL` if no secret found.

[transfer full]

### secret_service_lookup_sync ()

    SecretValue *
    secret_service_lookup_sync (SecretService *service,
                                const SecretSchema *schema,
                                GHashTable *attributes,
                                GCancellable *cancellable,
                                GError **error);

Lookup a secret value in the secret service.

The `attributes` should be a set of key and value string pairs.

If `service` is NULL, then `secret_service_get_sync()` will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

#### Parameters

service | the secret service. | [allow-none]
schema | the schema for the attributes. | [allow-none]
attributes | the attribute keys and values. | [element-type utf8 utf8]
cancellable | optional cancellation object |
error | location to place an error on failure |

#### Returns

a newly allocated SecretValue, which should be released with `secret_value_unref()`, or `NULL` if no secret found.

[transfer full]

### secret_service_clear ()

    void
    secret_service_clear (SecretService *service,
                          const SecretSchema *schema,
                          GHashTable *attributes,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Remove unlocked items which match the attributes from the secret service.

The `attributes` should be a set of key and value string pairs.

If `service` is NULL, then `secret_service_get()` will be called to get the default SecretService proxy.

This method will return immediately and complete asynchronously.

#### Parameters

service | the secret service. | [allow-none]
schema | the schema for the attributes. | [allow-none]
attributes | the attribute keys and values. | [element-type utf8 utf8]
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to be passed to the callback |

### secret_service_clear_finish ()

    gboolean
    secret_service_clear_finish (SecretService *service,
                                 GAsyncResult *result,
                                 GError **error);

Finish asynchronous operation to remove items from the secret service.

#### Parameters

service | the secret service. | [allow-none]
result | the asynchronous result passed to the callback |
error | location to place an error on failure |

#### Returns

whether items were removed or not

### secret_service_clear_sync ()

    gboolean
    secret_service_clear_sync (SecretService *service,
                               const SecretSchema *schema,
                               GHashTable *attributes,
                               GCancellable *cancellable,
                               GError **error);

Remove unlocked items which match the attributes from the secret service.

The `attributes` should be a set of key and value string pairs.

If `service` is NULL, then `secret_service_get_sync()` will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

#### Parameters

service | the secret service. | [allow-none]
schema | the schema for the attributes. | [allow-none]
attributes | the attribute keys and values. | [element-type utf8 utf8]
cancellable | optional cancellation object |
error | location to place an error on failure |

#### Returns

whether items were removed or not

### secret_service_prompt ()

    void
    secret_service_prompt (SecretService *self,
                           SecretPrompt *prompt,
                           const GVariantType *return_type,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Perform prompting for a SecretPrompt.

This function is called by other parts of this library to handle prompts for the various actions that can require prompting.

Override the SecretServiceClass `prompt_async` virtual method to change the behavior of the prompting. The default behavior is to simply run `secret_prompt_perform()` on the prompt.

#### Parameters

self | the secret service |
prompt | the prompt |
return_type | the variant type of the prompt result. | [allow-none]
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to be passed to the callback |

### secret_service_prompt_finish ()

    GVariant *
    secret_service_prompt_finish (SecretService *self,
                                  GAsyncResult *result,
                                  GError **error);

Complete asynchronous operation to perform prompting for a SecretPrompt.

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.

#### Parameters

self | the secret service |
result | the asynchronous result passed to the callback |
error | location to place an error on failure |

#### Returns

`NULL` if the prompt was dismissed or an error occurred, a variant result if the prompt was successful.

[transfer full]

### secret_service_prompt_sync ()

    GVariant *
    secret_service_prompt_sync (SecretService *self,
                                SecretPrompt *prompt,
                                GCancellable *cancellable,
                                const GVariantType *return_type,
                                GError **error);

Perform prompting for a SecretPrompt.

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.

This function is called by other parts of this library to handle prompts for the various actions that can require prompting.

Override the SecretServiceClass `prompt_sync` virtual method to change the behavior of the prompting. The default behavior is to simply run `secret_prompt_perform_sync()` on the prompt with a `NULL` `window_id`.

#### Parameters

self | the secret service |
prompt | the prompt |
cancellable | optional cancellation object |
return_type | the variant type of the prompt result |
error | location to place an error on failure |

#### Returns

`NULL` if the prompt was dismissed or an error occurred, a variant result if the prompt was successful.

[transfer full]

### secret_service_set_alias ()

    void
    secret_service_set_alias (SecretService *service,
                              const gchar *alias,
                              SecretCollection *collection,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Assign a collection to this alias. Aliases help determine well known collections, such as 'default'.

If `service` is NULL, then `secret_service_get()` will be called to get the default SecretService proxy.

This method will return immediately and complete asynchronously.

#### Parameters

service | a secret service object. | [allow-none]
alias | the alias to assign the collection to |
collection | the collection to assign to the alias. | [allow-none]
cancellable | optional cancellation object. | [allow-none]
callback | called when the operation completes |
user_data | data to pass to the callback |

### secret_service_set_alias_finish ()

    gboolean
    secret_service_set_alias_finish (SecretService *service,
                                     GAsyncResult *result,
                                     GError **error);

Finish an asynchronous operation to assign a collection to an alias.

#### Parameters

service | a secret service object. | [allow-none]
result | asynchronous result passed to callback |
error | location to place error on failure |

#### Returns

`TRUE` if successful

### secret_service_set_alias_sync ()

    gboolean
    secret_service_set_alias_sync (SecretService *service,
                                   const gchar *alias,
                                   SecretCollection *collection,
                                   GCancellable *cancellable,
                                   GError **error);

Assign a collection to this alias. Aliases help determine well known collections, such as 'default'.

If `service` is NULL, then `secret_service_get_sync()` will be called to get the default SecretService proxy.

This method may block and should not be used in user interface threads.

#### Parameters

service | a secret service object. | [allow-none]
alias | the alias to assign the collection to |
collection | the collection to assign to the alias. | [allow-none]
cancellable | optional cancellation object. | [allow-none]
error | location to place error on failure |

#### Returns

`TRUE` if successful

### secret_service_get_collection_gtype ()

    GType
    secret_service_get_collection_gtype (SecretService *self);

Get the GObject type for collections instantiated by this service. This will always be either SecretCollection or derived from it.

#### Parameters

self | the secret service |

#### Returns

the gobject type for collections

### secret_service_get_item_gtype ()

    GType
    secret_service_get_item_gtype (SecretService *self);

Get the GObject type for items instantiated by this service. This will always be either SecretItem or derived from it.

#### Parameters

self | the service |

#### Returns

the gobject type for items

## Types and Values

### struct SecretService

    struct SecretService;

A proxy object representing the Secret Service.

### struct SecretServiceClass

    struct SecretServiceClass {
    	GDBusProxyClass parent_class;

    	GType collection_gtype;
    	GType item_gtype;

    	GVariant *  (* prompt_sync)      (SecretService *self,
    	                                  SecretPrompt *prompt,
    	                                  GCancellable *cancellable,
    	                                  const GVariantType *return_type,
    	                                  GError **error);

    	void        (* prompt_async)     (SecretService *self,
    	                                  SecretPrompt *prompt,
    	                                  const GVariantType *return_type,
    	                                  GCancellable *cancellable,
    	                                  GAsyncReadyCallback callback,
    	                                  gpointer user_data);

    	GVariant *  (* prompt_finish)    (SecretService *self,
    	                                  GAsyncResult *result,
    	                                  GError **error);

    	GType       (* get_collection_gtype)  (SecretService *self);

    	GType       (* get_item_gtype)        (SecretService *self);
    };

The class for SecretService.

#### Members

GType `collection_gtype`; | the GType of the SecretCollection objects instantiated by the SecretService proxy |
GType `item_gtype`; | the GType of the SecretItem objects instantiated by the SecretService proxy |
`prompt_sync` () | called to perform synchronous prompting when necessary |
`prompt_async` () | called to perform asynchronous prompting when necessary |
`prompt_finish` () | called to complete an asynchronous prompt operation |
`get_collection_gtype` () | called to get the GObject type for collections instantiated by the SecretService proxy |
`get_item_gtype` () | called to get the GObject type for collections instantiated by the SecretService proxy |

### enum SecretServiceFlags

Flags which determine which parts of the SecretService proxy are initialized during a `secret_service_get()` or `secret_service_open()` operation.

#### Members

SECRET_SERVICE_NONE | no flags for initializing the SecretService |
SECRET_SERVICE_OPEN_SESSION | establish a session for transfer of secrets while initializing the SecretService |
SECRET_SERVICE_LOAD_COLLECTIONS | load collections while initializing the SecretService |

### enum SecretSearchFlags

Various flags to be used with `secret_service_search()` and `secret_service_search_sync()`.

#### Members

SECRET_SEARCH_NONE | no flags |
SECRET_SEARCH_ALL | all the items matching the search will be returned, instead of just the first one |
SECRET_SEARCH_UNLOCK | unlock locked items while searching |
SECRET_SEARCH_LOAD_SECRETS | while searching load secrets for items that are not locked |

## Property Details

### The `“collections”` property

      “collections”              SecretObjectList *

A list of SecretCollection objects representing the collections in 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 `secret_service_get()` or `secret_service_open()` functions. Or call the `secret_service_load_collections()` method.

Owner: SecretService

Flags: Read