Complete the example documentation

docs/reference/libsecret/Makefile.am

@@ -69,7 +69,7 @@ HTML_IMAGES=
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files=
+content_files=libsecret-examples.sgml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files

docs/reference/libsecret/libsecret-docs.sgml

@@ -19,6 +19,8 @@
 		<xi:include href="xml/secret-schema.xml"/>
 	</part>
 
+	<xi:include href="libsecret-examples.sgml"/>
+
 	<part id="complete">
 		<title>Complete API</title>
 		<xi:include href="xml/secret-service.xml"/>

docs/reference/libsecret/libsecret-examples.sgml

@@ -0,0 +1,617 @@
+<?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>