From a4d290db293408aeb7f6b41d6a3ac593476f071b Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Sun, 18 Mar 2012 13:19:03 +0100 Subject: [PATCH] Complete the example documentation --- docs/reference/libsecret/Makefile.am | 2 +- docs/reference/libsecret/libsecret-docs.sgml | 2 + .../libsecret/libsecret-examples.sgml | 617 ++++++++++++++++++ 3 files changed, 620 insertions(+), 1 deletion(-) create mode 100644 docs/reference/libsecret/libsecret-examples.sgml diff --git a/docs/reference/libsecret/Makefile.am b/docs/reference/libsecret/Makefile.am index 33bc1ce..c2038dc 100644 --- a/docs/reference/libsecret/Makefile.am +++ b/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 diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml index 067f151..1172dfb 100644 --- a/docs/reference/libsecret/libsecret-docs.sgml +++ b/docs/reference/libsecret/libsecret-docs.sgml @@ -19,6 +19,8 @@ + + Complete API diff --git a/docs/reference/libsecret/libsecret-examples.sgml b/docs/reference/libsecret/libsecret-examples.sgml new file mode 100644 index 0000000..94ef82a --- /dev/null +++ b/docs/reference/libsecret/libsecret-examples.sgml @@ -0,0 +1,617 @@ + + +]> + + Examples + + + C examples + +
+ C example: Define a password schema + + 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: + + + + See the other examples for how + to use the schema. +
+ +
+ C example: Store a password + + Here's how to store a password in the running secret service, + like gnome-keyring or ksecretservice. + + 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. + + These examples use the example + schema. + + This first example stores a password asynchronously, and is + appropriate for GUI applications so that the UI does not block. + + + + 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. + + +
+ +
+ C example: Lookup a password + + Here's how to lookup a password in the running secret service, + like gnome-keyring or ksecretservice. + + 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. + + These examples use the example + schema. + + This first example looks up a password asynchronously, and is + appropriate for GUI applications so that the UI does not block. + + + + 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. + + +
+ +
+ C example: Remove a password + + Here's how to remove a password from the running secret service, + like gnome-keyring or ksecretservice. + + 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. + + These examples use the example + schema. + + This first example removes a password asynchronously, and is + appropriate for GUI applications so that the UI does not block. + + + + 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. + + +
+ +
+ + + Javascript examples + +
+ Javascript example: Define a password schema + + 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: + + + + See the other examples for how + to use the schema. +
+ +
+ Javascript example: Store a password + + Here's how to store a password in the running secret service, + like gnome-keyring or ksecretservice. + + 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. + + These examples use the example + schema. + + This first example stores a password asynchronously, and is + appropriate for GUI applications so that the UI does not block. + + + + 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. + + +
+ +
+ Javascript example: Lookup a password + + Here's how to lookup a password in the running secret service, + like gnome-keyring or ksecretservice. + + 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. + + These examples use the example + schema. + + This first example looks up a password asynchronously, and is + appropriate for GUI applications so that the UI does not block. + + + + 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. + + +
+ +
+ Javascript example: Remove a password + + Here's how to remove a password from the running secret service, + like gnome-keyring or ksecretservice. + + 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. + + These examples use the example + schema. + + This first example removes a password asynchronously, and is + appropriate for GUI applications so that the UI does not block. + + + + This next example removes a password synchronously. The function + call will block until the removal completes. So this is appropriate for + non GUI applications. + + +
+ +
+ + + Python examples + +
+ Python example: Define a password schema + + 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: + + + + See the other examples for how + to use the schema. +
+ +
+ Python example: Store a password + + Here's how to store a password in the running secret service, + like gnome-keyring or ksecretservice. + + 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. + + These examples use the example + schema. + + This first example stores a password asynchronously, and is + appropriate for GUI applications so that the UI does not block. + + + + 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. + + +
+ +
+ Python example: Lookup a password + + Here's how to lookup a password in the running secret service, + like gnome-keyring or ksecretservice. + + 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. + + These examples use the example + schema. + + This first example looks up a password asynchronously, and is + appropriate for GUI applications so that the UI does not block. + + + + 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. + + +
+ +
+ Python example: Remove a password + + Here's how to remove a password from the running secret service, + like gnome-keyring or ksecretservice. + + 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. + + These examples use the example + schema. + + This first example removes a password asynchronously, and is + appropriate for GUI applications so that the UI does not block. + + + + This next example removes a password synchronously. The function + call will block until the removal completes. So this is appropriate for + non GUI applications. + + +
+ +
+ +