path: root/docs/reference/libsecret/libsecret-examples.sgml

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<part id="examples">
	<title>Examples</title>

	<chapter id="c-examples">
		<title>C examples</title>

		<section id="c-schema-example">
			<title>C example: Define a password schema</title>

			<para>Each stored password has a set of attributes which are later
			used to lookup the password. The names and types of the attributes
			are defined in a schema. The schema is usually defined once globally.
			Here's how to define a schema:</para>

			<informalexample><programlisting language="c"><![CDATA[
			/* in a header: */

			const SecretSchema * example_get_schema (void) G_GNUC_CONST;

			#define EXAMPLE_SCHEMA  example_get_schema ()


			/* in a .c file: */

			const SecretSchema *
			example_get_schema (void)
			{
				static const SecretSchema the_schema = {
					"org.example.Password", SECRET_SCHEMA_NONE,
					{
						{  "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
						{  "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
						{  "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
						{  "NULL", 0 },
					}
				};
				return &the_schema;
			}
			]]></programlisting></informalexample>

			<para>See the <link linkend="c-store-example">other examples</link> for how
			to use the schema.</para>
		</section>

		<section id="c-store-example">
			<title>C example: Store a password</title>

			<para>Here's how to store a password in the running secret service,
			like gnome-keyring or ksecretservice.</para>

			<para>Each stored password has a set of attributes which are later
			used to lookup the password. The attributes should not contain
			secrets, as they are not stored in an encrypted fashion.</para>

			<para>These examples use <link linkend="c-schema-example">the example
			schema</link>.</para>

			<para>This first example stores a password asynchronously, and is
			appropriate for GUI applications so that the UI does not block.</para>

			<informalexample><programlisting language="c"><![CDATA[
			static void
			on_password_stored (GObject *source,
			                    GAsyncResult *result,
			                    gpointer unused)
			{
				GError *error = NULL;

				secret_password_store_finish (result, &error);
				if (error != NULL) {
					/* ... handle the failure here */
					g_error_free (error);
				} else {
					/* ... do something now that the password has been stored */
				}
			}

			/*
			 * The variable argument list is the attributes used to later
			 * lookup the password. These attributes must conform to the schema.
			 */
			secret_password_store (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT, "The label",
			                       "the password", NULL, on_password_stored, NULL,
			                       "number", 8,
			                       "string", "eight",
			                       "even", TRUE,
			                       NULL);
			]]></programlisting></informalexample>

			<para>This next example stores a password synchronously. The function
			call will block until the password is stored. So this is appropriate for
			non GUI applications.</para>

			<informalexample><programlisting language="javascript"><![CDATA[
			GError *error = NULL;

			/*
			 * The variable argument list is the attributes used to later
			 * lookup the password. These attributes must conform to the schema.
			 */
			secret_password_store_sync (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT,
			                            "The label", "the password", NULL, &error,
			                            "number", 9,
			                            "string", "nine",
			                            "even", FALSE,
			                            NULL);

			if (error != NULL) {
				/* ... handle the failure here */
				g_error_free (error);
			} else {
				/* ... do something now that the password has been stored */
			}

			]]></programlisting></informalexample>
		</section>

		<section id="c-lookup-example">
			<title>C example: Lookup a password</title>

			<para>Here's how to lookup a password in the running secret service,
			like gnome-keyring or ksecretservice.</para>

			<para>Each stored password has a set of attributes which are
			used to lookup the password. If multiple passwords match the
			lookup attributes, then the one stored most recently is returned.</para>

			<para>These examples use <link linkend="c-schema-example">the example
			schema</link>.</para>

			<para>This first example looks up a password asynchronously, and is
			appropriate for GUI applications so that the UI does not block.</para>

			<informalexample><programlisting language="javascript"><![CDATA[
			static void
			on_password_lookup (GObject *source,
			                    GAsyncResult *result,
			                    gpointer unused)
			 {
				GError *error = NULL;

				gchar *password = secret_password_lookup_finish (result, &error);

				if (error != NULL) {
					/* ... handle the failure here */
					g_error_free (error);

				} else if (password == NULL) {
					/* password will be null, if no matching password found */

				} else {
					/* ... do something with the password */
					secret_password_free (password);
				}

			}

			/*
			 * The variable argument list is the attributes used to later
			 * lookup the password. These attributes must conform to the schema.
			 */
			secret_password_lookup (EXAMPLE_SCHEMA, NULL, on_password_lookup, NULL,
			                        "string", "nine",
			                        "even", FALSE,
			                        NULL);
			]]></programlisting></informalexample>

			<para>This next example looks up a password synchronously. The function
			call will block until the lookup completes. So this is appropriate for
			non GUI applications.</para>

			<informalexample><programlisting language="c"><![CDATA[
			GError *error = NULL;

			/* The attributes used to lookup the password should conform to the schema. */
			gchar *password = secret_password_lookup_sync (EXAMPLE_SCHEMA, NULL, &error,
			                                               "string", "nine",
			                                               "even", FALSE,
			                                               NULL);
			
			if (error != NULL) {
				/* ... handle the failure here */
				g_error_free (error);

			} else if (password == NULL) {
				/* password will be null, if no matching password found */

			} else {
				/* ... do something with the password */
				secret_password_free (password);
			}
			]]></programlisting></informalexample>
		</section>

		<section id="c-remove-example">
			<title>C example: Remove a password</title>

			<para>Here's how to remove a password from the running secret service,
			like gnome-keyring or ksecretservice.</para>

			<para>Each stored password has a set of attributes which are
			used to find which password to remove. If multiple passwords match the
			attributes, then the one stored most recently is removed.</para>

			<para>These examples use <link linkend="c-schema-example">the example
			schema</link>.</para>

			<para>This first example removes a password asynchronously, and is
			appropriate for GUI applications so that the UI does not block.</para>

			<informalexample><programlisting language="c"><![CDATA[
			static void
			on_password_removed (GObject *source,
			                     GAsyncResult *result,
			                     gpointer unused)
			 {
				GError *error = NULL;

				gboolean removed = secret_password_remove_finish (result, &error);

				if (error != NULL) {
					/* ... handle the failure here */
					g_error_free (error);

				} else {
					/* removed will be TRUE if a password was removed */
				}
			}

			/*
			 * The variable argument list is the attributes used to later
			 * lookup the password. These attributes must conform to the schema.
			 */
			secret_password_remove (EXAMPLE_SCHEMA, NULL, on_password_removed, NULL,
			                        "string", "nine",
			                        "even", FALSE,
			                        NULL);
			]]></programlisting></informalexample>

			<para>This next example looks up a password synchronously. The function
			call will block until the lookup completes. So this is appropriate for
			non GUI applications.</para>

			<informalexample><programlisting language="c"><![CDATA[
			GError *error = NULL;

			/*
			 * The variable argument list is the attributes used to later
			 * lookup the password. These attributes must conform to the schema.
			 */
			gboolean removed = secret_password_remove_sync (EXAMPLE_SCHEMA, NULL, &error,
			                                                "string", "nine",
			                                                "even", FALSE,
			                                                NULL);

			if (error != NULL) {
				/* ... handle the failure here */
				g_error_free (error);

			} else {
				/* removed will be TRUE if a password was removed */
			}
			]]></programlisting></informalexample>
		</section>

	</chapter>

	<chapter id="js-examples">
		<title>Javascript examples</title>

		<section id="js-schema-example">
			<title>Javascript example: Define a password schema</title>

			<para>Each stored password has a set of attributes which are later
			used to lookup the password. The names and types of the attributes
			are defined in a schema. The schema is usually defined once globally.
			Here's how to define a schema:</para>

			<informalexample><programlisting language="javascript"><![CDATA[
			const Secret = imports.gi.Secret;

			/* This schema is usually defined once globally */
			const EXAMPLE_SCHEMA = new Secret.Schema.new("org.example.Password",
				Secret.SchemaFlags.NONE,
				{
					"number": Secret.SchemaAttributeType.INTEGER,
					"string": Secret.SchemaAttributeType.STRING,
					"even": Secret.SchemaAttributeType.BOOLEAN,
				}
			);
			]]></programlisting></informalexample>

			<para>See the <link linkend="js-store-example">other examples</link> for how
			to use the schema.</para>
		</section>

		<section id="js-store-example">
			<title>Javascript example: Store a password</title>

			<para>Here's how to store a password in the running secret service,
			like gnome-keyring or ksecretservice.</para>

			<para>Each stored password has a set of attributes which are later
			used to lookup the password. The attributes should not contain
			secrets, as they are not stored in an encrypted fashion.</para>

			<para>These examples use <link linkend="js-schema-example">the example
			schema</link>.</para>

			<para>This first example stores a password asynchronously, and is
			appropriate for GUI applications so that the UI does not block.</para>

			<informalexample><programlisting language="javascript"><![CDATA[
			const Secret = imports.gi.Secret;

			function on_password_stored(source, result) {
				Secret.password_store_finish(result);
				/* ... do something now that the password has been stored */
			}

			/*
			 * The attributes used to later lookup the password. These
			 * attributes should conform to the schema.
			 */
			var attributes = {
				"number": "8",
				"string": "eight",
				"even": "true"
			};

			Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
			                      "The label", "the password", null, on_password_stored);
			]]></programlisting></informalexample>

			<para>This next example stores a password synchronously. The function
			call will block until the password is stored. So this is appropriate for
			non GUI applications.</para>

			<informalexample><programlisting language="javascript"><![CDATA[
			const Secret = imports.gi.Secret;

			/*
			 * The attributes used to later lookup the password. These
			 * attributes should conform to the schema.
			 */
			var attributes = {
				"number": "9",
				"string": "nine",
				"even": "false"
			};

			Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
			                           "The label", "the password", null);
			]]></programlisting></informalexample>
		</section>

		<section id="js-lookup-example">
			<title>Javascript example: Lookup a password</title>

			<para>Here's how to lookup a password in the running secret service,
			like gnome-keyring or ksecretservice.</para>

			<para>Each stored password has a set of attributes which are
			used to lookup the password. If multiple passwords match the
			lookup attributes, then the one stored most recently is returned.</para>

			<para>These examples use <link linkend="js-schema-example">the example
			schema</link>.</para>

			<para>This first example looks up a password asynchronously, and is
			appropriate for GUI applications so that the UI does not block.</para>

			<informalexample><programlisting language="javascript"><![CDATA[
			const Secret = imports.gi.Secret;

			function on_password_lookup(source, result) {
				var password = Secret.password_lookup_finish(result);
				/* password will be null if no matching password found */
			}

			/* The attributes used to lookup the password should conform to the schema. */
			Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
			                       null, on_password_lookup);
			]]></programlisting></informalexample>

			<para>This next example looks up a password synchronously. The function
			call will block until the lookup completes. So this is appropriate for
			non GUI applications.</para>

			<informalexample><programlisting language="javascript"><![CDATA[
			const Secret = imports.gi.Secret;

			/* The attributes used to lookup the password should conform to the schema. */
			var password = Secret.password_lookup_sync(EXAMPLE_SCHEMA,
			                                           { "number": "8", "even": "true" },
			                                           null);

			/* password will be null, if no matching password found */ 
			]]></programlisting></informalexample>
		</section>

		<section id="js-remove-example">
			<title>Javascript example: Remove a password</title>

			<para>Here's how to remove a password from the running secret service,
			like gnome-keyring or ksecretservice.</para>

			<para>Each stored password has a set of attributes which are
			used to find which password to remove. If multiple passwords match the
			attributes, then the one stored most recently is removed.</para>

			<para>These examples use <link linkend="js-schema-example">the example
			schema</link>.</para>

			<para>This first example removes a password asynchronously, and is
			appropriate for GUI applications so that the UI does not block.</para>

			<informalexample><programlisting language="javascript"><![CDATA[
			const Secret = imports.gi.Secret;

			function on_password_remove(source, result) {
				var removed = Secret.password_remove_finish(result);
				/* removed will be true if the password was removed */
			}

			/* The attributes used to lookup which password to remove should conform to the schema. */
			Secret.password_remove(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
			                       null, on_password_remove);
			]]></programlisting></informalexample>

			<para>This next example removes a password synchronously. The function
			call will block until the removal completes. So this is appropriate for
			non GUI applications.</para>

			<informalexample><programlisting language="javascript"><![CDATA[
			const Secret = imports.gi.Secret;

			/* The attributes used to lookup which password to remove should conform to the schema. */
			var removed = Secret.password_remove_sync(EXAMPLE_SCHEMA,
			                                          { "number": "8", "even": "true" },
			                                          null);

			/* removed will be true if the password was removed */
			]]></programlisting></informalexample>
		</section>

	</chapter>

	<chapter id="py-examples">
		<title>Python examples</title>

		<section id="py-schema-example">
			<title>Python example: Define a password schema</title>

			<para>Each stored password has a set of attributes which are later
			used to lookup the password. The names and types of the attributes
			are defined in a schema. The schema is usually defined once globally.
			Here's how to define a schema:</para>

			<informalexample><programlisting language="python"><![CDATA[
			from gi.repository import Secret

			EXAMPLE_SCHEMA = Secret.Schema.new("org.mock.type.Store",
				Secret.SchemaFlags.NONE,
				{
					"number": Secret.SchemaAttributeType.INTEGER,
					"string": Secret.SchemaAttributeType.STRING,
					"even": Secret.SchemaAttributeType.BOOLEAN,
				}
			)
			]]></programlisting></informalexample>

			<para>See the <link linkend="py-store-example">other examples</link> for how
			to use the schema.</para>
		</section>

		<section id="py-store-example">
			<title>Python example: Store a password</title>

			<para>Here's how to store a password in the running secret service,
			like gnome-keyring or ksecretservice.</para>

			<para>Each stored password has a set of attributes which are later
			used to lookup the password. The attributes should not contain
			secrets, as they are not stored in an encrypted fashion.</para>

			<para>These examples use <link linkend="py-schema-example">the example
			schema</link>.</para>

			<para>This first example stores a password asynchronously, and is
			appropriate for GUI applications so that the UI does not block.</para>

			<informalexample><programlisting language="python"><![CDATA[
			from gi.repository import Secret

			def on_password_stored(source, result, unused):
				Secret.password_store_finish(result)
				# ... do something now that the password has been stored

			# The attributes used to later lookup the password. These
			# attributes should conform to the schema.
			attributes = {
				"number": "8",
				"string": "eight",
				"even": "true"
			}

			Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
			                      "The label", "the password", None, on_password_stored)
			]]></programlisting></informalexample>

			<para>This next example stores a password synchronously. The function
			call will block until the password is stored. So this is appropriate for
			non GUI applications.</para>

			<informalexample><programlisting language="python"><![CDATA[
			from gi.repository import Secret

			# The attributes used to later lookup the password. These
			# attributes should conform to the schema.
			attributes = {
				"number": "8",
				"string": "eight",
				"even": "true"
			}

			Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
			                           "The label", "the password", None)
			]]></programlisting></informalexample>
		</section>

		<section id="py-lookup-example">
			<title>Python example: Lookup a password</title>

			<para>Here's how to lookup a password in the running secret service,
			like gnome-keyring or ksecretservice.</para>

			<para>Each stored password has a set of attributes which are
			used to lookup the password. If multiple passwords match the
			lookup attributes, then the one stored most recently is returned.</para>

			<para>These examples use <link linkend="py-schema-example">the example
			schema</link>.</para>

			<para>This first example looks up a password asynchronously, and is
			appropriate for GUI applications so that the UI does not block.</para>

			<informalexample><programlisting language="python"><![CDATA[
			from gi.repository import Secret

			def on_password_lookup(source, result, unused):
				password = Secret.password_lookup_finish(result)
				# password will be null, if no matching password found

			Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
			                       None, on_password_lookup)
			]]></programlisting></informalexample>

			<para>This next example looks up a password synchronously. The function
			call will block until the lookup completes. So this is appropriate for
			non GUI applications.</para>

			<informalexample><programlisting language="python"><![CDATA[
			from gi.repository import Secret

			password = Secret.password_lookup_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
			# password will be null, if no matching password found
			]]></programlisting></informalexample>
		</section>

		<section id="py-remove-example">
			<title>Python example: Remove a password</title>

			<para>Here's how to remove a password from the running secret service,
			like gnome-keyring or ksecretservice.</para>

			<para>Each stored password has a set of attributes which are
			used to find which password to remove. If multiple passwords match the
			attributes, then the one stored most recently is removed.</para>

			<para>These examples use <link linkend="py-schema-example">the example
			schema</link>.</para>

			<para>This first example removes a password asynchronously, and is
			appropriate for GUI applications so that the UI does not block.</para>

			<informalexample><programlisting language="python"><![CDATA[
			from gi.repository import Secret

			def on_password_remove(source, result, unused):
				removed = Secret.password_remove_finish(result)
				# removed will be true if the password was removed

			Secret.password_remove(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
                                               None, on_password_remove)
			]]></programlisting></informalexample>

			<para>This next example removes a password synchronously. The function
			call will block until the removal completes. So this is appropriate for
			non GUI applications.</para>

			<informalexample><programlisting language="python"><![CDATA[
			from gi.repository import Secret

			removed = Secret.password_remove_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
			# removed will be true if the password was removed
			]]></programlisting></informalexample>
		</section>

	</chapter>

</part>