Add Vala bindings.

https://bugzilla.gnome.org/show_bug.cgi?id=678846

1 files changed, 168 insertions, 0 deletions

diff --git a/docs/reference/libsecret/libsecret-examples.sgml b/docs/reference/libsecret/libsecret-examples.sgml
index f885799..67c3bce 100644
--- a/docs/reference/libsecret/libsecret-examples.sgml
+++ b/docs/reference/libsecret/libsecret-examples.sgml
@@ -614,4 +614,172 @@
 
 	</chapter>
 
+	<chapter id="vala-examples">
+		<title>Vala examples</title>
+
+		<section id="vala-schema-example">
+			<title>Vala 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="vala"><![CDATA[
+			var example = new Secret.Schema ("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="vala-store-example">other examples</link> for how
+			to use the schema.</para>
+		</section>
+
+		<section id="vala-store-example">
+			<title>Vala 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="vala-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="vala"><![CDATA[
+			var attributes = new GLib.HashTable<string,string> ();
+			attributes["number"] = "8";
+			attributes["string"] = "eight";
+			attributes["even"] = "true";
+
+			Secret.password_storev.begin (example_schema, attributes, Secret.COLLECTION_DEFAULT,
+			                              "The label", "the password", null, (obj, async_res) => {
+				bool res = Secret.password_store.end (async_res);
+				/* ... do something now that the password has been stored */
+			});
+			]]></programlisting></informalexample>
+
+			<para>If you are already inside of an async function, you can also
+			use the yield keyword:</para>
+
+			<informalexample><programlisting language="vala"><![CDATA[
+			var attributes = new GLib.HashTable<string,string> ();
+			attributes["number"] = "8";
+			attributes["string"] = "eight";
+			attributes["even"] = "true";
+
+			bool res = yield Secret.password_storev (example_schema, attributes,
+			                                         Secret.COLLECTION_DEFAULT, "The label",
+			                                         "the password", null);
+			]]></programlisting></informalexample>
+
+			<para>If you would like to avoid creating a hash table for the
+			attributes you can just use the variadic version:</para>
+
+			<informalexample><programlisting language="vala"><![CDATA[
+			bool res = yield Secret.password_store (example_schema, Secret.COLLECTION_DEFAULT, "The label",
+			                                        "the password", null, "number", 8, "string", "eight",
+			                                        "even", true);
+			]]></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="vala"><![CDATA[
+			Secret.password_store_sync (example_schema, attributes, Secret.COLLECTION_DEFAULT,
+			                            "The label", "the password", null,
+			                            "number", 9, "string", "nine", "even", false);
+			]]></programlisting></informalexample>
+		</section>
+
+		<section id="vala-lookup-example">
+			<title>Vala 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="vala-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="vala"><![CDATA[
+			var attributes = new GLib.HashTable<string,string> ();
+			attributes["number"] = "8";
+			attributes["string"] = "eight";
+			attributes["even"] = "true";
+
+			Secret.password_lookupv.begin (example_schema, attributes, null, (obj, async_res) => {
+				string password = Secret.password_lookup.end (async_res);
+			});
+			]]></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="vala"><![CDATA[
+			string password = Secret.password_lookup_sync (example_schema, attributes, null,
+			                                               "number", 9, "string", "nine", "even", false);
+			/* password will be null, if no matching password found */
+			]]></programlisting></informalexample>
+		</section>
+
+		<section id="vala-remove-example">
+			<title>Vala 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="vala-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="vala"><![CDATA[
+			var attributes = new GLib.HashTable<string,string> ();
+			attributes["number"] = "8";
+			attributes["string"] = "eight";
+			attributes["even"] = "true";
+
+			Secret.password_removev.begin (example_schema, attributes, null, (obj, async_res) => {
+				bool removed = Secret.password_removev.end (async_res);
+			});
+			]]></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="vala"><![CDATA[
+			var attributes = new GLib.HashTable<string,string> ();
+			attributes["number"] = "8";
+			attributes["string"] = "eight";
+			attributes["even"] = "true";
+
+			bool removed = Secret.password_remove_sync (example_schema, null,
+			                                            "number", 8, "string", "eight", "even", true);
+			/* removed will be true if the password was removed */
+			]]></programlisting></informalexample>
+		</section>
+
+	</chapter>
+
 </part>