path: root/docs/reference/libsecret/migrating-libgnome-keyring.xml

<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>