diff options
Diffstat (limited to 'docs/reference/libsecret/libsecret-examples.sgml')
| -rw-r--r-- | docs/reference/libsecret/libsecret-examples.sgml | 785 |
1 files changed, 0 insertions, 785 deletions
diff --git a/docs/reference/libsecret/libsecret-examples.sgml b/docs/reference/libsecret/libsecret-examples.sgml deleted file mode 100644 index e5be51a..0000000 --- a/docs/reference/libsecret/libsecret-examples.sgml +++ /dev/null @@ -1,785 +0,0 @@ -<?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_cleared (GObject *source, - GAsyncResult *result, - gpointer unused) - { - GError *error = NULL; - - gboolean removed = secret_password_clear_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_clear (EXAMPLE_SCHEMA, NULL, on_password_cleared, 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_clear_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_clear(source, result) { - var removed = Secret.password_clear_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_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, - null, on_password_clear); - ]]></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_clear_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_clear(source, result, unused): - removed = Secret.password_clear_finish(result) - # removed will be true if the password was removed - - Secret.password_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, - None, on_password_clear) - ]]></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_clear_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None) - # removed will be true if the password was removed - ]]></programlisting></informalexample> - </section> - - </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_clearv.begin (example_schema, attributes, null, (obj, async_res) => { - bool removed = Secret.password_clearv.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_clear_sync (example_schema, null, - "number", 8, "string", "eight", "even", true); - /* removed will be true if the password was removed */ - ]]></programlisting></informalexample> - </section> - - </chapter> - -</part> |