diff options
Diffstat (limited to 'docs/reference/libsecret/migrating-libgnome-keyring.xml')
| -rw-r--r-- | docs/reference/libsecret/migrating-libgnome-keyring.xml | 839 |
1 files changed, 839 insertions, 0 deletions
diff --git a/docs/reference/libsecret/migrating-libgnome-keyring.xml b/docs/reference/libsecret/migrating-libgnome-keyring.xml new file mode 100644 index 0000000..a675526 --- /dev/null +++ b/docs/reference/libsecret/migrating-libgnome-keyring.xml @@ -0,0 +1,839 @@ +<part id="migrating"> +<title>Migrating from libgnome-keyring</title> + +<chapter id="migrating-introduction"> + <title>Introduction</title> + + <para>Conceptually, libgnome-keyring and libsecret are fairly similar. Both + have keyrings, items, and ways to store and retrieve passwords. In both + cases items have attributes. The keys and values of attributes are used + to lookup a password that was stored.</para> + + <para>There is a + <link linkend="libsecret-Password-storage">simple password API for storing and retrieving passwords</link> + which is the easiest and recommended way to store passwords. And then + there is a more complicated API which models all the various collections + and items, along with all the possible actions that can be performed on them.</para> + + <para>libsecret uses the + <ulink url="http://standards.freedesktop.org/secret-service/">Secret Service DBus API</ulink> + to communicate with gnome-keyring-daemon, and as such exposes features + based on that DBus API.</para> + + <para>libsecret has been designed to be threadsafe, and uses the 'GDBus' + code in gio to accomplish this.</para> + + <para>Keyrings are called 'collections' in libsecret.</para> + + <para>See the relevant section for specifics about how to port the + libgnome-keyring functions or symbols in your project.</para> +</chapter> + +<chapter id="migrating-api"> + <title>API conversion</title> + <para>Here are some clues on how to migrate various libgnome-keyring + API functions and their logical equivalents in libsecret.</para> + +<section id="migrating-attributes"> + <title>Item attributes</title> + + <para>Remember that attributes are not, and never have been stored in + an encrypted fashion. They are not part of the 'secret', but instead + are a way to lookup a secret item.</para> + + <para>All attributes in libsecret are stored as strings. Sets of attributes + are represented by #GHashTable<!-- -->s and the keys and values of + these hash tables are strings.</para> + + <para>libsecret is far more <link linkend="migrating-schemas">focused on schemas</link>, + and encourages users to define a #SecretSchema for their password storage. + The schema defines which attributes are allowed an item. Each schema has + a name which is usually a dotted string (eg: <literal>org.gnome.MyProject.Password</literal>). + This schema name is stored internally in the item attributes.</para> + + <para>Schemas define whether an attribute should look like an integer, + a boolean, or a free-form string. These types are used when validating + the attribute values, even though the attribute values are stored and + matched as strings. Since attribute values are used primarily + for lookup of items it's important that the string representations of + integers and booleans are always identical. Boolean values are stored + as the strings <literal>true</literal> and <literal>false</literal>. + Integer values are stored in decimal, with a preceeding negative sign + for negative integers. libsecret facilitates this using the + secret_attributes_build() and secret_attributes_buildv() functions.</para> + + <para>Attributes are meant to be used for lookup of items; they're not + designed to be used as a generic key/value database. Although you can + force libsecret to do the latter, it's better to store your account + information elsewhere if possible, and use libsecret to store the password + or other secret.</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>#GnomeKeyringAttributeList</entry> + <entry>a #GHashTable of string keys and values</entry> + </row> + <row> + <entry>#GnomeKeyringAttribute</entry> + <entry>a key/value pair in a #GHashTable of strings</entry> + </row> + <row> + <entry>#GnomeKeyringAttributeType</entry> + <entry>#SecretSchemaAttributeType</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ATTRIBUTE_TYPE_STRING</entry> + <entry>%SECRET_SCHEMA_ATTRIBUTE_STRING</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32</entry> + <entry>%SECRET_SCHEMA_ATTRIBUTE_INTEGER</entry> + </row> + <row> + <entry>gnome_keyring_attribute_list_index()</entry> + <entry>use g_hash_table_lookup() on the attributes hash table</entry> + </row> + <row> + <entry>gnome_keyring_attribute_get_string()</entry> + <entry>use g_hash_table_lookup() on the attributes hash table</entry> + </row> + <row> + <entry>gnome_keyring_attribute_get_uint32()</entry> + <entry>no equivalent, use g_hash_table_lookup()</entry> + </row> + <row> + <entry>gnome_keyring_attribute_list_append_string()</entry> + <entry>secret_attributes_build()</entry> + </row> + <row> + <entry>gnome_keyring_attribute_list_append_uint32()</entry> + <entry>secret_attributes_build()</entry> + </row> + <row> + <entry>gnome_keyring_attribute_list_copy()</entry> + <entry>g_hash_table_ref()</entry> + </row> + <row> + <entry>gnome_keyring_attribute_list_free()</entry> + <entry>g_hash_table_unref()</entry> + </row> + <row> + <entry>gnome_keyring_attribute_list_index()</entry> + <entry>no equivalent, use g_hash_table_lookup()</entry> + </row> + <row> + <entry>gnome_keyring_attribute_list_new()</entry> + <entry>secret_attributes_build()</entry> + </row> + </tbody> + </tgroup></table></para> +</section> + +<section id="migrating-schemas"> + <title>Working with schemas</title> + + <para>libsecret is far more focused on schemas, and encourages users to + define a #SecretSchema for their password storage. The schema defines + which attributes are allowed an item. Each schema has a name which + is usually a dotted string (eg: <literal>org.gnome.MyProject.Password</literal>). + This name is stored in the item attributes. The schema name is also + used when looking up an item, to make sure that the stored schema + matches that used during the lookup. If you wish to lookup items that + were stored by libgnome-keyring, you should specify the + %SECRET_SCHEMA_DONT_MATCH_NAME flag in the schema so that the schema + name is not matched, since it was not stored by libgnome-keyring.</para> + + <para>Schemas define whether an attribute should look like an integer, + a boolean, or a free-form string. These types are used when validating + the attribute values stored, even though the attribute values are + stored and matched as strings.</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>#GnomeKeyringPasswordSchema</entry> + <entry>#SecretSchema</entry> + </row> + <row> + <entry>#GnomeKeyringPasswordSchemaAttribute</entry> + <entry>#SecretSchemaAttribute</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ITEM_APPLICATION_SECRET</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORD</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORD</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ITEM_PK_STORAGE</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ITEM_GENERIC_SECRET</entry> + <entry>no equivalent, define a specific schema with an appropriate dotted name</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ITEM_NETWORK_PASSWORD</entry> + <entry>the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ITEM_NOTE</entry> + <entry>the %SECRET_SCHEMA_NOTE schema</entry> + </row> + <row> + <entry>%GNOME_KEYRING_NETWORK_PASSWORD</entry> + <entry>the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses</entry> + </row> + </tbody> + </tgroup></table></para> +</section> + + +<section id="migrating-storing"> + <title>Storing passwords and items</title> + + <para>It's encouraged to use a #SecretSchema when storing items and + passwords.</para> + + <para>By default most ways of storing an item will now overwrite + another item with the same attributes in the same keyring. To manually + control this behavior use the secret_item_create().</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>%GNOME_KEYRING_DEFAULT</entry> + <entry>%SECRET_COLLECTION_DEFAULT</entry> + </row> + <row> + <entry>%GNOME_KEYRING_SESSION</entry> + <entry>%SECRET_COLLECTION_SESSION</entry> + </row> + <row> + <entry>gnome_keyring_store_password()</entry> + <entry>secret_password_store()</entry> + </row> + <row> + <entry>gnome_keyring_store_password_sync()</entry> + <entry>secret_password_store_sync()</entry> + </row> + <row> + <entry>gnome_keyring_set_network_password()</entry> + <entry>secret_password_store() with %SECRET_SCHEMA_COMPAT_NETWORK + although this is not recommended for new uses.</entry> + </row> + <row> + <entry>gnome_keyring_set_network_password_sync()</entry> + <entry>secret_password_store_sync() with %SECRET_SCHEMA_COMPAT_NETWORK + although this is not recommended for new uses.</entry> + </row> + <row> + <entry>gnome_keyring_item_create()</entry> + <entry>secret_item_create(), although using secret_password_store() + is simpler.</entry> + </row> + <row> + <entry>gnome_keyring_item_create_sync()</entry> + <entry>secret_item_create(), although using secret_password_store_sync() + is simpler.</entry> + </row> + </tbody> + </tgroup></table></para> +</section> + +<section id="migrating-searching"> + <title>Searching for passwords and items</title> + + <para>In general libsecret tries not to unlocking keyrings + where not necessary. Many search methods only return one item or + password that matches, preferring already unlocked items, and recently stored + items.</para> + + <para>Attributes are meant to be used for lookup of items; they're not + designed to be used as a generic key/value database. Although you can + force libsecret to do the latter, it's better to store your account + information elsewhere if possible, and use libsecret to store the password + or other secret. Because of this many search methods return just the + password or secret.</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>gnome_keyring_find_password()</entry> + <entry>secret_password_lookup()</entry> + </row> + <row> + <entry>gnome_keyring_find_password_sync()</entry> + <entry>secret_password_lookup_sync()</entry> + </row> + <row> + <entry>gnome_keyring_find_items()</entry> + <entry>secret_service_search(), with flags to fine tune behavior</entry> + </row> + <row> + <entry>gnome_keyring_find_itemsv()</entry> + <entry>secret_service_search(), with flags to fine tune behavior</entry> + </row> + <row> + <entry>gnome_keyring_find_items_sync()</entry> + <entry>secret_service_search_sync(), with flags to fine tune behavior</entry> + </row> + <row> + <entry>gnome_keyring_find_itemsv_sync()</entry> + <entry>secret_service_search(), with flags to fine tune behavior</entry> + </row> + <row> + <entry>GnomeKeyringFound</entry> + <entry>no equivalent, secret_service_search() returns a #GList of + #SecretItem<!-- -->s, and other methods return passwords directly.</entry> + </row> + <row> + <entry>gnome_keyring_found_copy()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_found_free()</entry> + <entry>g_object_unref() on the each of the items returned from + secret_service_search()</entry> + </row> + <row> + <entry>gnome_keyring_found_list_free()</entry> + <entry>g_list_free_full() used with g_object_unref() on the items returned from + secret_service_search()</entry> + </row> + <row> + <entry>gnome_keyring_find_network_password()</entry> + <entry>secret_password_lookup() with %SECRET_SCHEMA_COMPAT_NETWORK, + although this only returns one password and no attributes</entry> + </row> + <row> + <entry>gnome_keyring_find_network_password_sync()</entry> + <entry>secret_password_lookup_sync() with %SECRET_SCHEMA_COMPAT_NETWORK, + although this only returns one password and no attributes</entry> + </row> + <row> + <entry>#GnomeKeyringNetworkPasswordData</entry> + <entry>no equivalent, secret_password_lookup() gets the password directly + and no attributes</entry> + </row> + <row> + <entry>gnome_keyring_network_password_free()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_network_password_list_free()</entry> + <entry>no equivalent</entry> + </row> + </tbody> + </tgroup></table></para> +</section> + +<section id="migrating-removing"> + <title>Removing passwords and icons</title> + + <para>Neither libgnome-keyring or libsecret allow deletion of locked + items. libsecret tries to make it easier to delete all unlocked items + matching certain attributes.</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>gnome_keyring_delete_password()</entry> + <entry>secret_password_remove(), although we now try to delete + all unlocked matching items</entry> + </row> + <row> + <entry>gnome_keyring_delete_password_sync()</entry> + <entry>secret_password_remove_sync(), although we now try to delete + all unlocked matching items</entry> + </row> + <row> + <entry>gnome_keyring_item_delete()</entry> + <entry>secret_item_delete()</entry> + </row> + <row> + <entry>gnome_keyring_item_delete_sync()</entry> + <entry>secret_item_delete_sync()</entry> + </row> + </tbody> + </tgroup></table></para> +</section> + +<section id="migrating-items"> + <title>Item management</title> + + <para>In libsecret items are no longer identified by an unsigned integer. + Applications should retrieve items based on their attributes. It is also + possible to identify an item by its DBus object path.</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>gnome_keyring_item_create()</entry> + <entry>secret_item_create(), although secret_password_store() may be simpler</entry> + </row> + <row> + <entry>gnome_keyring_item_create_sync()</entry> + <entry>secret_item_create_sync(), although secret_password_store_sync() may be simpler</entry> + </row> + <row> + <entry>gnome_keyring_item_delete()</entry> + <entry>secret_item_delete(), although secret_password_remove() may be simpler</entry> + </row> + <row> + <entry>gnome_keyring_item_delete_sync()</entry> + <entry>secret_item_delete_sync(), although secret_password_remove_sync() may be simpler</entry> + </row> + <row> + <entry>gnome_keyring_item_get_info()</entry> + <entry>properties are loaded on a #SecretItem automatically, use + secret_item_load_secret() to load the secret</entry> + </row> + <row> + <entry>gnome_keyring_item_get_info_sync()</entry> + <entry>properties are loaded on a #SecretItem automatically, use + secret_item_load_secret_sync() to load the secret</entry> + </row> + <row> + <entry>gnome_keyring_item_get_info_full()</entry> + <entry>properties are loaded on a #SecretItem automatically, use + secret_item_load_secret() to load the secret</entry> + </row> + <row> + <entry>gnome_keyring_item_get_info_full_sync()</entry> + <entry>properties are loaded on a #SecretItem automatically, use + secret_item_load_secret_sync() to load the secret</entry> + </row> + <row> + <entry>gnome_keyring_item_set_info()</entry> + <entry>use the appropriate setter methods on #SecretItem</entry> + </row> + <row> + <entry>gnome_keyring_item_set_info_sync()</entry> + <entry>use the appropriate setter methods on #SecretItem</entry> + </row> + <row> + <entry>gnome_keyring_item_get_attributes()</entry> + <entry>secret_item_get_attributes()</entry> + </row> + <row> + <entry>gnome_keyring_item_get_attributes_sync()</entry> + <entry>secret_item_get_attributes()</entry> + </row> + <row> + <entry>gnome_keyring_item_set_attributes()</entry> + <entry>secret_item_set_attributes()</entry> + </row> + <row> + <entry>gnome_keyring_item_set_attributes_sync()</entry> + <entry>secret_item_set_attributes_sync()</entry> + </row> + <row> + <entry>#GnomeKeyringItemType</entry> + <entry>replaced by the name of a #SecretSchema</entry> + </row> + <row> + <entry>#GnomeKeyringItemInfo</entry> + <entry>#SecretItem</entry> + </row> + <row> + <entry>gnome_keyring_item_info_new()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_item_info_copy()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_item_info_free()</entry> + <entry>g_object_unref() on the #SecretItem</entry> + </row> + <row> + <entry>gnome_keyring_item_info_get_display_name()</entry> + <entry>secret_item_get_label()</entry> + </row> + <row> + <entry>gnome_keyring_item_info_set_display_name()</entry> + <entry>secret_item_set_label()</entry> + </row> + <row> + <entry>gnome_keyring_item_info_get_ctime()</entry> + <entry>secret_item_get_created()</entry> + </row> + <row> + <entry>gnome_keyring_item_info_get_mtime()</entry> + <entry>secret_item_get_modified()</entry> + </row> + <row> + <entry>gnome_keyring_item_info_get_type()</entry> + <entry>secret_item_get_schema_name()</entry> + </row> + <row> + <entry>gnome_keyring_item_info_set_type()</entry> + <entry>secret_item_set_attributes() with appropriate schema</entry> + </row> + <row> + <entry>gnome_keyring_item_info_get_secret()</entry> + <entry>secret_item_get_secret()</entry> + </row> + <row> + <entry>gnome_keyring_item_info_set_secret()</entry> + <entry>secret_item_set_secret() and secret_item_set_secret_sync()</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ITEM_INFO_BASICS</entry> + <entry>no equivalent, all basic item properties are loaded on #SecretItem + automatically</entry> + </row> + <row> + <entry>%GNOME_KEYRING_ITEM_INFO_SECRET</entry> + <entry>use secret_item_load_secret() and secret_item_load_secret_sync() to load + the secret for an item.</entry> + </row> + <row> + <entry>gnome_keyring_item_info_set_display_name()</entry> + <entry></entry> + </row> + </tbody> + </tgroup></table></para> +</section> + +<section id="migrating-keyrings"> + <title>Keyring management</title> + + <para>In libsecret keyrings are called 'collections'. This is the same + lingo as the underlying Secret Service DBus API. Keyrings are no longer + identified by simple keyring names. Normally applications just use the + default keyrings and these are identified by the aliases + %SECRET_COLLECTION_DEFAULT and %SECRET_COLLECTION_SESSION. It is also + possible to identify collections by their DBus object paths.</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>gnome_keyring_create()</entry> + <entry>secret_collection_create()</entry> + </row> + <row> + <entry>gnome_keyring_create_sync()</entry> + <entry>secret_collection_create_sync()</entry> + </row> + <row> + <entry>gnome_keyring_delete()</entry> + <entry>secret_collection_delete()</entry> + </row> + <row> + <entry>gnome_keyring_delete_sync()</entry> + <entry>secret_collection_delete_sync()</entry> + </row> + <row> + <entry>gnome_keyring_change_password()</entry> + <entry>no equivalent, use platform specific DBus APIs</entry> + </row> + <row> + <entry>gnome_keyring_change_password_sync()</entry> + <entry>no equivalent, use platform specific DBus APIs</entry> + </row> + <row> + <entry>gnome_keyring_list_keyring_names()</entry> + <entry>secret_service_load_collections() and secret_service_get_collections()</entry> + </row> + <row> + <entry>gnome_keyring_list_keyring_names_sync()</entry> + <entry>secret_service_load_collections_sync() and secret_service_get_collections()</entry> + </row> + <row> + <entry>gnome_keyring_set_default_keyring()</entry> + <entry>secret_service_set_alias()</entry> + </row> + <row> + <entry>gnome_keyring_set_default_keyring_sync()</entry> + <entry>secret_service_set_alias_sync()</entry> + </row> + <row> + <entry>gnome_keyring_get_default_keyring()</entry> + <entry>secret_collection_for_alias() with %SECRET_COLLECTION_DEFAULT</entry> + </row> + <row> + <entry>gnome_keyring_get_default_keyring_sync()</entry> + <entry>secret_collection_for_alias_sync() with %SECRET_COLLECTION_DEFAULT</entry> + </row> + <row> + <entry>gnome_keyring_list_item_ids()</entry> + <entry>secret_collection_load_items() and secret_collection_get_items()</entry> + </row> + <row> + <entry>gnome_keyring_list_item_ids_sync()</entry> + <entry>secret_collection_load_items_sync() and secret_collection_get_items()</entry> + </row> + <row> + <entry>#GnomeKeyringInfo</entry> + <entry>#SecretCollection and properties</entry> + </row> + <row> + <entry>gnome_keyring_get_info()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_get_info_sync()</entry> + <entry>no equivalent()</entry> + </row> + <row> + <entry>gnome_keyring_set_info()</entry> + <entry>no equivalent, use property setters on #SecretCollection</entry> + </row> + <row> + <entry>gnome_keyring_set_info_sync()</entry> + <entry>no equivalent, use property setters on #SecretCollection</entry> + </row> + <row> + <entry>gnome_keyring_info_free()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_info_copy()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_info_set_lock_on_idle()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_info_get_lock_on_idle()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_info_set_lock_timeout()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_info_get_lock_timeout()</entry> + <entry>no equivalent</entry> + </row> + <row> + <entry>gnome_keyring_info_get_mtime()</entry> + <entry>secret_collection_get_modified()</entry> + </row> + <row> + <entry>gnome_keyring_info_get_ctime()</entry> + <entry>secret_collection_get_created()</entry> + </row> + <row> + <entry>gnome_keyring_info_get_is_locked()</entry> + <entry>secret_collection_get_locked()</entry> + </row> + </tbody> + </tgroup></table></para> +</section> + +<section id="migrating-locking"> + <title>Locking and unlocking</title> + + <para>In libsecret you can unlock items directly, and the result is + (with gnome-keyring daemon) that the enclosing collection will be unlocked.</para> + + <para>It is no longer possible to pass a password to unlock keyrings. + These are automatically prompted for.</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>gnome_keyring_unlock()</entry> + <entry>secret_service_unlock()</entry> + </row> + <row> + <entry>gnome_keyring_unlock_sync()</entry> + <entry>secret_service_unlock_sync()</entry> + </row> + <row> + <entry>gnome_keyring_lock()</entry> + <entry>secret_service_lock()</entry> + </row> + <row> + <entry>gnome_keyring_lock_sync()</entry> + <entry>secret_service_lock_sync()</entry> + </row> + <row> + <entry>gnome_keyring_lock_all()</entry> + <entry>no equivalent, use platform specific DBus APIs</entry> + </row> + <row> + <entry>gnome_keyring_lock_all_sync()</entry> + <entry>no equivalent, use platform specific DBus APIs</entry> + </row> + </tbody> + </tgroup></table></para> +</section> + +<section id="migrating-memory"> + <title>Non-pageable memory</title> + + <para>libsecret no longer provides a full API for using non-pageable + memory. Use the <ulink url="http://developer.gnome.org/gcr/stable/gcr-Non-pageable-Memory.html">equivalent API in the Gcr library</ulink>.</para> + + <para>You can request that passwords are returned in non-pageable + memory by using the secret_password_lookup_nonpageable_sync() and + secret_password_lookup_nonpageable_finish() functions. + In addition the contents of #SecretValue items is stored in + non-pageable memory, unless the system doesn't support this.</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>gnome_keyring_memory_alloc()</entry> + <entry>no equivalent, use Gcr</entry> + </row> + <row> + <entry>gnome_keyring_memory_free()</entry> + <entry>secret_password_free(), although this only works on strings</entry> + </row> + <row> + <entry>gnome_keyring_memory_is_secure()</entry> + <entry>no equivalent, use Gcr</entry> + </row> + <row> + <entry>gnome_keyring_memory_new()</entry> + <entry>no equivalent, use Gcr</entry> + </row> + <row> + <entry>gnome_keyring_memory_realloc()</entry> + <entry>no equivalent, use Gcr</entry> + </row> + <row> + <entry>gnome_keyring_memory_strdup()</entry> + <entry>no equivalent, use #SecretValue which is ref-counted, or use Gcr</entry> + </row> + <row> + <entry>gnome_keyring_memory_try_alloc()</entry> + <entry>no equivalent, use Gcr</entry> + </row> + <row> + <entry>gnome_keyring_memory_try_realloc()</entry> + <entry>no equivalent, use Gcr</entry> + </row> + <row> + <entry>gnome_keyring_free_password()</entry> + <entry>secret_password_free()</entry> + </row> + </tbody> + </tgroup></table></para> +</section> + +<section id="migrating-misc"> + <title>Errors and cancellation</title> + + <para>libsecret uses standard the standard #GCancellable idiom + to cancel operations.</para> + + <para>It is not necessary to check whether the keyring daemon is + available before using it. It is started automatically.</para> + + <para>Errors are returned as standard #GError in the usual way. + There are fewer errors that are worth handling in an intelligent way, + exceptions are in the #SecretError enumeration. It is not recommended + to display any #GError message returned by libsecret to the user. Most + of the possible errors are DBus communication problems or similar.</para> + + <para>Replacements for related libgnome-keyring functions and types + are described below: + <table><tgroup cols="2"> + <thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead> + <tbody> + <row> + <entry>gnome_keyring_cancel_request()</entry> + <entry>g_cancellable_cancel() on a #GCancellable passed to the relevant operation</entry> + </row> + <row> + <entry>gnome_keyring_is_available()</entry> + <entry>no equivalent, the secret service is autostarted as necessary</entry> + </row> + <row> + <entry>gnome_keyring_result_to_message()</entry> + <entry>use the message in the #GError, although most failures are not appropriate for display to the user</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_OK</entry> + <entry>no #GError returned</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_DENIED</entry> + <entry>no longer used, item or collection is simply not unlocked</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_NO_KEYRING_DAEMON</entry> + <entry>%G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_ALREADY_UNLOCKED</entry> + <entry>no error, success returned</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_NO_SUCH_KEYRING</entry> + <entry>keyrings no longer have names, accessing an missing DBus object has usual failure</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_BAD_ARGUMENTS</entry> + <entry>%G_DBUS_ERROR_INVALID_ARGS or precondition failure in libsecret, this is always + a programmer error</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_IO_ERROR</entry> + <entry>relevant DBus errors, or %SECRET_ERROR_PROTOCOL</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_CANCELLED</entry> + <entry>%G_IO_ERROR_CANCELLED</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTS</entry> + <entry>no error, simply returns already existing keyring</entry> + </row> + <row> + <entry>%GNOME_KEYRING_RESULT_NO_MATCH</entry> + <entry>on error, an empty list is returned</entry> + </row> + <row> + <entry>gnome_keyring_string_list_free()</entry> + <entry>no equivalent</entry> + </row> + </tbody> + </tgroup></table></para> +</section> + +</chapter> + +</part> |