From 2c3a34cca46f523e0a1df62000c51c5e17d0b589 Mon Sep 17 00:00:00 2001 From: Maximiliano Date: Wed, 2 Feb 2022 12:19:14 +0000 Subject: [PATCH] Port documentation to gi-docgen --- .gitignore | 1 - .gitlab-ci.yml | 29 +- README.md | 5 + .../libsecret/libsecret-c-examples.md | 251 ++++++ docs/reference/libsecret/libsecret-docs.sgml | 47 - .../libsecret/libsecret-examples.sgml | 785 ---------------- .../libsecret/libsecret-js-examples.md | 170 ++++ .../libsecret/libsecret-overrides.txt | 2 - .../libsecret/libsecret-python-examples.md | 152 ++++ .../libsecret/libsecret-sections.txt | 389 -------- .../libsecret/libsecret-simple-api.md | 95 ++ docs/reference/libsecret/libsecret-tpm2.md | 69 ++ docs/reference/libsecret/libsecret-tpm2.sgml | 67 -- docs/reference/libsecret/libsecret-using.md | 80 ++ docs/reference/libsecret/libsecret-using.sgml | 112 --- .../libsecret/libsecret-vala-examples.md | 157 ++++ docs/reference/libsecret/libsecret.toml.in | 52 ++ docs/reference/libsecret/libsecret.types | 7 - docs/reference/libsecret/meson.build | 71 +- .../libsecret/migrating-libgnome-keyring.md | 823 +++++++++++++++++ .../libsecret/migrating-libgnome-keyring.xml | 839 ------------------ docs/reference/libsecret/urlmap.js | 6 + docs/reference/libsecret/version-major.xml.in | 1 - docs/reference/libsecret/version.xml.in | 1 - libsecret/secret-attributes.c | 17 +- libsecret/secret-backend.c | 24 +- libsecret/secret-collection.c | 142 ++- libsecret/secret-item.c | 80 +- libsecret/secret-methods.c | 86 +- libsecret/secret-password.c | 99 +-- libsecret/secret-paths.c | 192 ++-- libsecret/secret-prompt.c | 48 +- libsecret/secret-retrievable.c | 40 +- libsecret/secret-schema.c | 90 +- libsecret/secret-schemas.c | 44 +- libsecret/secret-schemas.h | 61 +- libsecret/secret-service.c | 121 ++- libsecret/secret-util.c | 6 +- libsecret/secret-value.c | 32 +- libsecret/secret-version.h.in | 8 - meson_options.txt | 2 +- subprojects/gi-docgen.wrap | 6 + 42 files changed, 2402 insertions(+), 2907 deletions(-) create mode 100644 docs/reference/libsecret/libsecret-c-examples.md delete mode 100644 docs/reference/libsecret/libsecret-docs.sgml delete mode 100644 docs/reference/libsecret/libsecret-examples.sgml create mode 100644 docs/reference/libsecret/libsecret-js-examples.md delete mode 100644 docs/reference/libsecret/libsecret-overrides.txt create mode 100644 docs/reference/libsecret/libsecret-python-examples.md delete mode 100644 docs/reference/libsecret/libsecret-sections.txt create mode 100644 docs/reference/libsecret/libsecret-simple-api.md create mode 100644 docs/reference/libsecret/libsecret-tpm2.md delete mode 100644 docs/reference/libsecret/libsecret-tpm2.sgml create mode 100644 docs/reference/libsecret/libsecret-using.md delete mode 100644 docs/reference/libsecret/libsecret-using.sgml create mode 100644 docs/reference/libsecret/libsecret-vala-examples.md create mode 100644 docs/reference/libsecret/libsecret.toml.in delete mode 100644 docs/reference/libsecret/libsecret.types create mode 100644 docs/reference/libsecret/migrating-libgnome-keyring.md delete mode 100644 docs/reference/libsecret/migrating-libgnome-keyring.xml create mode 100644 docs/reference/libsecret/urlmap.js delete mode 100644 docs/reference/libsecret/version-major.xml.in delete mode 100644 docs/reference/libsecret/version.xml.in create mode 100644 subprojects/gi-docgen.wrap diff --git a/.gitignore b/.gitignore index 62eeb63..5714fce 100644 --- a/.gitignore +++ b/.gitignore @@ -28,7 +28,6 @@ config.* depcomp install-sh INSTALL -gtk-doc.make libtool ltmain.sh Makefile diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index c27e417..1f55800 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -16,7 +16,7 @@ fedora:Werror: - dnf install -y $DEPENDENCIES - dbus-uuidgen --ensure script: - - meson _build -Dwerror=true -Dc_args=-Wno-error=deprecated-declarations + - meson _build -Dwerror=true -Dc_args=-Wno-error=deprecated-declarations -Dgtk_doc=false - meson compile -C _build - eval `dbus-launch --sh-syntax` - meson test -C _build @@ -35,7 +35,7 @@ fedora:asan: - dnf install -y $DEPENDENCIES libasan - dbus-uuidgen --ensure script: - - meson _build -Dsanitize=address + - meson _build -Dsanitize=address -Dgtk_doc=false - meson compile -C _build - eval `dbus-launch --sh-syntax` - meson test -C _build @@ -54,7 +54,7 @@ fedora:ubsan: - dnf install -y $DEPENDENCIES libubsan - dbus-uuidgen --ensure script: - - meson _build -Dsanitize=undefined + - meson _build -Dsanitize=undefined -Dgtk_doc=false - meson compile -C _build - eval `dbus-launch --sh-syntax` - meson test -C _build @@ -73,7 +73,7 @@ fedora-static-analyzers/test: - dnf install -y $DEPENDENCIES clang-analyzer cppcheck - dbus-uuidgen --ensure script: - - meson _build + - meson _build -Dgtk_doc=false - meson compile -C _build --ninja-args scan-build - cppcheck --force -q $CPPCHECK_OPTIONS libsecret/ egg/ tool/ artifacts: @@ -92,7 +92,7 @@ fedora:coverage: - dnf install -y $DEPENDENCIES lcov - dbus-uuidgen --ensure script: - - meson _build -Db_coverage=true -Dtpm2=true + - meson _build -Db_coverage=true -Dtpm2=true -Dgtk_doc=false - meson compile -C _build - eval `dbus-launch --sh-syntax` - export XDG_CONFIG_HOME=$HOME/.config @@ -113,11 +113,30 @@ fedora:coverage: # https://github.com/linux-test-project/lcov/issues/58 allow_failure: true +reference: + stage: build + image: fedora:35 + before_script: + - dnf install -y $DEPENDENCIES gi-docgen gobject-introspection-devel libgcrypt-devel + variables: + MESON_ARGS: >- + -Dgtk_doc=true + -Dvapi=false + -Dmanpage=false + script: + - meson ${MESON_ARGS} _build + - ninja -C _build + - mv _build/docs/reference/libsecret/libsecret-1 _reference + artifacts: + paths: + - _reference + pages: stage: deploy script: - mkdir public - mv _build/meson-logs/coveragereport public/coverage + - mv _reference/* public/ artifacts: when: on_success paths: diff --git a/README.md b/README.md index c255a52..ad1353a 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,11 @@ methods so consumers do not have to call the low-level DBus methods. The actual Secret Service API spec can be found at https://specifications.freedesktop.org/secret-service/. +Documentation +-------- + +You can find the nighlt documentation at https://gnome.pages.gitlab.gnome.org/libsecret/. + Building -------- diff --git a/docs/reference/libsecret/libsecret-c-examples.md b/docs/reference/libsecret/libsecret-c-examples.md new file mode 100644 index 0000000..4eebffb --- /dev/null +++ b/docs/reference/libsecret/libsecret-c-examples.md @@ -0,0 +1,251 @@ +Title: C Examples +Slug: libsecret-c-example + +# C Examples + +## 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: + +```c +// 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; +} +``` + +See the [other examples](#store-a-password) for how to use the schema. + +## 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](#define-a-password-schema). + +This first example stores a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```c +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); +``` + +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 +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 */ +} +``` + +## 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](#define-a-password-schema). + +This first example looks up a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```c +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); +``` + +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 +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); +} +``` + + +## 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](#define-a-password-schema). + +This first example removes a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```c +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); +``` + +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 +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 */ +} +``` diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml deleted file mode 100644 index 210f21a..0000000 --- a/docs/reference/libsecret/libsecret-docs.sgml +++ /dev/null @@ -1,47 +0,0 @@ - - -]> - - - Libsecret Library Reference Manual - - for libsecret &version;. - An online version of this documentation can be found at - https://developer.gnome.org/libsecret/unstable/. - - - - - Simple API - - - - - - - - Complete API - - - - - - - - - - - - - - - - - - - - - - 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 @@ - - -]> - - 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. - - -
- - - - - Vala examples - -
- Vala 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. -
- -
- Vala 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. - - (); - 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 */ - }); - ]]> - - If you are already inside of an async function, you can also - use the yield keyword: - - (); - 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); - ]]> - - If you would like to avoid creating a hash table for the - attributes you can just use the variadic version: - - - - 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. - - -
- -
- Vala 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. - - (); - 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); - }); - ]]> - - 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. - - -
- -
- Vala 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. - - (); - 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); - }); - ]]> - - This next example removes a password synchronously. The function - call will block until the removal completes. So this is appropriate for - non GUI applications. - - (); - 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 */ - ]]> -
- - - - diff --git a/docs/reference/libsecret/libsecret-js-examples.md b/docs/reference/libsecret/libsecret-js-examples.md new file mode 100644 index 0000000..ad98679 --- /dev/null +++ b/docs/reference/libsecret/libsecret-js-examples.md @@ -0,0 +1,170 @@ +Title: Javascript Examples +Slug: libsecret-js-example + +# Javascript examples + +## 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: + +```js +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, + } +); +``` + +See the [other examples](#store-a-password) for how +to use the schema. + +## 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](#define-a-password-schema). + +This first example stores a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```js +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); +``` + +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. + +```js +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); +``` + +## 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](#define-a-password-schema). + +This first example looks up a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```js +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); +``` + +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. + +```js +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 */ +``` + + +## 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](#define-a-password-schema). + +This first example removes a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```js +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); +``` + +This next example removes a password synchronously. The function +call will block until the removal completes. So this is appropriate for +non GUI applications. + +```js +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 */ +``` diff --git a/docs/reference/libsecret/libsecret-overrides.txt b/docs/reference/libsecret/libsecret-overrides.txt deleted file mode 100644 index 13f485f..0000000 --- a/docs/reference/libsecret/libsecret-overrides.txt +++ /dev/null @@ -1,2 +0,0 @@ -# These are manually-edited to override or add declarations to those scanned -# from the header files. diff --git a/docs/reference/libsecret/libsecret-python-examples.md b/docs/reference/libsecret/libsecret-python-examples.md new file mode 100644 index 0000000..b9c0b7d --- /dev/null +++ b/docs/reference/libsecret/libsecret-python-examples.md @@ -0,0 +1,152 @@ +Title: Python Examples +Slug: libsecret-python-example + +# Python examples + +## 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: + +```python +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, + } +) +``` + +See the [other examples](#store-a-password) for how +to use the schema. + + +## 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](#define-a-password-schema). + +This first example stores a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```python +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) +``` + +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 +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) +``` + +## 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](#define-a-password-schema). + +This first example looks up a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```python +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) +``` + +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 +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 +``` + +## 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](#define-a-password-schema). + +This first example removes a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```python +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) +``` + +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 +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 +``` diff --git a/docs/reference/libsecret/libsecret-sections.txt b/docs/reference/libsecret/libsecret-sections.txt deleted file mode 100644 index 1b225fe..0000000 --- a/docs/reference/libsecret/libsecret-sections.txt +++ /dev/null @@ -1,389 +0,0 @@ -
-secret-collection -libsecret/secret.h -SecretCollection -SecretCollectionClass -SecretCollectionFlags -secret_collection_for_alias -secret_collection_for_alias_finish -secret_collection_for_alias_sync -secret_collection_load_items -secret_collection_load_items_finish -secret_collection_load_items_sync -secret_collection_create -secret_collection_create_finish -secret_collection_create_sync -secret_collection_search -secret_collection_search_finish -secret_collection_search_sync -secret_collection_delete -secret_collection_delete_finish -secret_collection_delete_sync -secret_collection_get_created -secret_collection_get_service -secret_collection_get_flags -secret_collection_get_items -secret_collection_get_label -secret_collection_set_label -secret_collection_set_label_finish -secret_collection_set_label_sync -secret_collection_get_locked -secret_collection_get_modified -secret_collection_refresh - -SECRET_COLLECTION -SECRET_COLLECTION_CLASS -SECRET_COLLECTION_GET_CLASS -SECRET_IS_COLLECTION -SECRET_IS_COLLECTION_CLASS -SECRET_TYPE_COLLECTION -SECRET_TYPE_COLLECTION_FLAGS -SecretCollectionPrivate -secret_collection_get_type -secret_collection_flags_get_type -SecretCollectionCreateFlags -SECRET_TYPE_COLLECTION_CREATE_FLAGS -secret_collection_create_flags_get_type -
- -
-secret-item -libsecret/secret.h -SecretItem -SecretItemClass -SecretItemFlags -SecretItemCreateFlags -secret_item_create -secret_item_create_finish -secret_item_create_sync -secret_item_delete -secret_item_delete_finish -secret_item_delete_sync -secret_item_get_schema_name -secret_item_get_attributes -secret_item_set_attributes -secret_item_set_attributes_finish -secret_item_set_attributes_sync -secret_item_get_created -secret_item_get_label -secret_item_set_label -secret_item_set_label_finish -secret_item_set_label_sync -secret_item_get_flags -secret_item_get_locked -secret_item_get_modified -secret_item_get_service -secret_item_get_secret -secret_item_load_secret -secret_item_load_secret_finish -secret_item_load_secret_sync -secret_item_load_secrets -secret_item_load_secrets_finish -secret_item_load_secrets_sync -secret_item_set_secret -secret_item_set_secret_finish -secret_item_set_secret_sync -secret_item_refresh - -SECRET_IS_ITEM -SECRET_IS_ITEM_CLASS -SECRET_ITEM -SECRET_ITEM_CLASS -SECRET_ITEM_GET_CLASS -SECRET_TYPE_ITEM -SECRET_TYPE_ITEM_FLAGS -SecretItemPrivate -secret_item_get_type -secret_item_flags_get_type -SECRET_TYPE_ITEM_CREATE_FLAGS -secret_item_create_flags_get_type -
- -
-secret-error -libsecret/secret.h -SECRET_ERROR -SecretError - -SECRET_TYPE_ERROR -secret_error_get_quark -secret_error_get_type -
- -
-secret-password -libsecret/secret.h -SECRET_COLLECTION_DEFAULT -SECRET_COLLECTION_SESSION -secret_password_store -secret_password_storev -secret_password_store_finish -secret_password_store_sync -secret_password_storev_sync -secret_password_store_binary -secret_password_store_binary_sync -secret_password_storev_binary -secret_password_storev_binary_sync -secret_password_lookup -secret_password_lookupv -secret_password_lookup_finish -secret_password_lookup_nonpageable_finish -secret_password_lookup_sync -secret_password_lookup_nonpageable_sync -secret_password_lookupv_sync -secret_password_lookupv_nonpageable_sync -secret_password_lookup_binary_finish -secret_password_lookup_binary_sync -secret_password_lookupv_binary_sync -secret_password_clear -secret_password_clearv -secret_password_clear_finish -secret_password_clear_sync -secret_password_clearv_sync -secret_password_search -secret_password_search_finish -secret_password_search_sync -secret_password_searchv -secret_password_searchv_sync -secret_password_wipe -secret_password_free -
- -
-secret-retrievable -libsecret/secret.h -SECRET_TYPE_RETRIEVABLE -SecretRetrievable -SecretRetrievableInterface -secret_retrievable_get_attributes -secret_retrievable_get_created -secret_retrievable_get_label -secret_retrievable_get_modified -secret_retrievable_retrieve_secret -secret_retrievable_retrieve_secret_finish -secret_retrievable_retrieve_secret_sync -
- -
-secret-schema -libsecret/secret.h -SECRET_SCHEMA_NOTE -SECRET_SCHEMA_COMPAT_NETWORK -SecretSchema -SecretSchemaFlags -SecretSchemaAttribute -SecretSchemaAttributeType -secret_schema_new -secret_schema_newv -secret_schema_ref -secret_schema_unref -SecretSchemaType -secret_get_schema - -secret_schema_get_type -secret_schema_attribute_get_type -secret_schema_attribute_type_get_type -secret_schema_flags_get_type -SECRET_TYPE_SCHEMA_FLAGS -SECRET_TYPE_SCHEMA_ATTRIBUTE_TYPE -
- -
-secret-prompt -libsecret/secret.h -SecretPrompt -SecretPromptClass -secret_prompt_perform -secret_prompt_perform_finish -secret_prompt_perform_sync -secret_prompt_run - -SECRET_IS_PROMPT -SECRET_IS_PROMPT_CLASS -SECRET_PROMPT -SECRET_PROMPT_CLASS -SECRET_PROMPT_GET_CLASS -SECRET_TYPE_PROMPT -SecretPromptPrivate -secret_prompt_get_type -
- -
-secret-service -libsecret/secret.h -SecretService -SecretServiceClass -SecretServiceFlags -secret_service_get -secret_service_get_sync -secret_service_get_finish -secret_service_disconnect -secret_service_open -secret_service_open_finish -secret_service_open_sync -secret_service_get_collections -secret_service_get_flags -secret_service_get_session_algorithms -secret_service_ensure_session -secret_service_ensure_session_finish -secret_service_ensure_session_sync -secret_service_load_collections -secret_service_load_collections_finish -secret_service_load_collections_sync -SecretSearchFlags -secret_service_search -secret_service_search_finish -secret_service_search_sync -secret_service_lock -secret_service_lock_finish -secret_service_lock_sync -secret_service_unlock -secret_service_unlock_finish -secret_service_unlock_sync -secret_service_store -secret_service_store_finish -secret_service_store_sync -secret_service_lookup -secret_service_lookup_finish -secret_service_lookup_sync -secret_service_clear -secret_service_clear_finish -secret_service_clear_sync -secret_service_prompt -secret_service_prompt_finish -secret_service_prompt_sync -secret_service_set_alias -secret_service_set_alias_finish -secret_service_set_alias_sync -secret_service_get_collection_gtype -secret_service_get_item_gtype - -SECRET_IS_SERVICE -SECRET_IS_SERVICE_CLASS -SECRET_SERVICE -SECRET_SERVICE_CLASS -SECRET_SERVICE_GET_CLASS -SECRET_TYPE_SEARCH_FLAGS -SECRET_TYPE_SERVICE -SECRET_TYPE_SERVICE_FLAGS -SecretServicePrivate -secret_search_flags_get_type -secret_service_flags_get_type -secret_service_get_type -
- -
-secret-paths -libsecret/secret.h -secret_collection_new_for_dbus_path -secret_collection_new_for_dbus_path_finish -secret_collection_new_for_dbus_path_sync -secret_item_new_for_dbus_path -secret_item_new_for_dbus_path_finish -secret_item_new_for_dbus_path_sync -secret_service_get_session_dbus_path -secret_service_search_for_dbus_paths -secret_service_search_for_dbus_paths_finish -secret_service_search_for_dbus_paths_sync -secret_collection_search_for_dbus_paths -secret_collection_search_for_dbus_paths_finish -secret_collection_search_for_dbus_paths_sync -secret_service_get_secrets_for_dbus_paths -secret_service_get_secrets_for_dbus_paths_finish -secret_service_get_secrets_for_dbus_paths_sync -secret_service_get_secret_for_dbus_path -secret_service_get_secret_for_dbus_path_finish -secret_service_get_secret_for_dbus_path_sync -secret_service_lock_dbus_paths -secret_service_lock_dbus_paths_finish -secret_service_lock_dbus_paths_sync -secret_service_unlock_dbus_paths -secret_service_unlock_dbus_paths_finish -secret_service_unlock_dbus_paths_sync -secret_service_prompt_at_dbus_path -secret_service_prompt_at_dbus_path_finish -secret_service_prompt_at_dbus_path_sync -secret_service_create_collection_dbus_path -secret_service_create_collection_dbus_path_finish -secret_service_create_collection_dbus_path_sync -secret_service_create_item_dbus_path -secret_service_create_item_dbus_path_finish -secret_service_create_item_dbus_path_sync -secret_service_delete_item_dbus_path -secret_service_delete_item_dbus_path_finish -secret_service_delete_item_dbus_path_sync -secret_service_read_alias_dbus_path -secret_service_read_alias_dbus_path_finish -secret_service_read_alias_dbus_path_sync -secret_service_set_alias_to_dbus_path -secret_service_set_alias_to_dbus_path_finish -secret_service_set_alias_to_dbus_path_sync -secret_service_encode_dbus_secret -secret_service_decode_dbus_secret -
- -
-secret-value -libsecret/secret.h -SecretValue -secret_value_new -secret_value_new_full -secret_value_get -secret_value_get_text -secret_value_get_content_type -secret_value_ref -secret_value_unref -secret_value_unref_to_password - -SECRET_TYPE_VALUE -secret_value_get_type -
- -
-secret-attributes -libsecret/secret.h -secret_attributes_build -secret_attributes_buildv -
- -
-SecretGenService -
- -
-SecretGenCollection -
- -
-SecretGenItem -
- -
-SecretGenSession -
- -
-SecretGenPrompt -
- -
-secret-backend -SECRET_BACKEND_EXTENSION_POINT_NAME -SECRET_TYPE_BACKEND -SECRET_TYPE_BACKEND_FLAGS -SECRET_TYPE_SCHEMA_TYPE -SecretBackend -SecretBackendFlags -SecretBackendInterface -secret_backend_flags_get_type -secret_backend_get -secret_backend_get_finish -
- -
-secret-version -SECRET_CHECK_VERSION -SECRET_MAJOR_VERSION -SECRET_MICRO_VERSION -SECRET_MINOR_VERSION -
diff --git a/docs/reference/libsecret/libsecret-simple-api.md b/docs/reference/libsecret/libsecret-simple-api.md new file mode 100644 index 0000000..b6fda5e --- /dev/null +++ b/docs/reference/libsecret/libsecret-simple-api.md @@ -0,0 +1,95 @@ +Title: Simple API +Slug: libsecret-simple-api + +# Simple API + +## SecretPassword + +Simple password storage and lookup. + +This is a simple API for storing passwords and retrieving passwords in the +Secret Service. + +Each password is associated with a set of attributes. Attribute values can be +either strings, integers or booleans. + +The names and types of allowed attributes for a given password are defined with +a schema. Certain schemas are predefined. Additional schemas can be defined via +the [struct@Schema] structure. + +Each of the functions accept a variable list of attributes names and their +values. Include a `NULL` to terminate the list of attributes. + +## SecretSchema + +Represents a set of attributes that are stored with an item. These schemas are +used for interoperability between various services storing the same types of +items. + +Each schema has a name like `org.gnome.keyring.NetworkPassword`, and defines a +set of attributes, and types (string, integer, boolean) for those attributes. + +Attributes are stored as strings in the Secret Service, and the attribute types +simply define standard ways to store integer and boolean values as strings. +Attributes are represented in libsecret via a [struct@GLib.HashTable] with +string keys and values. Even for values that defined as an integer or boolean in +the schema, the attribute values in the [struct@GLib.HashTable] are strings. +Boolean values are stored as the strings 'true' and 'false'. Integer values are +stored in decimal, with a preceding negative sign for negative integers. + +Schemas are handled entirely on the client side by this library. The name of the +schema is automatically stored as an attribute on the item. + +Normally when looking up passwords only those with matching schema names are +returned. If the schema @flags contain the `SECRET_SCHEMA_DONT_MATCH_NAME` flag, +then lookups will not check that the schema name matches that on the item, only +the schema's attributes are matched. This is useful when you are looking up +items that are not stored by the libsecret library. Other libraries such as +libgnome-keyring don't store the schema name. + +Additional schemas can be defined via the %SecretSchema structure like this: + +```c +// 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; +} +``` + +## Secret Attributes + +Each item has a set of attributes, which are used to locate the item later. +These are not stored or transferred in a secure manner. Each attribute has a +string name and a string value. These attributes are represented by a +[struct@GLib.HashTable] with string keys and values. + +Use [func@attributes_build] to simply build up a set of attributes. + +## DBus Path Related Functions + +Secret Service functions which operate on DBus object paths + +These are low level functions which operate on DBus object paths of collections +or items, instead of the [class@Collection] or [class@Item] objects themselves. + +You can use these functions if you wish to manage access to the secret service +using the DBus API directly, and only wish to use a few calls in libsecret. diff --git a/docs/reference/libsecret/libsecret-tpm2.md b/docs/reference/libsecret/libsecret-tpm2.md new file mode 100644 index 0000000..b63de75 --- /dev/null +++ b/docs/reference/libsecret/libsecret-tpm2.md @@ -0,0 +1,69 @@ +Title: Extending file backend to use a TPM +Slug: libsecret-tpm2 + +# Extending file backend to use a TPM + +## Introduction + +The current implementation of file backend uses an encryption key derived from +the user's login password. Security wise this not an ideal situation. Because, +the entire security of the file backend relies on the user's login password +(single point of failure). This situation can be improved if the keys are +protected/generated by hardware. A Trusted Platform Module (TPM) is a such +hardware security module found in modern computer systems. + +The new `EGG_TPM2` API based on the "TSS Enhanced System API (ESAPI)" + +```c +EggTpm2Context *egg_tpm2_initialize (GError **); +void egg_tpm2_finalize (EggTpm2Context *); +GBytes *egg_tpm2_generate_master_password (EggTpm2Context *, + GError **); +GBytes *egg_tpm2_decrypt_master_password (EggTpm2Context *, + GBytes *, + GError **); +``` + +## Build and test libsecret with TPM2 support + +In order to try out the `TPM2 support` use the `-Dtpm2=true` build option/flag +during the `meson _build` process. + +You can alter the default build and install process as the following: + +```sh +meson _build -Dtpm2=true +ninja -C _build +ninja -C _build install +``` + +For testing the TPM2 support you need a physical TPM or a TPM emulator. The +following sections demonstrate how to setup +[swtpm](https://github.com/stefanberger/swtpm) emulator and testing out the TPM2 +support. If you have access to a TPM you can ignore the emulator section. + +swtpm emulator setup: + +```sh +dnf install swtpm swtpm-tools tpm2-abrmd tpm2-tss-devel +eval `dbus-launch --sh-syntax` +export XDG_CONFIG_HOME=$HOME/.config/swtpm +/usr/share/swtpm/swtpm-create-user-config-files --root +mkdir -p ${XDG_CONFIG_HOME}/mytpm1 +swtpm_setup --tpm2 --tpmstate $XDG_CONFIG_HOME/mytpm1 --createek --allow-signing --decryption --create-ek-cert --create-platform-cert --lock-nvram --overwrite --display +swtpm socket --tpm2 --tpmstate dir=$XDG_CONFIG_HOME/mytpm1 --flags startup-clear --ctrl type=tcp,port=2322 --server type=tcp,port=2321 --daemon +tpm2-abrmd --logger=stdout --tcti=swtpm: --session --allow-root --flush-all & +export TCTI=tabrmd:bus_type=session +``` + +Test TPM2 support: + +```sh +cd libsecret +meson _build -Dtpm2=true +ninja -C _build +export SECRET_BACKEND=file +export SECRET_FILE_TEST_PATH=$PWD/keyring +./_build/tool/secret-tool store --label=foo bar baz +ls # keyring +``` diff --git a/docs/reference/libsecret/libsecret-tpm2.sgml b/docs/reference/libsecret/libsecret-tpm2.sgml deleted file mode 100644 index 184e26a..0000000 --- a/docs/reference/libsecret/libsecret-tpm2.sgml +++ /dev/null @@ -1,67 +0,0 @@ - - - -Extending file backend to use a TPM - - -Introduction - -The current implementation of file backend uses an encryption key derived from the user's login password. Security wise this not an ideal situation. Because, the entire security of the file backend relies on the user's login password (single point of failure). This situation can be improved if the keys are protected/generated by hardware. A Trusted Platform Module (TPM) is a such hardware security module found in modern computer systems. - -The new EGG_TPM2 API based on the TSS Enhanced System API (ESAPI) - - -EggTpm2Context *egg_tpm2_initialize (GError **); -void egg_tpm2_finalize (EggTpm2Context *); -GBytes *egg_tpm2_generate_master_password (EggTpm2Context *, - GError **); -GBytes *egg_tpm2_decrypt_master_password (EggTpm2Context *, - GBytes *, - GError **); - - - - -Build and test libsecret with TPM2 support - -In order to try out the TPM2 support use the -Dtpm2=true build option/flag during the meson _build process. - -You can alter the default build and install process as the following: - - -$ meson _build -Dtpm2=true -$ ninja -C _build -$ ninja -C _build install - - -For testing the TPM2 support you need a physical TPM or a TPM emulator. The following sections demonstrate how to setup swtpm emulator and testing out the TPM2 support. If you have access to a TPM you can ignore the emulator section. - -swtpm emulator setup: - - -$ dnf install swtpm swtpm-tools tpm2-abrmd tpm2-tss-devel -$ eval `dbus-launch --sh-syntax` -$ export XDG_CONFIG_HOME=$HOME/.config/swtpm -$ /usr/share/swtpm/swtpm-create-user-config-files --root -$ mkdir -p ${XDG_CONFIG_HOME}/mytpm1 -$ swtpm_setup --tpm2 --tpmstate $XDG_CONFIG_HOME/mytpm1 --createek --allow-signing --decryption --create-ek-cert --create-platform-cert --lock-nvram --overwrite --display -$ swtpm socket --tpm2 --tpmstate dir=$XDG_CONFIG_HOME/mytpm1 --flags startup-clear --ctrl type=tcp,port=2322 --server type=tcp,port=2321 --daemon -$ tpm2-abrmd --logger=stdout --tcti=swtpm: --session --allow-root --flush-all & -$ export TCTI=tabrmd:bus_type=session - - -Test TPM2 support: - - -$ cd libsecret -$ meson _build -Dtpm2=true -$ ninja -C _build -$ export SECRET_BACKEND=file -$ export SECRET_FILE_TEST_PATH=$PWD/keyring -$ ./_build/tool/secret-tool store --label=foo bar baz -$ ls # keyring - - - diff --git a/docs/reference/libsecret/libsecret-using.md b/docs/reference/libsecret/libsecret-using.md new file mode 100644 index 0000000..bc2eae1 --- /dev/null +++ b/docs/reference/libsecret/libsecret-using.md @@ -0,0 +1,80 @@ +Title: Using libsecret +Slug: libsecret-using + +# Using libsecret in builds or scripts + +## C: Compiling with libsecret + +Like other GNOME libraries, libsecret uses `pkg-config` to provide compiler +options. The package name is `libsecret-1`. So in your `configure.ac` script,you +might specify something like: + +``` +PKG_CHECK_MODULES(LIBSECRET, [libsecret-1 >= 1.0]) +AC_SUBST(LIBSECRET_CFLAGS) +AC_SUBST(LIBSECRET_LIBS) +``` + +Code using libsecret should include the header like this: + +```c +#include ; +``` + +Including individual headers besides the main header files is not permitted and +will cause an error. + +Some parts of the libsecret API are not yet stable. To use them you need use the +`libsecret-unstable` package. The API contained in this package will change from +time to time. Here's how you would do it: + +``` +PKG_CHECK_MODULES(LIBSECRET, [libsecret-unstable >= 1.0]) +AC_SUBST(LIBSECRET_CFLAGS) +AC_SUBST(LIBSECRET_LIBS) +``` + +## Javascript: Importing libsecret + +In Javascript use the standard introspection import mechanism to get at +libsecret: + +```js +const Secret = imports.gi.Secret; + +// ... and here's a sample line of code which uses the import +var schema = new Secret.Schema.new("org.mock.Schema", + Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING }); +``` + + +## Python: Importing libsecret + +In python use the standard introspection import mechanism to get at libsecret: + +```python +from gi.repository import Secret + +# ... and a here's sample line of code which uses the import +schema = Secret.Schema.new("org.mock.Schema", + Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING }) +``` + +## Vala: Compiling with libsecret + +The package name is `libsecret-1`. You can use it like +this in your `Makefile.am` file: + +``` +AM_VALAFLAGS = \ + --pkg=libsecret-1 +``` + +Some parts of the libsecret API are not yet stable. +To use them you need to define the `SECRET_WITH_UNSTABLE` C preprocessor +macro to use them, or else the build will fail: + +``` +AM_CPPFLAGS = \ + -DSECRET_WITH_UNSTABLE=1 +``` diff --git a/docs/reference/libsecret/libsecret-using.sgml b/docs/reference/libsecret/libsecret-using.sgml deleted file mode 100644 index 3043e1e..0000000 --- a/docs/reference/libsecret/libsecret-using.sgml +++ /dev/null @@ -1,112 +0,0 @@ - - - -Using libsecret in builds or scripts - - -C: Compiling with libsecret - -Like other GNOME libraries, libsecret uses -pkg-config to provide compiler options. The package -name is "libsecret-1". So in your -configure.ac script,you might specify something like: - - -PKG_CHECK_MODULES(LIBSECRET, [libsecret-1 >= 1.0]) -AC_SUBST(LIBSECRET_CFLAGS) -AC_SUBST(LIBSECRET_LIBS) - - - -Code using libsecret should include the header like this: - - - -#include <libsecret/secret.h> - - - -Including individual headers besides the main header files is not -permitted and will cause an error. - - - -Some parts of the libsecret API are not yet stable. -To use them you need use the libsecret-unstable package. -The API contained in this package will change from time to time. Here's how -you would do it: - - - -PKG_CHECK_MODULES(LIBSECRET, [libsecret-unstable >= 1.0]) -AC_SUBST(LIBSECRET_CFLAGS) -AC_SUBST(LIBSECRET_LIBS) - - - - - -Javascript: Importing libsecret - - -In javascript use the standard introspection import mechanism to get at -libsecret: - - - -const Secret = imports.gi.Secret; - -// ... and here's a sample line of code which uses the import -var schema = new Secret.Schema.new("org.mock.Schema", - Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING }); - - - - - -Python: Importing libsecret - - -In python use the standard introspection import mechanism to get at -libsecret: - - - -from gi.repository import Secret - -# ... and a here's sample line of code which uses the import -schema = Secret.Schema.new("org.mock.Schema", - Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING }) - - - - - -Vala: Compiling with libsecret - - -The package name is "libsecret-1". You can use it like -this in your Makefile.am file: - - - -AM_VALAFLAGS = \ - --pkg=libsecret-1 - - - -Some parts of the libsecret API are not yet stable. -To use them you need to define the SECRET_WITH_UNSTABLE C preprocessor -macro to use them, or else the build will fail: - - - -AM_CPPFLAGS = \ - -DSECRET_WITH_UNSTABLE=1 - - - - - diff --git a/docs/reference/libsecret/libsecret-vala-examples.md b/docs/reference/libsecret/libsecret-vala-examples.md new file mode 100644 index 0000000..0e64724 --- /dev/null +++ b/docs/reference/libsecret/libsecret-vala-examples.md @@ -0,0 +1,157 @@ +Title: Vala Examples +Slug: libsecret-vala-example + +# Vala Examples + +## 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: + +```vala +var example = new Secret.Schema ("org.example.Password", Secret.SchemaFlags.NONE, + "number", Secret.SchemaAttributeType.INTEGER, + "string", Secret.SchemaAttributeType.STRING, + "even", Secret.SchemaAttributeType.BOOLEAN); +``` + +See the [other examples](#store-a-password) for how +to use the schema. + + +## 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](#define-a-password-schema). + +This first example stores a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```vala +var attributes = new GLib.HashTable (); +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 */ +}); +``` + +If you are already inside of an async function, you can also +use the yield keyword: + +```vala +var attributes = new GLib.HashTable (); +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); +``` + +If you would like to avoid creating a hash table for the +attributes you can just use the variadic version: + +```vala +bool res = yield Secret.password_store (example_schema, Secret.COLLECTION_DEFAULT, "The label", + "the password", null, "number", 8, "string", "eight", + "even", true); +``` + +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. + +```vala +Secret.password_store_sync (example_schema, attributes, Secret.COLLECTION_DEFAULT, + "The label", "the password", null, + "number", 9, "string", "nine", "even", false); +``` + +## 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](#define-a-password-schema). + +This first example looks up a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```vala +var attributes = new GLib.HashTable (); +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); +}); +``` + +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. + +```vala +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 */ +``` + +## 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](#define-a-password-schema). + +This first example removes a password asynchronously, and is +appropriate for GUI applications so that the UI does not block. + +```vala +var attributes = new GLib.HashTable (); +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); +}); +``` + +This next example removes a password synchronously. The function +call will block until the removal completes. So this is appropriate for +non GUI applications. + +```vala +var attributes = new GLib.HashTable (); +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 */ +``` diff --git a/docs/reference/libsecret/libsecret.toml.in b/docs/reference/libsecret/libsecret.toml.in new file mode 100644 index 0000000..5af2ac4 --- /dev/null +++ b/docs/reference/libsecret/libsecret.toml.in @@ -0,0 +1,52 @@ +[library] +version = "@VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/libsecret" +repository_url = "https://gitlab.gnome.org/GNOME/libsecret.git" +docs_url = "https://gnome.pages.gitlab.gnome.org/libsecret/" +website_url = "https://gnome.pages.gitlab.gnome.org/libsecret/" +authors = "Stef Walter, Daiki Ueno, and Niels De Graef" +license = "LGPL-2.1-or-later" +description = "Secret Service D-Bus client library" +dependencies = [ "GObject-2.0", "GLib-1.0", "Gio-2.0" ] +devhelp = true +search_index = true + +[dependencies."GObject-2.0"] +name = "GObject" +description = "The base type system library" +docs_url = "https://docs.gtk.org/gobject/" + +[dependencies."GLib-2.0"] +name = "GLib" +description = "The base type system library" +docs_url = "https://docs.gtk.org/glib/" + +[dependencies."Gio-2.0"] +name = "GIO" +description = "GObject Interfaces and Objects, Networking, IPC, and I/O" +docs_url = "https://docs.gtk.org/gio/" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/libsecret/-/blob/master" + +[extra] +# The same order will be used when generating the index +content_files = [ + 'libsecret-using.md', + 'libsecret-simple-api.md', + "libsecret-c-examples.md", + "libsecret-js-examples.md", + "libsecret-python-examples.md", + "libsecret-vala-examples.md", + "libsecret-tpm2.md", + "migrating-libgnome-keyring.md", +] + +content_images = [ +] +urlmap_file = "urlmap.js" diff --git a/docs/reference/libsecret/libsecret.types b/docs/reference/libsecret/libsecret.types deleted file mode 100644 index f9bfa7a..0000000 --- a/docs/reference/libsecret/libsecret.types +++ /dev/null @@ -1,7 +0,0 @@ -secret_collection_get_type -secret_error_get_type -secret_item_get_type -secret_prompt_get_type -secret_value_get_type -secret_service_flags_get_type -secret_service_get_type \ No newline at end of file diff --git a/docs/reference/libsecret/meson.build b/docs/reference/libsecret/meson.build index d342c58..ac4dfaa 100644 --- a/docs/reference/libsecret/meson.build +++ b/docs/reference/libsecret/meson.build @@ -1,39 +1,48 @@ -reference_content_files = [ - 'libsecret-examples.sgml', - 'libsecret-using.sgml', - 'libsecret-tpm2.sgml', - 'migrating-libgnome-keyring.xml', +expand_content_md_files = [ + 'libsecret-c-examples.md', + 'libsecret-js-examples.md', + 'libsecret-python-examples.md', + 'libsecret-simple-api.md', + 'libsecret-tpm2.md', + 'libsecret-using.md', + 'libsecret-vala-examples.md', + 'migrating-libgnome-keyring.md', ] -# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded -reference_expanded_content_files = [ - 'migrating-libgnome-keyring.xml', -] +toml_data = configuration_data() +toml_data.set('VERSION', meson.project_version()) -reference_ignore_headers = [ - 'mock-service.h', - 'secret-dbus-generated.h', - 'secret-private.h', -] - -configure_file( - input: 'version.xml.in', - output: '@BASENAME@', - configuration: {'VERSION': meson.project_version()}, +libsecret_toml = configure_file( + input: 'libsecret.toml.in', + output: 'libsecret.toml', + configuration: toml_data ) -gnome.gtkdoc('libsecret', - main_sgml: 'libsecret-docs.sgml', - content_files: reference_content_files, - src_dir: include_directories('../../../libsecret'), - dependencies: libsecret_dep, - gobject_typesfile: 'libsecret.types', - mkdb_args: '--expand-content-files=' + ' '.join(reference_expanded_content_files), - scan_args: [ - '--deprecated-guards=SECRET_DISABLE_DEPRECATED', - '--rebuild-types', - '--ignore-headers=' + ' '.join(reference_ignore_headers), +dependency('gi-docgen', version: '>= 2021.7', + fallback: ['gi-docgen', 'dummy_dep'], + native: true, + required: get_option('gtk_doc')) + +gidocgen = find_program('gi-docgen') + +docs_dir = get_option('datadir') / 'doc' + +custom_target('libsecret-doc', + input: [ libsecret_toml, libsecret_gir[0] ], + output: 'libsecret-@0@'.format(api_version_major), + command: [ + gidocgen, + 'generate', + '--quiet', + '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../libsecret'), + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT1@', ], - module_version: api_version_major, + depend_files: [ expand_content_md_files ], + build_by_default: true, install: true, + install_dir: docs_dir, ) diff --git a/docs/reference/libsecret/migrating-libgnome-keyring.md b/docs/reference/libsecret/migrating-libgnome-keyring.md new file mode 100644 index 0000000..43de06d --- /dev/null +++ b/docs/reference/libsecret/migrating-libgnome-keyring.md @@ -0,0 +1,823 @@ +Title: Migrating from libgnome-keyring +Slug: migrating-libgnome-keyring + +# Migrating from libgnome-keyring + +## Introduction + +Conceptually, libgnome-keyring and libsecret are fairly similar. Both +have keyrings, items, and ways to store and retrieve passwords. In both +cases items have attributes. The keys and values of attributes are used +to lookup a password that was stored. + +There is a +simple password API for storing and retrieving passwords +which is the easiest and recommended way to store passwords. And then +there is a more complicated API which models all the various collections +and items, along with all the possible actions that can be performed on them. + +libsecret uses the +Secret Service DBus API +to communicate with gnome-keyring-daemon, and as such exposes features +based on that DBus API. + +libsecret has been designed to be threadsafe, and uses the 'GDBus' +code in gio to accomplish this. + +Keyrings are called 'collections' in libsecret. + +See the relevant section for specifics about how to port the +libgnome-keyring functions or symbols in your project. + +## API conversion + +Here are some clues on how to migrate various libgnome-keyring +API functions and their logical equivalents in libsecret. + +### Item attributes + +Remember that attributes are not, and never have been stored in +an encrypted fashion. They are not part of the 'secret', but instead +are a way to lookup a secret item. + +All attributes in libsecret are stored as strings. Sets of attributes +are represented by [struct@GLib.HashTable]s and the keys and values of +these hash tables are strings. + +libsecret is far more focused on schemas, +and encourages users to define a [struct@Schema] for their password storage. +The schema defines which attributes are allowed an item. Each schema has +a name which is usually a dotted string (eg: `org.gnome.MyProject.Password`). +This schema name is stored internally in the item attributes. + +Schemas define whether an attribute should look like an integer, +a boolean, or a free-form string. These types are used when validating +the attribute values, even though the attribute values are stored and +matched as strings. Since attribute values are used primarily +for lookup of items it's important that the string representations of +integers and booleans are always identical. Boolean values are stored +as the strings `true` and `false`. +Integer values are stored in decimal, with a preceding negative sign +for negative integers. libsecret facilitates this using the +[func@attributes_build] and [func@attributes_buildv] functions. + +Attributes are meant to be used for lookup of items; they're not +designed to be used as a generic key/value database. Although you can +force libsecret to do the latter, it's better to store your account +information elsewhere if possible, and use libsecret to store the password +or other secret. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
GnomeKeyringAttributeLista [struct@GLib.HashTable] of string keys and values
GnomeKeyringAttributea key/value pair in a [struct@GLib.HashTable] of strings
GnomeKeyringAttributeType[struct@Schema]AttributeType
GNOME_KEYRING_ATTRIBUTE_TYPE_STRINGSECRET_SCHEMA_ATTRIBUTE_STRING
GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32SECRET_SCHEMA_ATTRIBUTE_INTEGER
gnome_keyring_attribute_list_index()use [func@GLib.HashTable.lookup] on the attributes hash table
gnome_keyring_attribute_get_string()use [func@GLib.HashTable.lookup] on the attributes hash table
gnome_keyring_attribute_get_uint32()no equivalent, use [func@GLib.HashTable.lookup]
gnome_keyring_attribute_list_append_string()[func@attributes_build]
gnome_keyring_attribute_list_append_uint32()[func@attributes_build]
gnome_keyring_attribute_list_copy()[func@GLib.HashTable.ref]
gnome_keyring_attribute_list_free()[func@GLib.HashTable.unref]
gnome_keyring_attribute_list_index()no equivalent, use [func@GLib.HashTable.lookup]
gnome_keyring_attribute_list_new()[func@attributes_build]
+ +## Working with schemas + +libsecret is far more focused on schemas, and encourages users to +define a [struct@Schema] for their password storage. The schema defines +which attributes are allowed an item. Each schema has a name which +is usually a dotted string (eg: `org.gnome.MyProject.Password`). +This name is stored in the item attributes. The schema name is also +used when looking up an item, to make sure that the stored schema +matches that used during the lookup. If you wish to lookup items that +were stored by libgnome-keyring, you should specify the +`SECRET_SCHEMA_DONT_MATCH_NAME` flag in the schema so that the schema +name is not matched, since it was not stored by libgnome-keyring. + +Schemas define whether an attribute should look like an integer, +a boolean, or a free-form string. These types are used when validating +the attribute values stored, even though the attribute values are +stored and matched as strings. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
GnomeKeyringPasswordSchema[struct@Schema]
GnomeKeyringPasswordSchemaAttribute[struct@Schema]Attribute
GNOME_KEYRING_ITEM_APPLICATION_SECRETno equivalent
GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORDno equivalent
GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORDno equivalent
GNOME_KEYRING_ITEM_PK_STORAGEno equivalent
GNOME_KEYRING_ITEM_GENERIC_SECRETno equivalent, define a specific schema with an appropriate dotted name
GNOME_KEYRING_ITEM_NETWORK_PASSWORDthe SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses
GNOME_KEYRING_ITEM_NOTEthe SECRET_SCHEMA_NOTE schema
GNOME_KEYRING_NETWORK_PASSWORDthe SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses
+ +## Storing passwords and items + +It's encouraged to use a [struct@Schema] when storing items and +passwords. + +By default most ways of storing an item will now overwrite +another item with the same attributes in the same keyring. To manually +control this behavior use the [func@Item.create]. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
GNOME_KEYRING_DEFAULT[const@COLLECTION_DEFAULT]
GNOME_KEYRING_SESSION[const@COLLECTION_SESSION]
gnome_keyring_store_password()[func@password_store]
gnome_keyring_store_password_sync()[func@password_store_sync]
gnome_keyring_set_network_password()[func@password_store] with SECRET_SCHEMA_COMPAT_NETWORK + although this is not recommended for new uses.
gnome_keyring_set_network_password_sync()[func@password_store_sync] with SECRET_SCHEMA_COMPAT_NETWORK + although this is not recommended for new uses.
gnome_keyring_item_create()[func@Item.create], although using [func@password_store] + is simpler.
gnome_keyring_item_create_sync()[func@Item.create], although using [func@password_store_sync] + is simpler.
+ +## Searching for passwords and items + +In general libsecret tries not to unlocking keyrings +where not necessary. Many search methods only return one item or +password that matches, preferring already unlocked items, and recently stored +items. + +Attributes are meant to be used for lookup of items; they're not +designed to be used as a generic key/value database. Although you can +force libsecret to do the latter, it's better to store your account +information elsewhere if possible, and use libsecret to store the password +or other secret. Because of this many search methods return just the +password or secret. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
gnome_keyring_find_password()[func@password_lookup]
gnome_keyring_find_password_sync()[func@password_lookup_sync]
gnome_keyring_find_items()[method@Service.search], with flags to fine tune behavior
gnome_keyring_find_itemsv()[method@Service.search], with flags to fine tune behavior
gnome_keyring_find_items_sync()[method@Service.search_sync], with flags to fine tune behavior
gnome_keyring_find_itemsv_sync()[method@Service.search], with flags to fine tune behavior
GnomeKeyringFoundno equivalent, [method@Service.search] returns a [struct@GLib.List] of + [class@Item]s, and other methods return passwords directly.
gnome_keyring_found_copy()no equivalent
gnome_keyring_found_free()[method@GObject.Object.unref] on the each of the items returned from + [method@Service.search]
gnome_keyring_found_list_free()[func@GLib.List.free_full] used with [method@GObject.Object.unref] on the items returned from + [method@Service.search]
gnome_keyring_find_network_password()[func@password_lookup] with SECRET_SCHEMA_COMPAT_NETWORK, + although this only returns one password and no attributes
gnome_keyring_find_network_password_sync()[func@password_lookup_sync] with SECRET_SCHEMA_COMPAT_NETWORK, + although this only returns one password and no attributes
GnomeKeyringNetworkPasswordDatano equivalent, [func@password_lookup] gets the password directly + and no attributes
gnome_keyring_network_password_free()no equivalent
gnome_keyring_network_password_list_free()no equivalent
+ +## Removing passwords and icons + +Neither libgnome-keyring or libsecret allow deletion of locked +items. libsecret tries to make it easier to delete all unlocked items +matching certain attributes. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
gnome_keyring_delete_password()[func@password_clear], although we now try to delete + all unlocked matching items
gnome_keyring_delete_password_sync()[func@password_clear_sync], although we now try to delete + all unlocked matching items
gnome_keyring_item_delete()[method@Item.delete]
gnome_keyring_item_delete_sync()[method@Item.delete_sync]
+ +## Item management + +In libsecret items are no longer identified by an unsigned integer. +Applications should retrieve items based on their attributes. It is also +possible to identify an item by its DBus object path. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
gnome_keyring_item_create()[func@Item.create], although [func@password_store] may be simpler
gnome_keyring_item_create_sync()[func@Item.create_sync], although [func@password_store_sync] may be simpler
gnome_keyring_item_delete()[method@Item.delete], although [func@password_clear] may be simpler
gnome_keyring_item_delete_sync()[method@Item.delete_sync], although [func@password_clear_sync] may be simpler
gnome_keyring_item_get_info()properties are loaded on a [class@Item] automatically, use + [method@Item.load_secret] to load the secret
gnome_keyring_item_get_info_sync()properties are loaded on a [class@Item] automatically, use + [method@Item.load_secret_sync] to load the secret
gnome_keyring_item_get_info_full()properties are loaded on a [class@Item] automatically, use + [method@Item.load_secret] to load the secret
gnome_keyring_item_get_info_full_sync()properties are loaded on a [class@Item] automatically, use + [method@Item.load_secret_sync] to load the secret
gnome_keyring_item_set_info()use the appropriate setter methods on [class@Item]
gnome_keyring_item_set_info_sync()use the appropriate setter methods on [class@Item]
gnome_keyring_item_get_attributes()[method@Item.get_attributes]
gnome_keyring_item_get_attributes_sync()[method@Item.get_attributes]
gnome_keyring_item_set_attributes()[method@Item.set_attributes]
gnome_keyring_item_set_attributes_sync()[method@Item.set_attributes_sync]
GnomeKeyringItemTypereplaced by the name of a [struct@Schema]
GnomeKeyringItemInfo[class@Item]
gnome_keyring_item_info_new()no equivalent
gnome_keyring_item_info_copy()no equivalent
gnome_keyring_item_info_free()[method@GObject.Object.unref] on the [class@Item]
gnome_keyring_item_info_get_display_name()[method@Item.get_label]
gnome_keyring_item_info_set_display_name()[method@Item.set_label]
gnome_keyring_item_info_get_ctime()[method@Item.get_created]
gnome_keyring_item_info_get_mtime()[method@Item.get_modified]
gnome_keyring_item_info_get_type()[method@Item.get_schema_name]
gnome_keyring_item_info_set_type()[method@Item.set_attributes] with appropriate schema
gnome_keyring_item_info_get_secret()[method@Item.get_secret]
gnome_keyring_item_info_set_secret()[method@Item.set_secret] and [method@Item.set_secret_sync]
GNOME_KEYRING_ITEM_INFO_BASICSno equivalent, all basic item properties are loaded on [class@Item] + automatically
GNOME_KEYRING_ITEM_INFO_SECRETuse [method@Item.load_secret] and [method@Item.load_secret_sync] to load + the secret for an item.
gnome_keyring_item_info_set_display_name()
+ +## Keyring management + +In libsecret keyrings are called 'collections'. This is the same +lingo as the underlying Secret Service DBus API. Keyrings are no longer +identified by simple keyring names. Normally applications just use the +default keyrings and these are identified by the aliases +[const@COLLECTION_DEFAULT] and [const@COLLECTION_SESSION]. It is also +possible to identify collections by their DBus object paths. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
gnome_keyring_create()[func@Collection.create]
gnome_keyring_create_sync()[func@Collection.create_sync]
gnome_keyring_delete()[method@Collection.delete]
gnome_keyring_delete_sync()[method@Collection.delete_sync]
gnome_keyring_change_password()no equivalent, use platform specific DBus APIs
gnome_keyring_change_password_sync()no equivalent, use platform specific DBus APIs
gnome_keyring_list_keyring_names()[method@Service.load_collections] and [method@Service.get_collections]
gnome_keyring_list_keyring_names_sync()[method@Service.load_collections_sync] and [method@Service.get_collections]
gnome_keyring_set_default_keyring()[method@Service.set_alias]
gnome_keyring_set_default_keyring_sync()[method@Service.set_alias_sync]
gnome_keyring_get_default_keyring()[func@Collection.for_alias] with [const@COLLECTION_DEFAULT]
gnome_keyring_get_default_keyring_sync()[func@Collection.for_alias_sync] with [const@COLLECTION_DEFAULT]
gnome_keyring_list_item_ids()[method@Collection.load_items] and [method@Collection.get_items]
gnome_keyring_list_item_ids_sync()[method@Collection.load_items_sync] and [method@Collection.get_items]
GnomeKeyringInfo[class@Collection] and properties
gnome_keyring_get_info()no equivalent
gnome_keyring_get_info_sync()no equivalent
gnome_keyring_set_info()no equivalent, use property setters on [class@Collection]
gnome_keyring_set_info_sync()no equivalent, use property setters on [class@Collection]
gnome_keyring_info_free()no equivalent
gnome_keyring_info_copy()no equivalent
gnome_keyring_info_set_lock_on_idle()no equivalent
gnome_keyring_info_get_lock_on_idle()no equivalent
gnome_keyring_info_set_lock_timeout()no equivalent
gnome_keyring_info_get_lock_timeout()no equivalent
gnome_keyring_info_get_mtime()[method@Collection.get_modified]
gnome_keyring_info_get_ctime()[method@Collection.get_created]
gnome_keyring_info_get_is_locked()[method@Collection.get_locked]
+ +## Locking and unlocking + +In libsecret you can unlock items directly, and the result is +(with gnome-keyring daemon) that the enclosing collection will be unlocked. + +It is no longer possible to pass a password to unlock keyrings. +These are automatically prompted for. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
gnome_keyring_unlock()[method@Service.unlock]
gnome_keyring_unlock_sync()[method@Service.unlock_sync]
gnome_keyring_lock()[method@Service.lock]
gnome_keyring_lock_sync()[method@Service.lock_sync]
gnome_keyring_lock_all()no equivalent, use platform specific DBus APIs
gnome_keyring_lock_all_sync()no equivalent, use platform specific DBus APIs
+ +## Non-pageable memory + +libsecret no longer provides a full API for using non-pageable +memory. Use the equivalent API in the Gcr library. + +You can request that passwords are returned in non-pageable +memory by using the [func@password_lookup_nonpageable_sync] and +[func@password_lookup_nonpageable_finish] functions. +In addition the contents of [struct@Value] items is stored in +non-pageable memory, unless the system doesn't support this. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
gnome_keyring_memory_alloc()no equivalent, use Gcr
gnome_keyring_memory_free()[func@password_free], although this only works on strings
gnome_keyring_memory_is_secure()no equivalent, use Gcr
gnome_keyring_memory_new()no equivalent, use Gcr
gnome_keyring_memory_realloc()no equivalent, use Gcr
gnome_keyring_memory_strdup()no equivalent, use [struct@Value] which is ref-counted, or use Gcr
gnome_keyring_memory_try_alloc()no equivalent, use Gcr
gnome_keyring_memory_try_realloc()no equivalent, use Gcr
gnome_keyring_free_password()[func@password_free]
+ +## Errors and cancellation + +libsecret uses standard the standard [class@Gio.Cancellable] idiom +to cancel operations. + +It is not necessary to check whether the keyring daemon is +available before using it. It is started automatically. + +Errors are returned as standard [struct@GLib.Error] in the usual way. +There are fewer errors that are worth handling in an intelligent way, +exceptions are in the #SecretError enumeration. It is not recommended +to display any [struct@GLib.Error] message returned by libsecret to the user. Most +of the possible errors are DBus communication problems or similar. + +Replacements for related libgnome-keyring functions and types +are described below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
libgnome-keyringlibsecret
gnome_keyring_cancel_request()[method@Gio.Cancellable.cancel] on a [class@Gio.Cancellable] passed to the relevant operation
gnome_keyring_is_available()no equivalent, the secret service is autostarted as necessary
gnome_keyring_result_to_message()use the message in the [struct@GLib.Error], although most failures are not appropriate for display to the user
GNOME_KEYRING_RESULT_OKno [struct@GLib.Error] returned
GNOME_KEYRING_RESULT_DENIEDno longer used, item or collection is simply not unlocked
GNOME_KEYRING_RESULT_NO_KEYRING_DAEMONG_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND
GNOME_KEYRING_RESULT_ALREADY_UNLOCKEDno error, success returned
GNOME_KEYRING_RESULT_NO_SUCH_KEYRINGkeyrings no longer have names, accessing an missing DBus object has usual failure
GNOME_KEYRING_RESULT_BAD_ARGUMENTSG_DBUS_ERROR_INVALID_ARGS or precondition failure in libsecret, this is always + a programmer error
GNOME_KEYRING_RESULT_IO_ERRORrelevant DBus errors, or SECRET_ERROR_PROTOCOL
GNOME_KEYRING_RESULT_CANCELLEDG_IO_ERROR_CANCELLED
GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTSno error, simply returns already existing keyring
GNOME_KEYRING_RESULT_NO_MATCHon error, an empty list is returned
gnome_keyring_string_list_free()no equivalent
diff --git a/docs/reference/libsecret/migrating-libgnome-keyring.xml b/docs/reference/libsecret/migrating-libgnome-keyring.xml deleted file mode 100644 index 7f727ec..0000000 --- a/docs/reference/libsecret/migrating-libgnome-keyring.xml +++ /dev/null @@ -1,839 +0,0 @@ - -Migrating from libgnome-keyring - - - Introduction - - Conceptually, libgnome-keyring and libsecret are fairly similar. Both - have keyrings, items, and ways to store and retrieve passwords. In both - cases items have attributes. The keys and values of attributes are used - to lookup a password that was stored. - - There is a - simple password API for storing and retrieving passwords - which is the easiest and recommended way to store passwords. And then - there is a more complicated API which models all the various collections - and items, along with all the possible actions that can be performed on them. - - libsecret uses the - Secret Service DBus API - to communicate with gnome-keyring-daemon, and as such exposes features - based on that DBus API. - - libsecret has been designed to be threadsafe, and uses the 'GDBus' - code in gio to accomplish this. - - Keyrings are called 'collections' in libsecret. - - See the relevant section for specifics about how to port the - libgnome-keyring functions or symbols in your project. - - - - API conversion - Here are some clues on how to migrate various libgnome-keyring - API functions and their logical equivalents in libsecret. - -
- Item attributes - - Remember that attributes are not, and never have been stored in - an encrypted fashion. They are not part of the 'secret', but instead - are a way to lookup a secret item. - - All attributes in libsecret are stored as strings. Sets of attributes - are represented by #GHashTables and the keys and values of - these hash tables are strings. - - libsecret is far more focused on schemas, - and encourages users to define a #SecretSchema for their password storage. - The schema defines which attributes are allowed an item. Each schema has - a name which is usually a dotted string (eg: org.gnome.MyProject.Password). - This schema name is stored internally in the item attributes. - - Schemas define whether an attribute should look like an integer, - a boolean, or a free-form string. These types are used when validating - the attribute values, even though the attribute values are stored and - matched as strings. Since attribute values are used primarily - for lookup of items it's important that the string representations of - integers and booleans are always identical. Boolean values are stored - as the strings true and false. - Integer values are stored in decimal, with a preceding negative sign - for negative integers. libsecret facilitates this using the - secret_attributes_build() and secret_attributes_buildv() functions. - - Attributes are meant to be used for lookup of items; they're not - designed to be used as a generic key/value database. Although you can - force libsecret to do the latter, it's better to store your account - information elsewhere if possible, and use libsecret to store the password - or other secret. - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - #GnomeKeyringAttributeList - a #GHashTable of string keys and values - - - #GnomeKeyringAttribute - a key/value pair in a #GHashTable of strings - - - #GnomeKeyringAttributeType - #SecretSchemaAttributeType - - - %GNOME_KEYRING_ATTRIBUTE_TYPE_STRING - %SECRET_SCHEMA_ATTRIBUTE_STRING - - - %GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32 - %SECRET_SCHEMA_ATTRIBUTE_INTEGER - - - gnome_keyring_attribute_list_index() - use g_hash_table_lookup() on the attributes hash table - - - gnome_keyring_attribute_get_string() - use g_hash_table_lookup() on the attributes hash table - - - gnome_keyring_attribute_get_uint32() - no equivalent, use g_hash_table_lookup() - - - gnome_keyring_attribute_list_append_string() - secret_attributes_build() - - - gnome_keyring_attribute_list_append_uint32() - secret_attributes_build() - - - gnome_keyring_attribute_list_copy() - g_hash_table_ref() - - - gnome_keyring_attribute_list_free() - g_hash_table_unref() - - - gnome_keyring_attribute_list_index() - no equivalent, use g_hash_table_lookup() - - - gnome_keyring_attribute_list_new() - secret_attributes_build() - - -
-
- -
- Working with schemas - - libsecret is far more focused on schemas, and encourages users to - define a #SecretSchema for their password storage. The schema defines - which attributes are allowed an item. Each schema has a name which - is usually a dotted string (eg: org.gnome.MyProject.Password). - This name is stored in the item attributes. The schema name is also - used when looking up an item, to make sure that the stored schema - matches that used during the lookup. If you wish to lookup items that - were stored by libgnome-keyring, you should specify the - %SECRET_SCHEMA_DONT_MATCH_NAME flag in the schema so that the schema - name is not matched, since it was not stored by libgnome-keyring. - - Schemas define whether an attribute should look like an integer, - a boolean, or a free-form string. These types are used when validating - the attribute values stored, even though the attribute values are - stored and matched as strings. - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - #GnomeKeyringPasswordSchema - #SecretSchema - - - #GnomeKeyringPasswordSchemaAttribute - #SecretSchemaAttribute - - - %GNOME_KEYRING_ITEM_APPLICATION_SECRET - no equivalent - - - %GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORD - no equivalent - - - %GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORD - no equivalent - - - %GNOME_KEYRING_ITEM_PK_STORAGE - no equivalent - - - %GNOME_KEYRING_ITEM_GENERIC_SECRET - no equivalent, define a specific schema with an appropriate dotted name - - - %GNOME_KEYRING_ITEM_NETWORK_PASSWORD - the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses - - - %GNOME_KEYRING_ITEM_NOTE - the %SECRET_SCHEMA_NOTE schema - - - %GNOME_KEYRING_NETWORK_PASSWORD - the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses - - -
-
- - -
- Storing passwords and items - - It's encouraged to use a #SecretSchema when storing items and - passwords. - - By default most ways of storing an item will now overwrite - another item with the same attributes in the same keyring. To manually - control this behavior use the secret_item_create(). - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - %GNOME_KEYRING_DEFAULT - %SECRET_COLLECTION_DEFAULT - - - %GNOME_KEYRING_SESSION - %SECRET_COLLECTION_SESSION - - - gnome_keyring_store_password() - secret_password_store() - - - gnome_keyring_store_password_sync() - secret_password_store_sync() - - - gnome_keyring_set_network_password() - secret_password_store() with %SECRET_SCHEMA_COMPAT_NETWORK - although this is not recommended for new uses. - - - gnome_keyring_set_network_password_sync() - secret_password_store_sync() with %SECRET_SCHEMA_COMPAT_NETWORK - although this is not recommended for new uses. - - - gnome_keyring_item_create() - secret_item_create(), although using secret_password_store() - is simpler. - - - gnome_keyring_item_create_sync() - secret_item_create(), although using secret_password_store_sync() - is simpler. - - -
-
- -
- Searching for passwords and items - - In general libsecret tries not to unlocking keyrings - where not necessary. Many search methods only return one item or - password that matches, preferring already unlocked items, and recently stored - items. - - Attributes are meant to be used for lookup of items; they're not - designed to be used as a generic key/value database. Although you can - force libsecret to do the latter, it's better to store your account - information elsewhere if possible, and use libsecret to store the password - or other secret. Because of this many search methods return just the - password or secret. - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - gnome_keyring_find_password() - secret_password_lookup() - - - gnome_keyring_find_password_sync() - secret_password_lookup_sync() - - - gnome_keyring_find_items() - secret_service_search(), with flags to fine tune behavior - - - gnome_keyring_find_itemsv() - secret_service_search(), with flags to fine tune behavior - - - gnome_keyring_find_items_sync() - secret_service_search_sync(), with flags to fine tune behavior - - - gnome_keyring_find_itemsv_sync() - secret_service_search(), with flags to fine tune behavior - - - GnomeKeyringFound - no equivalent, secret_service_search() returns a #GList of - #SecretItems, and other methods return passwords directly. - - - gnome_keyring_found_copy() - no equivalent - - - gnome_keyring_found_free() - g_object_unref() on the each of the items returned from - secret_service_search() - - - gnome_keyring_found_list_free() - g_list_free_full() used with g_object_unref() on the items returned from - secret_service_search() - - - gnome_keyring_find_network_password() - secret_password_lookup() with %SECRET_SCHEMA_COMPAT_NETWORK, - although this only returns one password and no attributes - - - gnome_keyring_find_network_password_sync() - secret_password_lookup_sync() with %SECRET_SCHEMA_COMPAT_NETWORK, - although this only returns one password and no attributes - - - #GnomeKeyringNetworkPasswordData - no equivalent, secret_password_lookup() gets the password directly - and no attributes - - - gnome_keyring_network_password_free() - no equivalent - - - gnome_keyring_network_password_list_free() - no equivalent - - -
-
- -
- Removing passwords and icons - - Neither libgnome-keyring or libsecret allow deletion of locked - items. libsecret tries to make it easier to delete all unlocked items - matching certain attributes. - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - gnome_keyring_delete_password() - secret_password_clear(), although we now try to delete - all unlocked matching items - - - gnome_keyring_delete_password_sync() - secret_password_clear_sync(), although we now try to delete - all unlocked matching items - - - gnome_keyring_item_delete() - secret_item_delete() - - - gnome_keyring_item_delete_sync() - secret_item_delete_sync() - - -
-
- -
- Item management - - In libsecret items are no longer identified by an unsigned integer. - Applications should retrieve items based on their attributes. It is also - possible to identify an item by its DBus object path. - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - gnome_keyring_item_create() - secret_item_create(), although secret_password_store() may be simpler - - - gnome_keyring_item_create_sync() - secret_item_create_sync(), although secret_password_store_sync() may be simpler - - - gnome_keyring_item_delete() - secret_item_delete(), although secret_password_clear() may be simpler - - - gnome_keyring_item_delete_sync() - secret_item_delete_sync(), although secret_password_clear_sync() may be simpler - - - gnome_keyring_item_get_info() - properties are loaded on a #SecretItem automatically, use - secret_item_load_secret() to load the secret - - - gnome_keyring_item_get_info_sync() - properties are loaded on a #SecretItem automatically, use - secret_item_load_secret_sync() to load the secret - - - gnome_keyring_item_get_info_full() - properties are loaded on a #SecretItem automatically, use - secret_item_load_secret() to load the secret - - - gnome_keyring_item_get_info_full_sync() - properties are loaded on a #SecretItem automatically, use - secret_item_load_secret_sync() to load the secret - - - gnome_keyring_item_set_info() - use the appropriate setter methods on #SecretItem - - - gnome_keyring_item_set_info_sync() - use the appropriate setter methods on #SecretItem - - - gnome_keyring_item_get_attributes() - secret_item_get_attributes() - - - gnome_keyring_item_get_attributes_sync() - secret_item_get_attributes() - - - gnome_keyring_item_set_attributes() - secret_item_set_attributes() - - - gnome_keyring_item_set_attributes_sync() - secret_item_set_attributes_sync() - - - #GnomeKeyringItemType - replaced by the name of a #SecretSchema - - - #GnomeKeyringItemInfo - #SecretItem - - - gnome_keyring_item_info_new() - no equivalent - - - gnome_keyring_item_info_copy() - no equivalent - - - gnome_keyring_item_info_free() - g_object_unref() on the #SecretItem - - - gnome_keyring_item_info_get_display_name() - secret_item_get_label() - - - gnome_keyring_item_info_set_display_name() - secret_item_set_label() - - - gnome_keyring_item_info_get_ctime() - secret_item_get_created() - - - gnome_keyring_item_info_get_mtime() - secret_item_get_modified() - - - gnome_keyring_item_info_get_type() - secret_item_get_schema_name() - - - gnome_keyring_item_info_set_type() - secret_item_set_attributes() with appropriate schema - - - gnome_keyring_item_info_get_secret() - secret_item_get_secret() - - - gnome_keyring_item_info_set_secret() - secret_item_set_secret() and secret_item_set_secret_sync() - - - %GNOME_KEYRING_ITEM_INFO_BASICS - no equivalent, all basic item properties are loaded on #SecretItem - automatically - - - %GNOME_KEYRING_ITEM_INFO_SECRET - use secret_item_load_secret() and secret_item_load_secret_sync() to load - the secret for an item. - - - gnome_keyring_item_info_set_display_name() - - - -
-
- -
- Keyring management - - In libsecret keyrings are called 'collections'. This is the same - lingo as the underlying Secret Service DBus API. Keyrings are no longer - identified by simple keyring names. Normally applications just use the - default keyrings and these are identified by the aliases - %SECRET_COLLECTION_DEFAULT and %SECRET_COLLECTION_SESSION. It is also - possible to identify collections by their DBus object paths. - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - gnome_keyring_create() - secret_collection_create() - - - gnome_keyring_create_sync() - secret_collection_create_sync() - - - gnome_keyring_delete() - secret_collection_delete() - - - gnome_keyring_delete_sync() - secret_collection_delete_sync() - - - gnome_keyring_change_password() - no equivalent, use platform specific DBus APIs - - - gnome_keyring_change_password_sync() - no equivalent, use platform specific DBus APIs - - - gnome_keyring_list_keyring_names() - secret_service_load_collections() and secret_service_get_collections() - - - gnome_keyring_list_keyring_names_sync() - secret_service_load_collections_sync() and secret_service_get_collections() - - - gnome_keyring_set_default_keyring() - secret_service_set_alias() - - - gnome_keyring_set_default_keyring_sync() - secret_service_set_alias_sync() - - - gnome_keyring_get_default_keyring() - secret_collection_for_alias() with %SECRET_COLLECTION_DEFAULT - - - gnome_keyring_get_default_keyring_sync() - secret_collection_for_alias_sync() with %SECRET_COLLECTION_DEFAULT - - - gnome_keyring_list_item_ids() - secret_collection_load_items() and secret_collection_get_items() - - - gnome_keyring_list_item_ids_sync() - secret_collection_load_items_sync() and secret_collection_get_items() - - - #GnomeKeyringInfo - #SecretCollection and properties - - - gnome_keyring_get_info() - no equivalent - - - gnome_keyring_get_info_sync() - no equivalent - - - gnome_keyring_set_info() - no equivalent, use property setters on #SecretCollection - - - gnome_keyring_set_info_sync() - no equivalent, use property setters on #SecretCollection - - - gnome_keyring_info_free() - no equivalent - - - gnome_keyring_info_copy() - no equivalent - - - gnome_keyring_info_set_lock_on_idle() - no equivalent - - - gnome_keyring_info_get_lock_on_idle() - no equivalent - - - gnome_keyring_info_set_lock_timeout() - no equivalent - - - gnome_keyring_info_get_lock_timeout() - no equivalent - - - gnome_keyring_info_get_mtime() - secret_collection_get_modified() - - - gnome_keyring_info_get_ctime() - secret_collection_get_created() - - - gnome_keyring_info_get_is_locked() - secret_collection_get_locked() - - -
-
- -
- Locking and unlocking - - In libsecret you can unlock items directly, and the result is - (with gnome-keyring daemon) that the enclosing collection will be unlocked. - - It is no longer possible to pass a password to unlock keyrings. - These are automatically prompted for. - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - gnome_keyring_unlock() - secret_service_unlock() - - - gnome_keyring_unlock_sync() - secret_service_unlock_sync() - - - gnome_keyring_lock() - secret_service_lock() - - - gnome_keyring_lock_sync() - secret_service_lock_sync() - - - gnome_keyring_lock_all() - no equivalent, use platform specific DBus APIs - - - gnome_keyring_lock_all_sync() - no equivalent, use platform specific DBus APIs - - -
-
- -
- Non-pageable memory - - libsecret no longer provides a full API for using non-pageable - memory. Use the equivalent API in the Gcr library. - - You can request that passwords are returned in non-pageable - memory by using the secret_password_lookup_nonpageable_sync() and - secret_password_lookup_nonpageable_finish() functions. - In addition the contents of #SecretValue items is stored in - non-pageable memory, unless the system doesn't support this. - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - gnome_keyring_memory_alloc() - no equivalent, use Gcr - - - gnome_keyring_memory_free() - secret_password_free(), although this only works on strings - - - gnome_keyring_memory_is_secure() - no equivalent, use Gcr - - - gnome_keyring_memory_new() - no equivalent, use Gcr - - - gnome_keyring_memory_realloc() - no equivalent, use Gcr - - - gnome_keyring_memory_strdup() - no equivalent, use #SecretValue which is ref-counted, or use Gcr - - - gnome_keyring_memory_try_alloc() - no equivalent, use Gcr - - - gnome_keyring_memory_try_realloc() - no equivalent, use Gcr - - - gnome_keyring_free_password() - secret_password_free() - - -
-
- -
- Errors and cancellation - - libsecret uses standard the standard #GCancellable idiom - to cancel operations. - - It is not necessary to check whether the keyring daemon is - available before using it. It is started automatically. - - Errors are returned as standard #GError in the usual way. - There are fewer errors that are worth handling in an intelligent way, - exceptions are in the #SecretError enumeration. It is not recommended - to display any #GError message returned by libsecret to the user. Most - of the possible errors are DBus communication problems or similar. - - Replacements for related libgnome-keyring functions and types - are described below: - - libgnome-keyringlibsecret - - - gnome_keyring_cancel_request() - g_cancellable_cancel() on a #GCancellable passed to the relevant operation - - - gnome_keyring_is_available() - no equivalent, the secret service is autostarted as necessary - - - gnome_keyring_result_to_message() - use the message in the #GError, although most failures are not appropriate for display to the user - - - %GNOME_KEYRING_RESULT_OK - no #GError returned - - - %GNOME_KEYRING_RESULT_DENIED - no longer used, item or collection is simply not unlocked - - - %GNOME_KEYRING_RESULT_NO_KEYRING_DAEMON - %G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND - - - %GNOME_KEYRING_RESULT_ALREADY_UNLOCKED - no error, success returned - - - %GNOME_KEYRING_RESULT_NO_SUCH_KEYRING - keyrings no longer have names, accessing an missing DBus object has usual failure - - - %GNOME_KEYRING_RESULT_BAD_ARGUMENTS - %G_DBUS_ERROR_INVALID_ARGS or precondition failure in libsecret, this is always - a programmer error - - - %GNOME_KEYRING_RESULT_IO_ERROR - relevant DBus errors, or %SECRET_ERROR_PROTOCOL - - - %GNOME_KEYRING_RESULT_CANCELLED - %G_IO_ERROR_CANCELLED - - - %GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTS - no error, simply returns already existing keyring - - - %GNOME_KEYRING_RESULT_NO_MATCH - on error, an empty list is returned - - - gnome_keyring_string_list_free() - no equivalent - - -
-
- - - - diff --git a/docs/reference/libsecret/urlmap.js b/docs/reference/libsecret/urlmap.js new file mode 100644 index 0000000..67e8a25 --- /dev/null +++ b/docs/reference/libsecret/urlmap.js @@ -0,0 +1,6 @@ +// A map between namespaces and base URLs for their online documentation +baseURLs = [ + [ 'GLib', 'https://docs.gtk.org/glib/' ], + [ 'GObject', 'https://docs.gtk.org/gobject/' ], + [ 'Gio', 'https://docs.gtk.org/gio/' ], +] diff --git a/docs/reference/libsecret/version-major.xml.in b/docs/reference/libsecret/version-major.xml.in deleted file mode 100644 index e9450db..0000000 --- a/docs/reference/libsecret/version-major.xml.in +++ /dev/null @@ -1 +0,0 @@ -@SECRET_MAJOR@ \ No newline at end of file diff --git a/docs/reference/libsecret/version.xml.in b/docs/reference/libsecret/version.xml.in deleted file mode 100644 index 27323da..0000000 --- a/docs/reference/libsecret/version.xml.in +++ /dev/null @@ -1 +0,0 @@ -@VERSION@ \ No newline at end of file diff --git a/libsecret/secret-attributes.c b/libsecret/secret-attributes.c index be3597a..603ef7a 100644 --- a/libsecret/secret-attributes.c +++ b/libsecret/secret-attributes.c @@ -19,19 +19,6 @@ #include -/** - * SECTION:secret-attributes - * @title: Secret Attributes - * @short_description: secret attributes - * - * Each item has a set of attributes, which are used to locate the item later. - * These are not stored or transferred in a secure manner. Each attribute has - * a string name and a string value. These attributes are represented by a - * #GHashTable with string keys and values. - * - * Use secret_attributes_build() to simply build up a set of attributes. - */ - GVariant * _secret_attributes_to_variant (GHashTable *attributes, const gchar *schema_name) @@ -87,7 +74,7 @@ _secret_attributes_for_variant (GVariant *variant) * @schema. The list of attributes should be terminated with a %NULL. * * Returns: (transfer full) (element-type utf8 utf8): a new table of - * attributes, to be released with g_hash_table_unref() + * attributes, to be released with [func@GLib.HashTable.unref] */ GHashTable * secret_attributes_build (const SecretSchema *schema, @@ -116,7 +103,7 @@ secret_attributes_build (const SecretSchema *schema, * @schema. The list of attributes should be terminated with a %NULL. * * Returns: (transfer full) (element-type utf8 utf8): a new table of - * attributes, to be released with g_hash_table_unref() + * attributes, to be released with [func@GLib.HashTable.unref] */ GHashTable * secret_attributes_buildv (const SecretSchema *schema, diff --git a/libsecret/secret-backend.c b/libsecret/secret-backend.c index 73f0fd7..c527f82 100644 --- a/libsecret/secret-backend.c +++ b/libsecret/secret-backend.c @@ -25,9 +25,9 @@ #include "libsecret/secret-enum-types.h" /** - * SECTION:secret-backend - * @title: SecretBackend - * @short_description: A backend implementation of password storage + * SecretBackend + * + * A backend implementation of password storage * * #SecretBackend represents a backend implementation of password * storage. @@ -48,14 +48,14 @@ * @parent_iface: the parent interface * @ensure_for_flags: implementation of reinitialization step in constructor, optional * @ensure_for_flags_finish: implementation of reinitialization step in constructor, optional - * @store: implementation of secret_password_store(), required - * @store_finish: implementation of secret_password_store_finish(), required - * @lookup: implementation of secret_password_lookup(), required - * @lookup_finish: implementation of secret_password_lookup_finish(), required - * @clear: implementation of secret_password_clear(), required - * @clear_finish: implementation of secret_password_clear_finish(), required - * @search: implementation of secret_password_search(), required - * @search_finish: implementation of secret_password_search_finish(), required + * @store: implementation of [func@password_store], required + * @store_finish: implementation of [func@password_store_finish], required + * @lookup: implementation of [func@password_lookup], required + * @lookup_finish: implementation of [func@password_lookup_finish], required + * @clear: implementation of [func@password_clear], required + * @clear_finish: implementation of [func@password_clear_finish], required + * @search: implementation of [func@password_search], required + * @search_finish: implementation of [func@password_search_finish], required * * The interface for #SecretBackend. * @@ -264,7 +264,7 @@ secret_backend_get (SecretBackendFlags flags, * Complete an asynchronous operation to get a #SecretBackend. * * Returns: (transfer full): a new reference to a #SecretBackend proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. * * Since: 0.19.0 */ diff --git a/libsecret/secret-collection.c b/libsecret/secret-collection.c index 5e3378d..9f426b7 100644 --- a/libsecret/secret-collection.c +++ b/libsecret/secret-collection.c @@ -27,29 +27,24 @@ #include /** - * SECTION:secret-collection - * @title: SecretCollection - * @short_description: A collection of secret items + * SecretCollection: + * + * A proxy object representing a collection of secrets in the Secret Service. * * #SecretCollection represents a collection of secret items stored in the * Secret Service. * - * A collection can be in a locked or unlocked state. Use secret_service_lock() - * or secret_service_unlock() to lock or unlock the collection. + * A collection can be in a locked or unlocked state. Use + * [method@SecretService.lock] or [method@SecretService.unlock] to lock or + * unlock the collection. * - * Use the SecretCollection::items property or secret_collection_get_items() to - * lookup the items in the collection. There may not be any items exposed when - * the collection is locked. + * Use the [property@SecretCollection:items] property or + * [method@SecretCollection.get_items] to lookup the items in the collection. + * There may not be any items exposed when the collection is locked. * * Stability: Stable */ -/** - * SecretCollection: - * - * A proxy object representing a collection of secrets in the Secret Service. - */ - /** * SecretCollectionClass: * @parent_class: the parent class @@ -69,22 +64,22 @@ * SecretCollectionCreateFlags: * @SECRET_COLLECTION_CREATE_NONE: no flags * - * Flags for secret_collection_create(). + * Flags for [func@Collection.create]. */ /** * SECRET_COLLECTION_DEFAULT: * - * An alias to the default collection. This can be passed to secret_password_store() - * secret_collection_for_alias(). + * An alias to the default collection. This can be passed to + * [func@password_store] [func@Collection.for_alias]. */ /** * SECRET_COLLECTION_SESSION: * * An alias to the session collection, which will be cleared when the user ends - * the session. This can be passed to secret_password_store(), - * secret_collection_for_alias() or similar functions. + * the session. This can be passed to [func@password_store], + * [func@Collection.for_alias] or similar functions. */ enum { @@ -429,9 +424,9 @@ secret_collection_class_init (SecretCollectionClass *klass) proxy_class->g_signal = secret_collection_signal; /** - * SecretCollection:service: + * SecretCollection:service: (attributes org.gtk.Property.get=secret_collection_get_service) * - * The #SecretService object that this collection is associated with and + * The [class@Service] object that this collection is associated with and * uses to interact with the actual D-Bus Secret Service. */ g_object_class_install_property (gobject_class, PROP_SERVICE, @@ -439,7 +434,7 @@ secret_collection_class_init (SecretCollectionClass *klass) SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:flags: + * SecretCollection:flags: (attributes org.gtk.Property.get=secret_collection_get_flags) * * A set of flags describing which parts of the secret collection have * been initialized. @@ -450,9 +445,9 @@ secret_collection_class_init (SecretCollectionClass *klass) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:items: + * SecretCollection:items: (attributes org.gtk.Property.get=secret_collection_get_items) * - * A list of #SecretItem objects representing the items that are in + * A list of [class@Item] objects representing the items that are in * this collection. This list will be empty if the collection is locked. */ g_object_class_install_property (gobject_class, PROP_ITEMS, @@ -460,32 +455,32 @@ secret_collection_class_init (SecretCollectionClass *klass) _secret_list_get_type (), G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:label: + * SecretCollection:label: (attributes org.gtk.Property.get=secret_collection_get_label org.gtk.Property.set=secret_collection_set_label) * * The human readable label for the collection. * * Setting this property will result in the label of the collection being * set asynchronously. To properly track the changing of the label use the - * secret_collection_set_label() function. + * [method@Collection.set_label] function. */ g_object_class_install_property (gobject_class, PROP_LABEL, g_param_spec_string ("label", "Label", "Item label", NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:locked: + * SecretCollection:locked: (attributes org.gtk.Property.get=secret_collection_get_locked) * * Whether the collection is locked or not. * - * To lock or unlock a collection use the secret_service_lock() or - * secret_service_unlock() functions. + * To lock or unlock a collection use the [method@Service.lock] or + * [method@Service.unlock] functions. */ g_object_class_install_property (gobject_class, PROP_LOCKED, g_param_spec_boolean ("locked", "Locked", "Item locked", TRUE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:created: + * SecretCollection:created: (attributes org.gtk.Property.get=secret_collection_get_created) * * The date and time (in seconds since the UNIX epoch) that this * collection was created. @@ -495,7 +490,7 @@ secret_collection_class_init (SecretCollectionClass *klass) 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretCollection:modified: + * SecretCollection:modified: (attributes org.gtk.Property.get=secret_collection_get_modified) * * The date and time (in seconds since the UNIX epoch) that this * collection was last modified. @@ -765,10 +760,10 @@ on_load_item (GObject *source, * * Ensure that the #SecretCollection proxy has loaded all the items present * in the Secret Service. This affects the result of - * secret_collection_get_items(). + * [method@Collection.get_items]. * - * For collections returned from secret_service_get_collections() the items - * will have already been loaded. + * For collections returned from [method@Service.get_collections] the items will + * have already been loaded. * * This method will return immediately and complete asynchronously. */ @@ -859,9 +854,9 @@ secret_collection_load_items_finish (SecretCollection *self, * * Ensure that the #SecretCollection proxy has loaded all the items present * in the Secret Service. This affects the result of - * secret_collection_get_items(). + * [method@Collection.get_items]. * - * For collections returned from secret_service_get_collections() the items + * For collections returned from [method@Service.get_collections] the items * will have already been loaded. * * This method may block indefinitely and should not be used in user interface @@ -1050,7 +1045,7 @@ _secret_collection_properties_new (const gchar *label) * Create a new collection in the secret service. * * This method returns immediately and completes asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that are required. * * An @alias is a well-known tag for a collection, such as 'default' (ie: the @@ -1059,8 +1054,8 @@ _secret_collection_properties_new (const gchar *label) * collection with that alias already exists, then a new collection will not * be created. The previous one will be returned instead. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get the + * default [class@Service] proxy. */ void secret_collection_create (SecretService *service, @@ -1108,7 +1103,7 @@ secret_collection_create (SecretService *service, * Finish operation to create a new collection in the secret service. * * Returns: (transfer full): the new collection, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretCollection * secret_collection_create_finish (GAsyncResult *result, @@ -1140,20 +1135,20 @@ secret_collection_create_finish (GAsyncResult *result, * Create a new collection in the secret service. * * This method may block indefinitely and should not be used in user interface - * threads. The secret service may prompt the user. secret_service_prompt() + * threads. The secret service may prompt the user. [method@Service.prompt] * will be used to handle any prompts that are required. * - * An @alias is a well-known tag for a collection, such as 'default' (ie: the + * An @alias is a well-known tag for a collection, such as `default` (ie: the * default collection to store items in). This allows other applications to * easily identify and share a collection. If you specify an @alias, and a * collection with that alias already exists, then a new collection will not * be created. The previous one will be returned instead. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get the + * default [class@Service] proxy. * * Returns: (transfer full): the new collection, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretCollection * secret_collection_create_sync (SecretService *service, @@ -1395,7 +1390,7 @@ on_search_paths (GObject *source, * search and be returned. If the unlock fails, the search does not fail. * * If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have - * their secret values loaded and available via secret_item_get_secret(). + * their secret values loaded and available via [method@Item.get_secret]. * * This function returns immediately and completes asynchronously. */ @@ -1443,7 +1438,7 @@ secret_collection_search (SecretCollection *self, * Complete asynchronous operation to search for items in a collection. * * Returns: (transfer full) (element-type Secret.Item): - * a list of items that matched the search + * a list of items that matched the search */ GList * secret_collection_search_finish (SecretCollection *self, @@ -1526,13 +1521,13 @@ collection_load_items_sync (SecretCollection *self, * search and be returned. If the unlock fails, the search does not fail. * * If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have - * their secret values loaded and available via secret_item_get_secret(). + * their secret values loaded and available via [method@Item.get_secret]. * * This function may block indefinitely. Use the asynchronous version * in user interface threads. * * Returns: (transfer full) (element-type Secret.Item): - * a list of items that matched the search + * a list of items that matched the search */ GList * secret_collection_search_sync (SecretCollection *self, @@ -1610,7 +1605,7 @@ on_service_delete_path (GObject *source, * Delete this collection. * * This method returns immediately and completes asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that show up. */ void @@ -1671,9 +1666,9 @@ secret_collection_delete_finish (SecretCollection *self, * * Delete this collection. * - * This method may block indefinitely and should not be used in user - * interface threads. The secret service may prompt the user. - * secret_service_prompt() will be used to handle any prompts that show up. + * This method may block indefinitely and should not be used in user interface + * threads. The secret service may prompt the user. [method@Service.prompt] will + * be used to handle any prompts that show up. * * Returns: whether the collection was successfully deleted or not */ @@ -1705,7 +1700,7 @@ secret_collection_delete_sync (SecretCollection *self, } /** - * secret_collection_get_service: + * secret_collection_get_service: (attributes org.gtk.Method.get_property=service) * @self: a collection * * Get the Secret Service object that this collection was created with. @@ -1720,14 +1715,14 @@ secret_collection_get_service (SecretCollection *self) } /** - * secret_collection_get_flags: + * secret_collection_get_flags: (attributes org.gtk.Method.get_property=flags) * @self: the secret collection proxy * * Get the flags representing what features of the #SecretCollection proxy * have been initialized. * - * Use secret_collection_load_items() to initialize further features - * and change the flags. + * Use [method@Collection.load_items] to initialize further features and change + * the flags. * * Returns: the flags for features initialized */ @@ -1749,14 +1744,14 @@ secret_collection_get_flags (SecretCollection *self) } /** - * secret_collection_get_items: + * secret_collection_get_items: (attributes org.gtk.Method.get_property=items) * @self: a collection * * Get the list of items in this collection. * - * Returns: (transfer full) (element-type Secret.Item): a list of items, - * when done, the list should be freed with g_list_free, and each item should - * be released with g_object_unref() + * Returns: (transfer full) (element-type Secret.Item): a list of items, when + * done, the list should be freed with [func@GLib.List.free], and each item + * should be released with [method@GObject.Object.unref] */ GList * secret_collection_get_items (SecretCollection *self) @@ -1792,12 +1787,13 @@ _secret_collection_find_item_instance (SecretCollection *self, } /** - * secret_collection_get_label: + * secret_collection_get_label: (attributes org.gtk.Method.get_property=label) * @self: a collection * * Get the label of this collection. * - * Returns: (transfer full): the label, which should be freed with g_free() + * Returns: (transfer full): the label, which should be freed with + * [func@GLib.free] */ gchar * secret_collection_get_label (SecretCollection *self) @@ -1817,7 +1813,7 @@ secret_collection_get_label (SecretCollection *self) } /** - * secret_collection_set_label: + * secret_collection_set_label: (attributes org.gtk.Method.set_property=label) * @self: a collection * @label: a new label * @cancellable: (nullable): optional cancellation object @@ -1895,12 +1891,12 @@ secret_collection_set_label_sync (SecretCollection *self, } /** - * secret_collection_get_locked: + * secret_collection_get_locked: (attributes org.gtk.Method.get_property=locked) * @self: a collection * * Get whether the collection is locked or not. * - * Use secret_service_lock() or secret_service_unlock() to lock or unlock the + * Use [method@Service.lock] or [method@Service.unlock] to lock or unlock the * collection. * * Returns: whether the collection is locked or not @@ -1923,7 +1919,7 @@ secret_collection_get_locked (SecretCollection *self) } /** - * secret_collection_get_created: + * secret_collection_get_created: (attributes org.gtk.Method.get_property=created) * @self: a collection * * Get the created date and time of the collection. The return value is @@ -1949,7 +1945,7 @@ secret_collection_get_created (SecretCollection *self) } /** - * secret_collection_get_modified: + * secret_collection_get_modified: (attributes org.gtk.Method.get_property=modified) * @self: a collection * * Get the modified date and time of the collection. The return value is @@ -2091,8 +2087,8 @@ on_read_alias_service (GObject *source, * Lookup which collection is assigned to this alias. Aliases help determine * well known collections, such as 'default'. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get the + * default [class@Service] proxy. * * This method will return immediately and complete asynchronously. */ @@ -2167,10 +2163,10 @@ secret_collection_for_alias_finish (GAsyncResult *result, * @error: location to place error on failure * * Lookup which collection is assigned to this alias. Aliases help determine - * well known collections, such as 'default'. + * well known collections, such as `default`. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get the + * default [class@Service] proxy. * * This method may block and should not be used in user interface threads. * diff --git a/libsecret/secret-item.c b/libsecret/secret-item.c index efab923..3c4ddb6 100644 --- a/libsecret/secret-item.c +++ b/libsecret/secret-item.c @@ -29,38 +29,32 @@ #include /** - * SECTION:secret-item - * @title: SecretItem - * @short_description: A secret item + * SecretItem: + * + * A secret item * * #SecretItem represents a secret item stored in the Secret Service. * - * Each item has a value, represented by a #SecretValue, which can be - * retrieved by secret_item_get_secret() or set by secret_item_set_secret(). + * Each item has a value, represented by a [struct@Value], which can be + * retrieved by [method@Item.get_secret] or set by [method@Item.set_secret]. * The item is only available when the item is not locked. * - * Items can be locked or unlocked using the secret_service_lock() or - * secret_service_unlock() functions. The Secret Service may not be able to + * Items can be locked or unlocked using the [method@Service.lock] or + * [method@Service.unlock] functions. The Secret Service may not be able to * unlock individual items, and may unlock an entire collection when a single * item is unlocked. * * Each item has a set of attributes, which are used to locate the item later. * These are not stored or transferred in a secure manner. Each attribute has - * a string name and a string value. Use secret_service_search() to search for - * items based on their attributes, and secret_item_set_attributes() to change + * a string name and a string value. Use [method@Service.search] to search for + * items based on their attributes, and [method@Item.set_attributes] to change * the attributes associated with an item. * - * Items can be created with secret_item_create() or secret_service_store(). + * Items can be created with [func@Item.create] or [method@Service.store]. * * Stability: Stable */ -/** - * SecretItem: - * - * A proxy object representing a secret item in the Secret Service. - */ - /** * SecretItemClass: * @parent_class: the parent class @@ -81,7 +75,7 @@ * @SECRET_ITEM_CREATE_NONE: no flags * @SECRET_ITEM_CREATE_REPLACE: replace an item with the same attributes. * - * Flags for secret_item_create(). + * Flags for [func@Item.create]. */ enum { @@ -335,9 +329,9 @@ secret_item_class_init (SecretItemClass *klass) proxy_class->g_properties_changed = secret_item_properties_changed; /** - * SecretItem:service: + * SecretItem:service: (attributes org.gtk.Property.get=secret_item_get_service) * - * The #SecretService object that this item is associated with and + * The [class@Service] object that this item is associated with and * uses to interact with the actual D-Bus Secret Service. */ g_object_class_install_property (gobject_class, PROP_SERVICE, @@ -345,7 +339,7 @@ secret_item_class_init (SecretItemClass *klass) SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); /** - * SecretItem:flags: + * SecretItem:flags: (attributes org.gtk.Property.get=secret_item_get_flags) * * A set of flags describing which parts of the secret item have * been initialized. @@ -370,18 +364,18 @@ secret_item_class_init (SecretItemClass *klass) * * Setting this property will result in the label of the item being * set asynchronously. To properly track the changing of the label use the - * secret_item_set_label() function. + * [method@Item.set_label] function. */ g_object_class_override_property (gobject_class, PROP_LABEL, "label"); /** - * SecretItem:locked: + * SecretItem:locked: (attributes org.gtk.Property.get=secret_item_get_locked) * * Whether the item is locked or not. An item may not be independently * lockable separate from other items in its collection. * - * To lock or unlock a item use the secret_service_lock() or - * secret_service_unlock() functions. + * To lock or unlock a item use the [method@Service.lock] or + * [method@Service.unlock] functions. */ g_object_class_install_property (gobject_class, PROP_LOCKED, g_param_spec_boolean ("locked", "Locked", "Item locked", @@ -734,7 +728,7 @@ item_properties_new (const gchar *label, * instead of creating a new one. * * This method may block indefinitely and should not be used in user interface - * threads. The secret service may prompt the user. secret_service_prompt() + * threads. The secret service may prompt the user. [method@Service.prompt] * will be used to handle any prompts that are required. */ void @@ -790,7 +784,7 @@ secret_item_create (SecretCollection *collection, * Finish operation to create a new item in the secret service. * * Returns: (transfer full): the new item, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretItem * secret_item_create_finish (GAsyncResult *result, @@ -828,11 +822,11 @@ secret_item_create_finish (GAsyncResult *result, * instead of creating a new one. * * This method may block indefinitely and should not be used in user interface - * threads. The secret service may prompt the user. secret_service_prompt() + * threads. The secret service may prompt the user. [method@Service.prompt] * will be used to handle any prompts that are required. * * Returns: (transfer full): the new item, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretItem * secret_item_create_sync (SecretCollection *collection, @@ -908,7 +902,7 @@ on_item_deleted (GObject *source, * Delete this item. * * This method returns immediately and completes asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that show up. */ void @@ -971,7 +965,7 @@ secret_item_delete_finish (SecretItem *self, * * This method may block indefinitely and should not be used in user * interface threads. The secret service may prompt the user. - * secret_service_prompt() will be used to handle any prompts that show up. + * [method@Service.prompt] will be used to handle any prompts that show up. * * Returns: whether the item was successfully deleted or not */ @@ -1003,13 +997,13 @@ secret_item_delete_sync (SecretItem *self, } /** - * secret_item_get_flags: + * secret_item_get_flags: (attributes org.gtk.Method.get_property=flags) * @self: the secret item proxy * * Get the flags representing what features of the #SecretItem proxy * have been initialized. * - * Use secret_item_load_secret() to initialize further features + * Use [method@Item.load_secret] to initialize further features * and change the flags. * * Returns: the flags for features initialized @@ -1033,7 +1027,7 @@ secret_item_get_flags (SecretItem *self) } /** - * secret_item_get_service: + * secret_item_get_service: (attributes org.gtk.Method.get_property=service) * @self: an item * * Get the Secret Service object that this item was created with. @@ -1055,10 +1049,10 @@ secret_item_get_service (SecretItem *self) * Get the secret value of this item. If this item is locked or the secret * has not yet been loaded then this will return %NULL. * - * To load the secret call the secret_item_load_secret() method. + * To load the secret call the [method@Item.load_secret] method. * * Returns: (transfer full) (nullable): the secret value which should be - * released with secret_value_unref(), or %NULL + * released with [method@Value.unref], or %NULL */ SecretValue * secret_item_get_secret (SecretItem *self) @@ -1189,7 +1183,7 @@ secret_item_load_secret (SecretItem *self, * Complete asynchronous operation to load the secret value of this item. * * The newly loaded secret value can be accessed by calling - * secret_item_get_secret(). + * [method@Item.get_secret]. * * Returns: whether the secret item successfully loaded or not */ @@ -1394,7 +1388,7 @@ on_loads_secrets_session (GObject *source, * * Load the secret values for a secret item stored in the service. * - * The @items must all have the same SecretItem::service property. + * The @items must all have the same [property@Item:service] property. * * This function returns immediately and completes asynchronously. */ @@ -1488,7 +1482,7 @@ secret_item_load_secrets_finish (GAsyncResult *result, * * Load the secret values for a secret item stored in the service. * - * The @items must all have the same SecretItem::service property. + * The @items must all have the same [property@Item:service] property. * * This method may block indefinitely and should not be used in user interface * threads. @@ -1698,7 +1692,7 @@ secret_item_set_secret_sync (SecretItem *self, * @self: an item * * Gets the name of the schema that this item was stored with. This is also - * available at the xdg:schema attribute. + * available at the `xdg:schema` attribute. * * Returns: (nullable) (transfer full): the schema name */ @@ -1730,11 +1724,11 @@ secret_item_get_schema_name (SecretItem *self) * or transferred securely by the secret service. * * Do not modify the attributes returned by this method. Use - * secret_item_set_attributes() instead. + * [method@Item.set_attributes] instead. * * Returns: (transfer full) (element-type utf8 utf8): a new reference - * to the attributes, which should not be modified, and - * released with g_hash_table_unref() + * to the attributes, which should not be modified, and + * released with [func@GLib.HashTable.unref] */ GHashTable * secret_item_get_attributes (SecretItem *self) @@ -1865,7 +1859,7 @@ secret_item_set_attributes_sync (SecretItem *self, * * Get the label of this item. * - * Returns: (transfer full): the label, which should be freed with g_free() + * Returns: (transfer full): the label, which should be freed with [func@GLib.free] */ gchar * secret_item_get_label (SecretItem *self) diff --git a/libsecret/secret-methods.c b/libsecret/secret-methods.c index b9b696e..1101c38 100644 --- a/libsecret/secret-methods.c +++ b/libsecret/secret-methods.c @@ -33,7 +33,7 @@ * @SECRET_SEARCH_UNLOCK: unlock locked items while searching * @SECRET_SEARCH_LOAD_SECRETS: while searching load secrets for items that are not locked * - * Various flags to be used with secret_service_search() and secret_service_search_sync(). + * Various flags to be used with [method@Service.search] and [method@Service.search_sync]. */ typedef struct { @@ -273,8 +273,8 @@ on_search_service (GObject *source, * Search for items matching the @attributes. All collections are searched. * The @attributes should be a table of string keys and string values. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get + * the default [class@Service] proxy. * * If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the * search will be returned. Otherwise only the first item will be returned. @@ -285,7 +285,7 @@ on_search_service (GObject *source, * search and be returned. If the unlock fails, the search does not fail. * * If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items will have - * their secret values loaded and available via secret_item_get_secret(). + * their secret values loaded and available via [method@Item.get_secret]. * * This function returns immediately and completes asynchronously. */ @@ -345,7 +345,7 @@ secret_service_search (SecretService *service, * Complete asynchronous operation to search for items. * * Returns: (transfer full) (element-type Secret.Item): - * a list of items that matched the search + * a list of items that matched the search */ GList * secret_service_search_finish (SecretService *service, @@ -413,8 +413,8 @@ service_load_items_sync (SecretService *service, * Search for items matching the @attributes. All collections are searched. * The @attributes should be a table of string keys and string values. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get + * the default [class@Service] proxy. * * If %SECRET_SEARCH_ALL is set in @flags, then all the items matching the * search will be returned. Otherwise only the first item will be returned. @@ -426,14 +426,14 @@ service_load_items_sync (SecretService *service, * * If %SECRET_SEARCH_LOAD_SECRETS is set in @flags, then the items' secret * values will be loaded for any unlocked items. Loaded item secret values - * are available via secret_item_get_secret(). If the load of a secret values + * are available via [method@Item.get_secret]. If the load of a secret values * fail, then the * * This function may block indefinitely. Use the asynchronous version * in user interface threads. * * Returns: (transfer full) (element-type Secret.Item): - * a list of items that matched the search + * a list of items that matched the search */ GList * secret_service_search_sync (SecretService *service, @@ -735,11 +735,11 @@ service_xlock_finish (SecretService *service, * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get + * the default [class@Service] proxy. * * This method returns immediately and completes asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that show up. */ void @@ -797,12 +797,12 @@ secret_service_lock_finish (SecretService *service, * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user * interface threads. The secret service may prompt the user. - * secret_service_prompt() will be used to handle any prompts that show up. + * [method@Service.prompt] will be used to handle any prompts that show up. * * Returns: the number of items or collections that were locked */ @@ -849,12 +849,12 @@ secret_service_lock_sync (SecretService *service, * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user * interface threads. The secret service may prompt the user. - * secret_service_prompt() will be used to handle any prompts that show up. + * [method@Service.prompt] will be used to handle any prompts that show up. */ void secret_service_unlock (SecretService *service, @@ -911,12 +911,12 @@ secret_service_unlock_finish (SecretService *service, * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user * interface threads. The secret service may prompt the user. - * secret_service_prompt() will be used to handle any prompts that show up. + * [method@Service.prompt] will be used to handle any prompts that show up. * * Returns: the number of items or collections that were unlocked */ @@ -1131,11 +1131,11 @@ on_store_service (GObject *source, * If the attributes match a secret item already stored in the collection, then * the item will be updated with these new values. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get + * the default [class@Service] proxy. * * If @collection is not specified, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method will return immediately and complete asynchronously. @@ -1251,11 +1251,11 @@ secret_service_store_finish (SecretService *service, * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user interface * threads. @@ -1427,8 +1427,8 @@ on_lookup_service (GObject *source, * * The @attributes should be a set of key and value string pairs. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get + * the default [class@Service] proxy. * * This method will return immediately and complete asynchronously. */ @@ -1485,8 +1485,8 @@ secret_service_lookup (SecretService *service, * * If no secret is found then %NULL is returned. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found */ SecretValue * secret_service_lookup_finish (SecretService *service, @@ -1520,14 +1520,14 @@ secret_service_lookup_finish (SecretService *service, * * The @attributes should be a set of key and value string pairs. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user interface * threads. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found */ SecretValue * secret_service_lookup_sync (SecretService *service, @@ -1674,8 +1674,8 @@ on_delete_service (GObject *source, * * The @attributes should be a set of key and value string pairs. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get + * the default [class@Service] proxy. * * This method will return immediately and complete asynchronously. */ @@ -1765,8 +1765,8 @@ secret_service_clear_finish (SecretService *service, * * The @attributes should be a set of key and value string pairs. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user interface * threads. @@ -1878,8 +1878,8 @@ on_set_alias_service (GObject *source, * Assign a collection to this alias. Aliases help determine * well known collections, such as 'default'. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get + * the default [class@Service] proxy. * * This method will return immediately and complete asynchronously. */ @@ -1967,8 +1967,8 @@ secret_service_set_alias_finish (SecretService *service, * Assign a collection to this alias. Aliases help determine * well known collections, such as 'default'. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block and should not be used in user interface threads. * diff --git a/libsecret/secret-password.c b/libsecret/secret-password.c index 30c5352..deabdf3 100644 --- a/libsecret/secret-password.c +++ b/libsecret/secret-password.c @@ -23,27 +23,6 @@ #include -/** - * SECTION:secret-password - * @title: Password storage - * @short_description: Simple password storage and lookup - * - * This is a simple API for storing passwords and retrieving passwords in the - * Secret Service. - * - * Each password is associated with a set of attributes. Attribute values can - * be either strings, integers or booleans. - * - * The names and types of allowed attributes for a given password are defined - * with a schema. Certain schemas are predefined. Additional schemas can be - * defined via the %SecretSchema structure. - * - * Each of the functions accept a variable list of attributes names and their - * values. Include a %NULL to terminate the list of attributes. - * - * Stability: Stable - */ - /** * secret_password_store: (skip) * @schema: the schema for attributes @@ -67,7 +46,7 @@ * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method will return immediately and complete asynchronously. @@ -195,7 +174,7 @@ on_store_backend (GObject *source, * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method will return immediately and complete asynchronously. @@ -240,9 +219,9 @@ secret_password_storev (const SecretSchema *schema, * secret_password_store_binary: (skip) * @schema: the schema for attributes * @collection: (nullable): a collection alias, or D-Bus object path of the - * collection where to store the secret + * collection where to store the secret * @label: label for the secret - * @value: a #SecretValue + * @value: a [struct@Value] * @cancellable: (nullable): optional cancellation object * @callback: called when the operation completes * @user_data: data to be passed to the callback @@ -250,8 +229,8 @@ secret_password_storev (const SecretSchema *schema, * * Store a password in the secret service. * - * This is similar to secret_password_store(), but takes a - * #SecretValue as the argument instead of a null-terminated password. + * This is similar to [func@password_store], but takes a + * [struct@Value] as the argument instead of a null-terminated password. * * This method will return immediately and complete asynchronously. * @@ -296,15 +275,15 @@ secret_password_store_binary (const SecretSchema *schema, * @collection: (nullable): a collection alias, or D-Bus object path of the * collection where to store the secret * @label: label for the secret - * @value: a #SecretValue + * @value: a [struct@Value] * @cancellable: (nullable): optional cancellation object * @callback: (scope async): called when the operation completes * @user_data: data to be passed to the callback * * Store a password in the secret service. * - * This is similar to secret_password_storev(), but takes a - * #SecretValue as the argument instead of a null-terminated password. + * This is similar to [func@password_storev], but takes a + * [struct@Value] as the argument instead of a null-terminated password. * * This method will return immediately and complete asynchronously. * @@ -387,7 +366,7 @@ secret_password_store_finish (GAsyncResult *result, * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method may block indefinitely and should not be used in user interface @@ -448,7 +427,7 @@ secret_password_store_sync (const SecretSchema *schema, * the item will be updated with these new values. * * If @collection is %NULL, then the default collection will be - * used. Use #SECRET_COLLECTION_SESSION to store the password in the session + * used. Use [const@COLLECTION_SESSION] to store the password in the session * collection, which doesn't get stored across login sessions. * * This method may block indefinitely and should not be used in user interface @@ -500,15 +479,15 @@ secret_password_storev_sync (const SecretSchema *schema, * @collection: (nullable): a collection alias, or D-Bus object path of the * collection where to store the secret * @label: label for the secret - * @value: a #SecretValue + * @value: a [struct@Value] * @cancellable: (nullable): optional cancellation object * @error: location to place an error on failure * @...: the attribute keys and values, terminated with %NULL * * Store a password in the secret service. * - * This is similar to secret_password_store_sync(), but takes a - * #SecretValue as the argument instead of a null terminated password. + * This is similar to [func@password_store_sync], but takes a + * [struct@Value] as the argument instead of a null terminated password. * * This method may block indefinitely and should not be used in user interface * threads. @@ -558,14 +537,14 @@ secret_password_store_binary_sync (const SecretSchema *schema, * @collection: (nullable): a collection alias, or D-Bus object path of the * collection where to store the secret * @label: label for the secret - * @value: a #SecretValue + * @value: a [struct@Value] * @cancellable: (nullable): optional cancellation object * @error: location to place an error on failure * * Store a password in the secret service. * - * This is similar to secret_password_storev_sync(), but takes a - * #SecretValue as the argument instead of a null-terminated passwords. + * This is similar to [func@password_storev_sync], but takes a [struct@Value] as + * the argument instead of a null-terminated passwords. * * This method may block indefinitely and should not be used in user interface * threads. @@ -779,7 +758,7 @@ secret_password_lookupv (const SecretSchema *schema, * Finish an asynchronous operation to lookup a password in the secret service. * * Returns: (transfer full): a new password string stored in nonpageable memory - * which must be freed with secret_password_free() when done + * which must be freed with [func@password_free] when done */ gchar * secret_password_lookup_nonpageable_finish (GAsyncResult *result, @@ -804,8 +783,8 @@ secret_password_lookup_nonpageable_finish (GAsyncResult *result, * * Finish an asynchronous operation to lookup a password in the secret service. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found * * Since: 0.19.0 */ @@ -827,7 +806,7 @@ secret_password_lookup_binary_finish (GAsyncResult *result, * Finish an asynchronous operation to lookup a password in the secret service. * * Returns: (transfer full): a new password string which should be freed with - * secret_password_free() or may be freed with g_free() when done + * [func@password_free] or may be freed with [func@GLib.free] when done */ gchar * secret_password_lookup_finish (GAsyncResult *result, @@ -865,7 +844,7 @@ secret_password_lookup_finish (GAsyncResult *result, * threads. * * Returns: (transfer full): a new password string which should be freed with - * secret_password_free() or may be freed with g_free() when done + * [func@password_free] or may be freed with [func@GLib.free] when done */ gchar * secret_password_lookup_sync (const SecretSchema *schema, @@ -917,7 +896,7 @@ secret_password_lookup_sync (const SecretSchema *schema, * threads. * * Returns: (transfer full): a new password string stored in nonpageable memory - * which must be freed with secret_password_free() when done + * which must be freed with [func@password_free] when done */ gchar * secret_password_lookup_nonpageable_sync (const SecretSchema *schema, @@ -966,7 +945,7 @@ secret_password_lookup_nonpageable_sync (const SecretSchema *schema, * threads. * * Returns: (transfer full): a new password string stored in non pageable memory - * which should be freed with secret_password_free() when done + * which should be freed with [func@password_free] when done */ gchar * secret_password_lookupv_nonpageable_sync (const SecretSchema *schema, @@ -1010,14 +989,14 @@ secret_password_lookupv_nonpageable_sync (const SecretSchema *schema, * * Lookup a password in the secret service. * - * This is similar to secret_password_lookup_sync(), but returns a - * #SecretValue instead of a null-terminated password. + * This is similar to [func@password_lookup_sync], but returns a + * [struct@Value] instead of a null-terminated password. * * This method may block indefinitely and should not be used in user interface * threads. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found * * Since: 0.19.0 */ @@ -1060,14 +1039,14 @@ secret_password_lookup_binary_sync (const SecretSchema *schema, * * Lookup a password in the secret service. * - * This is similar to secret_password_lookupv_sync(), but returns a - * #SecretValue instead of a null-terminated password. + * This is similar to [func@password_lookupv_sync], but returns a + * [struct@Value] instead of a null-terminated password. * * This method may block indefinitely and should not be used in user interface * threads. * - * Returns: (transfer full): a newly allocated #SecretValue, which should be - * released with secret_value_unref(), or %NULL if no secret found + * Returns: (transfer full): a newly allocated [struct@Value], which should be + * released with [method@Value.unref], or %NULL if no secret found * * Since: 0.19.0 */ @@ -1121,7 +1100,7 @@ secret_password_lookupv_binary_sync (const SecretSchema *schema, * threads. * * Returns: (transfer full): a new password string which should be freed with - * secret_password_free() or may be freed with g_free() when done + * [func@password_free] or may be freed with [func@GLib.free] when done */ gchar * secret_password_lookupv_sync (const SecretSchema *schema, @@ -1613,7 +1592,7 @@ secret_password_searchv (const SecretSchema *schema, * Finish an asynchronous operation to search for items in the secret service. * * Returns: (transfer full) (element-type Secret.Retrievable): a list of - * #SecretRetrievable containing attributes of the matched items + * [iface@Retrievable] containing attributes of the matched items * * Since: 0.19.0 */ @@ -1648,7 +1627,7 @@ secret_password_search_finish (GAsyncResult *result, * threads. * * Returns: (transfer full) (element-type Secret.Retrievable): a list of - * #SecretRetrievable containing attributes of the matched items + * [iface@Retrievable] containing attributes of the matched items * * Since: 0.19.0 */ @@ -1701,7 +1680,7 @@ secret_password_search_sync (const SecretSchema *schema, * threads. * * Returns: (transfer full) (element-type Secret.Retrievable): a list of - * #SecretRetrievable containing attributes of the matched items + * [iface@Retrievable] containing attributes of the matched items * * Since: 0.19.0 */ @@ -1746,9 +1725,9 @@ secret_password_searchv_sync (const SecretSchema *schema, * Clear the memory used by a password, and then free it. * * This function must be used to free nonpageable memory returned by - * secret_password_lookup_nonpageable_finish(), - * secret_password_lookup_nonpageable_sync() or - * secret_password_lookupv_nonpageable_sync(). + * [func@password_lookup_nonpageable_finish], + * [func@password_lookup_nonpageable_sync] or + * [func@password_lookupv_nonpageable_sync]. */ void secret_password_free (gchar *password) diff --git a/libsecret/secret-paths.c b/libsecret/secret-paths.c index 1fc3adc..f39f6c7 100644 --- a/libsecret/secret-paths.c +++ b/libsecret/secret-paths.c @@ -23,22 +23,6 @@ #include "secret-value.h" -/** - * SECTION:secret-paths - * @title: DBus Path Related Functions - * @short_description: Secret Service functions which operate on DBus object paths - * - * These are low level functions which operate on DBus object paths of - * collections or items, instead of the #SecretCollection or #SecretItem - * objects themselves. - * - * You can use these functions if you wish to manage access to the secret - * service using the DBus API directly, and only wish to use a few calls - * in libsecret. - * - * Stability: Unstable - */ - /** * secret_collection_new_for_dbus_path: (skip) * @service: (nullable): a secret service object @@ -50,8 +34,8 @@ * * Get a new collection proxy for a collection in the secret service. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [func@Service.get] will be called to get + * the default [class@Service] proxy. * * This method will return immediately and complete asynchronously. * @@ -95,7 +79,7 @@ secret_collection_new_for_dbus_path (SecretService *service, * collection in the secret service. * * Returns: (transfer full): the new collection, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretCollection * secret_collection_new_for_dbus_path_finish (GAsyncResult *result, @@ -128,8 +112,8 @@ secret_collection_new_for_dbus_path_finish (GAsyncResult *result, * * Get a new collection proxy for a collection in the secret service. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [funcService.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user interface * threads. @@ -137,7 +121,7 @@ secret_collection_new_for_dbus_path_finish (GAsyncResult *result, * Stability: Unstable * * Returns: (transfer full): the new collection, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretCollection * secret_collection_new_for_dbus_path_sync (SecretService *service, @@ -179,8 +163,8 @@ secret_collection_new_for_dbus_path_sync (SecretService *service, * * Get a new item proxy for a secret item in the secret service. * - * If @service is %NULL, then secret_service_get() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [funcService.get] will be called to get + * the default [class@Service] proxy. * * This method will return immediately and complete asynchronously. * @@ -226,7 +210,7 @@ secret_item_new_for_dbus_path (SecretService *service, * Stability: Unstable * * Returns: (transfer full): the new item, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretItem * secret_item_new_for_dbus_path_finish (GAsyncResult *result, @@ -256,8 +240,8 @@ secret_item_new_for_dbus_path_finish (GAsyncResult *result, * * Get a new item proxy for a secret item in the secret service. * - * If @service is %NULL, then secret_service_get_sync() will be called to get - * the default #SecretService proxy. + * If @service is %NULL, then [funcService.get_sync] will be called to get + * the default [class@Service] proxy. * * This method may block indefinitely and should not be used in user interface * threads. @@ -265,7 +249,7 @@ secret_item_new_for_dbus_path_finish (GAsyncResult *result, * Stability: Unstable * * Returns: (transfer full): the new item, which should be unreferenced - * with g_object_unref() + * with [method@GObject.Object.unref] */ SecretItem * secret_item_new_for_dbus_path_sync (SecretService *service, @@ -332,10 +316,10 @@ on_search_items_complete (GObject *source, * * This function returns immediately and completes asynchronously. * - * When your callback is called use secret_collection_search_for_dbus_paths_finish() + * When your callback is called use [method@Collection.search_for_dbus_paths_finish] * to get the results of this function. Only the DBus object paths of the - * items will be returned. If you would like #SecretItem objects to be returned - * instead, then use the secret_collection_search() function. + * items will be returned. If you would like [class@Item] objects to be returned + * instead, then use the [method@Collection.search] function. * * Stability: Unstable */ @@ -382,13 +366,13 @@ secret_collection_search_for_dbus_paths (SecretCollection *collection, * Complete asynchronous operation to search for items in a collection. * * DBus object paths of the items will be returned. If you would to have - * #SecretItem objects to be returned instead, then use the - * secret_collection_search() and secret_collection_search_finish() functions. + * [class@Item] objects to be returned instead, then use the + * [method@Collection.search] and [method@Collection.search_finish] functions. * * Stability: Unstable * * Returns: (transfer full) (array zero-terminated=1): an array of DBus object - * paths for matching items. + * paths for matching items. */ gchar ** secret_collection_search_for_dbus_paths_finish (SecretCollection *collection, @@ -429,13 +413,13 @@ secret_collection_search_for_dbus_paths_finish (SecretCollection *collection, * in user interface threads. * * DBus object paths of the items will be returned. If you would to have - * #SecretItem objects to be returned instead, then use the - * secret_collection_search_sync() function. + * [class@Item] objects to be returned instead, then use the + * [method@Collection.search_sync] function. * * Stability: Unstable * * Returns: (transfer full) (array zero-terminated=1): an array of DBus object - * paths for matching items. + * paths for matching items. */ gchar ** secret_collection_search_for_dbus_paths_sync (SecretCollection *collection, @@ -483,10 +467,10 @@ secret_collection_search_for_dbus_paths_sync (SecretCollection *collection, * * This function returns immediately and completes asynchronously. * - * When your callback is called use secret_service_search_for_dbus_paths_finish() + * When your callback is called use [method@Service.search_for_dbus_paths_finish] * to get the results of this function. Only the D-Bus object paths of the - * items will be returned. If you would like #SecretItem objects to be returned - * instead, then use the secret_service_search() function. + * items will be returned. If you would like [class@Item] objects to be returned + * instead, then use the [method@Service.search] function. * * Stability: Unstable */ @@ -558,9 +542,9 @@ _secret_service_search_for_paths_variant (SecretService *self, * in the @locked or @unlocked arrays respectively. * * D-Bus object paths of the items will be returned in the @unlocked or - * @locked arrays. If you would to have #SecretItem objects to be returned - * instead, then us the secret_service_search() and - * secret_service_search_finish() functions. + * @locked arrays. If you would to have [class@Item] objects to be returned + * instead, then us the [method@Service.search] and + * [method@Service.search_finish] functions. * * Stability: Unstable * @@ -626,8 +610,8 @@ secret_service_search_for_dbus_paths_finish (SecretService *self, * in the @locked or @unlocked arrays respectively. * * D-Bus object paths of the items will be returned in the @unlocked or - * @locked arrays. If you would to have #SecretItem objects to be returned - * instead, then use the secret_service_search_sync() function. + * @locked arrays. If you would to have [class@Item] objects to be returned + * instead, then use the [method@Service.search_sync] function. * * Stability: Unstable * @@ -736,7 +720,7 @@ on_get_secrets_session (GObject *source, * Get the secret value for a secret item stored in the service. * * The item is represented by its D-Bus object path. If you already have a - * #SecretItem proxy object, use use secret_item_get_secret() to more simply + * [class@Item] proxy object, use use [method@Item.get_secret] to more simply * get its secret value. * * This function returns immediately and completes asynchronously. @@ -784,7 +768,7 @@ secret_service_get_secret_for_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): the newly allocated secret value - * for the item, which should be released with secret_value_unref() + * for the item, which should be released with [method@Value.unref] */ SecretValue * secret_service_get_secret_for_dbus_path_finish (SecretService *self, @@ -818,7 +802,7 @@ secret_service_get_secret_for_dbus_path_finish (SecretService *self, * Get the secret value for a secret item stored in the service. * * The item is represented by its D-Bus object path. If you already have a - * #SecretItem proxy object, use use secret_item_load_secret_sync() to more simply + * [class@Item] proxy object, use use [method@Item.load_secret_sync] to more simply * get its secret value. * * This method may block indefinitely and should not be used in user interface @@ -829,7 +813,7 @@ secret_service_get_secret_for_dbus_path_finish (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): the newly allocated secret value - * for the item, which should be released with secret_value_unref() + * the item, which should be released with [method@Value.unref] */ SecretValue * secret_service_get_secret_for_dbus_path_sync (SecretService *self, @@ -872,7 +856,7 @@ secret_service_get_secret_for_dbus_path_sync (SecretService *self, * Get the secret values for a secret item stored in the service. * * The items are represented by their D-Bus object paths. If you already have - * #SecretItem proxy objects, use use secret_item_load_secrets() to more simply + * [class@Item] proxy objects, use use [func@Item.load_secrets] to more simply * get their secret values. * * This function returns immediately and completes asynchronously. @@ -920,8 +904,8 @@ secret_service_get_secrets_for_dbus_paths (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (element-type utf8 Secret.Value): a newly - * allocated hash table of item_path keys to #SecretValue - * values. + * allocated hash table of item_path keys to [struct@Value] + * values. */ GHashTable * secret_service_get_secrets_for_dbus_paths_finish (SecretService *self, @@ -955,7 +939,7 @@ secret_service_get_secrets_for_dbus_paths_finish (SecretService *self, * Get the secret values for a secret item stored in the service. * * The items are represented by their D-Bus object paths. If you already have - * #SecretItem proxy objects, use use secret_item_load_secrets_sync() to more + * [class@Item] proxy objects, use use [func@Item.load_secrets_sync] to more * simply get their secret values. * * This method may block indefinitely and should not be used in user interface @@ -966,8 +950,8 @@ secret_service_get_secrets_for_dbus_paths_finish (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (element-type utf8 Secret.Value): a newly - * allocated hash table of item_path keys to #SecretValue - * values. + * allocated hash table of item_path keys to [struct@Value] + * values. */ GHashTable * secret_service_get_secrets_for_dbus_paths_sync (SecretService *self, @@ -1158,15 +1142,15 @@ _secret_service_xlock_paths_finish (SecretService *self, * Lock items or collections in the secret service. * * The items or collections are represented by their D-Bus object paths. If you - * already have #SecretItem and #SecretCollection proxy objects, use use - * secret_service_lock_sync() instead. + * already have [class@Item] and [class@Collection] proxy objects, use use + * [method@Service.lock_sync] instead. * * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * * This method may block indefinitely and should not be used in user * interface threads. The secret service may prompt the user. - * secret_service_prompt() will be used to handle any prompts that show up. + * [method@Service.prompt] will be used to handle any prompts that show up. * * Stability: Unstable * @@ -1215,14 +1199,14 @@ secret_service_lock_dbus_paths_sync (SecretService *self, * Lock items or collections in the secret service. * * The items or collections are represented by their D-Bus object paths. If you - * already have #SecretItem and #SecretCollection proxy objects, use use - * secret_service_lock() instead. + * already have [class@Item] and [class@Collection] proxy objects, use use + * [method@Service.lock] instead. * * The secret service may not be able to lock items individually, and may * lock an entire collection instead. * * This method returns immediately and completes asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that show up. * * Stability: Unstable @@ -1288,15 +1272,15 @@ secret_service_lock_dbus_paths_finish (SecretService *self, * Unlock items or collections in the secret service. * * The items or collections are represented by their D-Bus object paths. If you - * already have #SecretItem and #SecretCollection proxy objects, use use - * secret_service_unlock_sync() instead. + * already have [class@Item] and [class@Collection] proxy objects, use use + * [method@Service.unlock_sync] instead. * * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * * This method may block indefinitely and should not be used in user * interface threads. The secret service may prompt the user. - * secret_service_prompt() will be used to handle any prompts that show up. + * [method@Service.prompt] will be used to handle any prompts that show up. * * Stability: Unstable * @@ -1346,14 +1330,14 @@ secret_service_unlock_dbus_paths_sync (SecretService *self, * Unlock items or collections in the secret service. * * The items or collections are represented by their D-Bus object paths. If you - * already have #SecretItem and #SecretCollection proxy objects, use use - * secret_service_unlock() instead. + * already have [class@Item] and [class@Collection] proxy objects, use use + * [method@Service.unlock] instead. * * The secret service may not be able to unlock items individually, and may * unlock an entire collection instead. * * This method returns immediately and completes asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that show up. * * Stability: Unstable @@ -1540,7 +1524,7 @@ _secret_service_delete_path_finish (SecretService *self, * Delete a secret item from the secret service. * * The item is represented by its D-Bus object path. If you already have a - * #SecretItem proxy objects, use use secret_item_delete() instead. + * [class@Item] proxy objects, use use [method@Item.delete] instead. * * This method will return immediately and complete asynchronously. * @@ -1591,7 +1575,7 @@ secret_service_delete_item_dbus_path_finish (SecretService *self, * Delete a secret item from the secret service. * * The item is represented by its D-Bus object path. If you already have a - * #SecretItem proxy objects, use use secret_item_delete_sync() instead. + * [class@Item] proxy objects, use use [method@Item.delete_sync] instead. * * This method may block indefinitely and should not be used in user interface * threads. @@ -1716,7 +1700,7 @@ on_create_collection_called (GObject *source, * * Using this method requires that you setup a correct hash table of D-Bus * properties for the new collection. You may prefer to use - * secret_collection_create() which does handles this for you. + * [func@Collection.create] which does handles this for you. * * An @alias is a well-known tag for a collection, such as 'default' (ie: the * default collection to store items in). This allows other applications to @@ -1727,13 +1711,13 @@ on_create_collection_called (GObject *source, * * @properties is a set of properties for the new collection. The keys in the * hash table should be interface.property strings like - * org.freedesktop.Secret.Collection.Label. The values - * in the hash table should be #GVariant values of the properties. + * `org.freedesktop.Secret.Collection.Label`. The values + * in the hash table should be [struct@GLib.Variant] values of the properties. * * If you wish to have a * * This method will return immediately and complete asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that are required. * * Stability: Unstable @@ -1794,7 +1778,7 @@ secret_service_create_collection_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full): a new string containing the D-Bus object path - * of the collection + * of the collection */ gchar * secret_service_create_collection_dbus_path_finish (SecretService *self, @@ -1832,7 +1816,7 @@ secret_service_create_collection_dbus_path_finish (SecretService *self, * * Using this method requires that you setup a correct hash table of D-Bus * properties for the new collection. You may prefer to use - * secret_collection_create() which does handles this for you. + * [func@Collection.create] which does handles this for you. * * An @alias is a well-known tag for a collection, such as 'default' (ie: the * default collection to store items in). This allows other applications to @@ -1843,11 +1827,11 @@ secret_service_create_collection_dbus_path_finish (SecretService *self, * * @properties is a set of properties for the new collection. The keys in the * hash table should be interface.property strings like - * org.freedesktop.Secret.Collection.Label. The values - * in the hash table should be #GVariant values of the properties. + * `org.freedesktop.Secret.Collection.Label`. The values + * in the hash table should be [struct@GLib.Variant] values of the properties. * * This method may block indefinitely and should not be used in user interface - * threads. The secret service may prompt the user. secret_service_prompt() + * threads. The secret service may prompt the user. [method@Service.prompt] * will be used to handle any prompts that are required. * * Stability: Unstable @@ -2018,7 +2002,7 @@ on_create_item_session (GObject *source, * Create a new item in a secret service collection and return its D-Bus * object path. * - * It is often easier to use secret_password_store() or secret_item_create() + * It is often easier to use [func@password_store] or [func@Item.create] * rather than using this function. Using this method requires that you setup * a correct hash table of D-Bus @properties for the new collection. * @@ -2028,11 +2012,11 @@ on_create_item_session (GObject *source, * * @properties is a set of properties for the new collection. The keys in the * hash table should be interface.property strings like - * org.freedesktop.Secret.Item.Label. The values - * in the hash table should be #GVariant values of the properties. + * `org.freedesktop.Secret.Item.Label`. The values + * in the hash table should be [struct@GLib.Variant] values of the properties. * * This method will return immediately and complete asynchronously. The secret - * service may prompt the user. secret_service_prompt() will be used to handle + * service may prompt the user. [method@Service.prompt] will be used to handle * any prompts that are required. * * Stability: Unstable @@ -2085,7 +2069,7 @@ secret_service_create_item_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full): a new string containing the D-Bus object path - * of the item + * of the item */ gchar * secret_service_create_item_dbus_path_finish (SecretService *self, @@ -2139,7 +2123,7 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result, * Create a new item in a secret service collection and return its D-Bus * object path. * - * It is often easier to use secret_password_store_sync() or secret_item_create_sync() + * It is often easier to use [func@password_store_sync] or [func@Item.create_sync] * rather than using this function. Using this method requires that you setup * a correct hash table of D-Bus @properties for the new collection. * @@ -2149,11 +2133,11 @@ _secret_service_create_item_dbus_path_finish_raw (GAsyncResult *result, * * @properties is a set of properties for the new collection. The keys in the * hash table should be interface.property strings like - * org.freedesktop.Secret.Item.Label. The values - * in the hash table should be #GVariant values of the properties. + * `org.freedesktop.Secret.Item.Label`. The values + * in the hash table should be [struct@GLib.Variant] values of the properties. * * This method may block indefinitely and should not be used in user interface - * threads. The secret service may prompt the user. secret_service_prompt() + * threads. The secret service may prompt the user. [method@Service.prompt] * will be used to handle any prompts that are required. * * Stability: Unstable @@ -2240,7 +2224,7 @@ secret_service_read_alias_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): the collection dbus object path, - * or %NULL if none assigned to the alias + * or %NULL if none assigned to the alias */ gchar * secret_service_read_alias_dbus_path_finish (SecretService *self, @@ -2449,11 +2433,11 @@ secret_service_set_alias_to_dbus_path_sync (SecretService *self, * @return_type: (nullable): the variant type of the prompt result * @error: location to place error on failure * - * Perform prompting for a #SecretPrompt. + * Perform prompting for a [class@Prompt]. * - * Override the #SecretServiceClass prompt_async virtual method + * Override the #SecretServiceClass [vfunc@Service.prompt_async] virtual method * to change the behavior of the propmting. The default behavior is to simply - * run secret_prompt_perform() on the prompt. + * run [method@Prompt.perform] on the prompt. * * Returns a variant result if the prompt was completed and not dismissed. The * type of result depends on the action the prompt is completing, and is defined @@ -2464,7 +2448,7 @@ secret_service_set_alias_to_dbus_path_sync (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): %NULL if the prompt was dismissed or an - * error occurred, a variant result if the prompt was successful + * error occurred, a variant result if the prompt was successful */ GVariant * secret_service_prompt_at_dbus_path_sync (SecretService *self, @@ -2497,14 +2481,14 @@ secret_service_prompt_at_dbus_path_sync (SecretService *self, * @callback: called when the operation completes * @user_data: data to be passed to the callback * - * Perform prompting for a #SecretPrompt. + * Perform prompting for a [class@Prompt]. * * This function is called by other parts of this library to handle prompts * for the various actions that can require prompting. * - * Override the #SecretServiceClass prompt_async virtual method + * Override the #SecretServiceClass [vfunc@Service.prompt_async] virtual method * to change the behavior of the propmting. The default behavior is to simply - * run secret_prompt_perform() on the prompt. + * run [method@Prompt.perform] on the prompt. * * Stability: Unstable */ @@ -2533,7 +2517,7 @@ secret_service_prompt_at_dbus_path (SecretService *self, * @result: the asynchronous result passed to the callback * @error: location to place an error on failure * - * Complete asynchronous operation to perform prompting for a #SecretPrompt. + * Complete asynchronous operation to perform prompting for a [class@Prompt]. * * Returns a variant result if the prompt was completed and not dismissed. The * type of result depends on the action the prompt is completing, and is defined @@ -2542,7 +2526,7 @@ secret_service_prompt_at_dbus_path (SecretService *self, * Stability: Unstable * * Returns: (transfer full) (nullable): %NULL if the prompt was dismissed or an - * error occurred, a variant result if the prompt was successful + * error occurred, a variant result if the prompt was successful */ GVariant * secret_service_prompt_at_dbus_path_finish (SecretService *self, @@ -2561,12 +2545,12 @@ secret_service_prompt_at_dbus_path_finish (SecretService *self, * @service: the service * @value: the secret value * - * Encodes a #SecretValue into GVariant for use with the Secret Service - * DBus API. + * Encodes a [struct@Value] into [struct@GLib.Variant] for use with the Secret + * Service DBus API. * - * The resulting GVariant will have a (oayays) signature. + * The resulting [struct@GLib.Variant] will have a `(oayays)` signature. * - * A session must have already been established by the #SecretService. + * A session must have already been established by the [class@Service]. * * Returns: (transfer floating): the encoded secret */ @@ -2590,12 +2574,12 @@ secret_service_encode_dbus_secret (SecretService *service, * @service: the service * @value: the encoded secret * - * Decode a #SecretValue into GVariant received with the Secret Service + * Decode a [struct@Value] into [struct@GLib.Variant] received with the Secret Service * DBus API. * - * The GVariant should have a (oayays) signature. + * The [struct@GLib.Variant] should have a `(oayays)` signature. * - * A session must have already been established by the #SecretService, and + * A session must have already been established by the [class@Service], and * the encoded secret must be valid for that session. * * Returns: (transfer full): the decoded secret value diff --git a/libsecret/secret-prompt.c b/libsecret/secret-prompt.c index 24229da..c40ce5d 100644 --- a/libsecret/secret-prompt.c +++ b/libsecret/secret-prompt.c @@ -22,32 +22,26 @@ #include /** - * SECTION:secret-prompt - * @title: SecretPrompt - * @short_description: a prompt in the Service + * SecretPrompt: * - * A #SecretPrompt represents a prompt in the Secret Service. + * A prompt in the Service + * + * A proxy object representing a prompt that the Secret Service will display + * to the user. * * Certain actions on the Secret Service require user prompting to complete, * such as creating a collection, or unlocking a collection. When such a prompt * is necessary, then a #SecretPrompt object is created by this library, and - * passed to the secret_service_prompt() method. In this way it is handled + * passed to the [method@Service.prompt] method. In this way it is handled * automatically. * * In order to customize prompt handling, override the - * SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish - * virtual methods of the #SecretService class. + * [vfunc@Service.prompt_async] and [vfunc@Service.prompt_finish] virtual + * methods of the [class@Service] class. * * Stability: Stable */ -/** - * SecretPrompt: - * - * A proxy object representing a prompt that the Secret Service will display - * to the user. - */ - /** * SecretPromptClass: * @parent_class: the parent class @@ -131,10 +125,10 @@ _secret_prompt_instance (SecretService *service, * API specification. * * If @window_id is non-null then it is used as an XWindow id on Linux. The API - * expects this id to be converted to a string using the %d - * printf format. The Secret Service can make its prompt transient for the window - * with this id. In some Secret Service implementations this is not possible, so - * the behavior depending on this should degrade gracefully. + * expects this id to be converted to a string using the `%d` printf format. The + * Secret Service can make its prompt transient for the window with this id. In + * some Secret Service implementations this is not possible, so the behavior + * depending on this should degrade gracefully. * * This runs the dialog in a recursive mainloop. When run from a user interface * thread, this means the user interface will remain responsive. Care should be @@ -191,10 +185,10 @@ secret_prompt_run (SecretPrompt *self, * API specification. * * If @window_id is non-null then it is used as an XWindow id on Linux. The API - * expects this id to be converted to a string using the %d - * printf format. The Secret Service can make its prompt transient for the window - * with this id. In some Secret Service implementations this is not possible, - * so the behavior depending on this should degrade gracefully. + * expects this id to be converted to a string using the `%d` printf format. The + * Secret Service can make its prompt transient for the window with this id. In + * some Secret Service implementations this is not possible, so the behavior + * depending on this should degrade gracefully. * * This method may block indefinitely and should not be used in user interface * threads. @@ -412,10 +406,10 @@ on_prompt_cancelled (GCancellable *cancellable, * was completed and not dismissed. * * If @window_id is non-null then it is used as an XWindow id on Linux. The API - * expects this id to be converted to a string using the %d - * printf format. The Secret Service can make its prompt transient for the window - * with this id. In some Secret Service implementations this is not possible, so - * the behavior depending on this should degrade gracefully. + * expects this id to be converted to a string using the `%d` printf format. The + * Secret Service can make its prompt transient for the window with this id. In + * some Secret Service implementations this is not possible, so the behavior + * depending on this should degrade gracefully. * * This method will return immediately and complete asynchronously. */ @@ -505,7 +499,7 @@ secret_prompt_perform (SecretPrompt *self, * defined in the Secret Service DBus API specification. * * Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred, - * a variant result if the prompt was successful + * a variant result if the prompt was successful */ GVariant * secret_prompt_perform_finish (SecretPrompt *self, diff --git a/libsecret/secret-retrievable.c b/libsecret/secret-retrievable.c index caa063b..d64285b 100644 --- a/libsecret/secret-retrievable.c +++ b/libsecret/secret-retrievable.c @@ -18,16 +18,16 @@ #include "secret-private.h" /** - * SECTION:secret-retrievable - * @title: SecretRetrievable - * @short_description: A read-only secret item + * SecretRetrievable + * + * A read-only secret item * * #SecretRetrievable provides a read-only view of a secret item * stored in the Secret Service. * - * Each item has a value, represented by a #SecretValue, which can be - * retrieved by secret_retrievable_retrieve_secret() and - * secret_retrievable_retrieve_secret_finish(). + * Each item has a value, represented by a [struct@Value], which can be + * retrieved by [method@Retrievable.retrieve_secret] and + * [method@Retrievable.retrieve_secret_finish]. * * Stability: Stable */ @@ -44,10 +44,10 @@ /** * SecretRetrievableInterface: * @parent_iface: the parent interface - * @retrieve_secret: implementation of secret_retrievable_retrieve_secret(), + * @retrieve_secret: implementation of [method@Retrievable.retrieve_secret], * required * @retrieve_secret_finish: implementation of - * secret_retrievable_retrieve_secret_finish(), required + * [method@Retrievable.retrieve_secret_finish], required * * The interface for #SecretRetrievable. * @@ -60,7 +60,7 @@ static void secret_retrievable_default_init (SecretRetrievableInterface *iface) { /** - * SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full) + * SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full) (attributes org.gtk.Property.get=secret_retrievable_get_attributes) * * The attributes set on this item. Attributes are used to locate an * item. They are not guaranteed to be stored or transferred securely. @@ -72,7 +72,7 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface) G_TYPE_HASH_TABLE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretRetrievable:label: + * SecretRetrievable:label: (attributes org.gtk.Property.get=secret_retrievable_get_label) * * The human readable label for the item. * @@ -83,7 +83,7 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface) NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretRetrievable:created: + * SecretRetrievable:created: (attributes org.gtk.Property.get=secret_retrievable_get_created) * * The date and time (in seconds since the UNIX epoch) that this * item was created. @@ -95,7 +95,7 @@ secret_retrievable_default_init (SecretRetrievableInterface *iface) 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * SecretRetrievable:modified: + * SecretRetrievable:modified: (attributes org.gtk.Property.get=secret_retrievable_get_modified) * * The date and time (in seconds since the UNIX epoch) that this * item was last modified. @@ -146,7 +146,7 @@ secret_retrievable_retrieve_secret (SecretRetrievable *self, * Complete asynchronous operation to retrieve the secret value of this object. * * Returns: (transfer full) (nullable): the secret value which should be - * released with secret_value_unref(), or %NULL + * released with [method@Value.unref], or %NULL * * Since: 0.19.0 */ @@ -178,7 +178,7 @@ secret_retrievable_retrieve_secret_finish (SecretRetrievable *self, * threads. * * Returns: (transfer full) (nullable): the secret value which should be - * released with secret_value_unref(), or %NULL + * released with [method@Value.unref], or %NULL * * Since: 0.19.0 */ @@ -213,7 +213,7 @@ secret_retrievable_retrieve_secret_sync (SecretRetrievable *self, } /** - * secret_retrievable_get_attributes: + * secret_retrievable_get_attributes: (attributes org.gtk.Method.get_property=attributes) * @self: a retrievable object * * Get the attributes of this object. @@ -225,8 +225,8 @@ secret_retrievable_retrieve_secret_sync (SecretRetrievable *self, * Do not modify the attribute returned by this method. * * Returns: (transfer full) (element-type utf8 utf8): a new reference - * to the attributes, which should not be modified, and - * released with g_hash_table_unref() + * to the attributes, which should not be modified, and + * released with [func@GLib.HashTable.unref] * * Since: 0.19.0 */ @@ -247,7 +247,7 @@ secret_retrievable_get_attributes (SecretRetrievable *self) * * Get the label of this item. * - * Returns: (transfer full): the label, which should be freed with g_free() + * Returns: (transfer full): the label, which should be freed with [func@GLib.free] * * Since: 0.19.0 */ @@ -263,7 +263,7 @@ secret_retrievable_get_label (SecretRetrievable *self) } /** - * secret_retrievable_get_created: + * secret_retrievable_get_created: (attributes org.gtk.Method.get_property=created) * @self: a retrievable object * * Get the created date and time of the object. The return value is @@ -285,7 +285,7 @@ secret_retrievable_get_created (SecretRetrievable *self) } /** - * secret_retrievable_get_modified: + * secret_retrievable_get_modified: (attributes org.gtk.Method.get_property=modified) * @self: a retrievable object * * Get the modified date and time of the object. The return value is diff --git a/libsecret/secret-schema.c b/libsecret/secret-schema.c index b04d922..32967bf 100644 --- a/libsecret/secret-schema.c +++ b/libsecret/secret-schema.c @@ -22,82 +22,6 @@ #include "egg/egg-secure-memory.h" -/** - * SECTION:secret-schema - * @title: SecretSchema - * @short_description: Schema for defining which attributes are on items - * - * Each password is associated with a set of attributes. Attribute values can - * be either strings, integers or booleans. - * - * The names and types of allowed attributes for a given password are defined - * with a schema. - * - * Additional schemas can be defined via the %SecretSchema structure like this: - * - * - * /* 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; - * } - * - * - * Stability: Stable - */ - -/** - * SecretSchema: - * @name: the dotted name of the schema - * @flags: flags for the schema - * @attributes: the attribute names and types of those attributes - * - * Represents a set of attributes that are stored with an item. These schemas - * are used for interoperability between various services storing the same types - * of items. - * - * Each schema has a name like "org.gnome.keyring.NetworkPassword", and defines - * a set of attributes, and types (string, integer, boolean) for those attributes. - * - * Attributes are stored as strings in the Secret Service, and the attribute - * types simply define standard ways to store integer and boolean values as strings. - * Attributes are represented in libsecret via a #GHashTable with string keys and - * values. Even for values that defined as an integer or boolean in the schema, - * the attribute values in the #GHashTable are strings. Boolean values are stored - * as the strings 'true' and 'false'. Integer values are stored in decimal, with - * a preceding negative sign for negative integers. - * - * Schemas are handled entirely on the client side by this library. The name of the - * schema is automatically stored as an attribute on the item. - * - * Normally when looking up passwords only those with matching schema names are - * returned. If the schema @flags contain the %SECRET_SCHEMA_DONT_MATCH_NAME flag, - * then lookups will not check that the schema name matches that on the item, only - * the schema's attributes are matched. This is useful when you are looking up items - * that are not stored by the libsecret library. Other libraries such as libgnome-keyring - * don't store the schema name. - * - * Stability: Stable - */ - /** * SecretSchemaFlags: * @SECRET_SCHEMA_NONE: no flags for the schema @@ -161,12 +85,12 @@ G_DEFINE_BOXED_TYPE (SecretSchemaAttribute, secret_schema_attribute, * schemas are used for interoperability between various services storing the * same types of items. * - * Each schema has an @name like "org.gnome.keyring.NetworkPassword", and + * Each schema has an @name like `org.gnome.keyring.NetworkPassword`, and * defines a set of attributes names, and types (string, integer, boolean) for * those attributes. * * Each key in the @attributes table should be a attribute name strings, and - * the values in the table should be integers from the #SecretSchemaAttributeType + * the values in the table should be integers from the [enum@SchemaAttributeType] * enumeration, representing the attribute type for each attribute name. * * Normally when looking up passwords only those with matching schema names are @@ -177,7 +101,7 @@ G_DEFINE_BOXED_TYPE (SecretSchemaAttribute, secret_schema_attribute, * don't store the schema name. * * Returns: (transfer full): the new schema, which should be unreferenced with - * secret_schema_unref() when done + * [method@Schema.unref] when done */ SecretSchema * secret_schema_newv (const gchar *name, @@ -244,13 +168,13 @@ secret_schema_newv (const gchar *name, * schemas are used for interoperability between various services storing the * same types of items. * - * Each schema has an @name like "org.gnome.keyring.NetworkPassword", and + * Each schema has an @name like `org.gnome.keyring.NetworkPassword`, and * defines a set of attributes names, and types (string, integer, boolean) for * those attributes. * * The variable argument list should contain pairs of a) The attribute name as * a null-terminated string, followed by b) integers from the - * #SecretSchemaAttributeType enumeration, representing the attribute type for + * [enum@SchemaAttributeType] enumeration, representing the attribute type for * each attribute name. The list of attributes should be terminated with a %NULL. * * Normally when looking up passwords only those with matching schema names are @@ -261,7 +185,7 @@ secret_schema_newv (const gchar *name, * don't store the schema name. * * Returns: (transfer full): the new schema, which should be unreferenced with - * secret_schema_unref() when done + * [method@Schema.unref] when done */ SecretSchema * secret_schema_new (const gchar *name, @@ -304,7 +228,7 @@ secret_schema_new (const gchar *name, * allocated, then this function will copy the schema. * * Returns: (transfer full): the referenced schema, which should be later - * unreferenced with secret_schema_unref() + * unreferenced with [method@Schema.unref] */ SecretSchema * secret_schema_ref (SecretSchema *schema) diff --git a/libsecret/secret-schemas.c b/libsecret/secret-schemas.c index f07a2ac..cc51a6d 100644 --- a/libsecret/secret-schemas.c +++ b/libsecret/secret-schemas.c @@ -17,18 +17,6 @@ #include "secret-schema.h" #include "secret-schemas.h" -/** - * SECRET_SCHEMA_NOTE: (skip) - * - * A predefined schema for personal passwords stored by the user in the - * password manager. This schema has no attributes, and the items are not - * meant to be used automatically by applications. - * - * When used to search for items using this schema, it will only match - * items that have the same schema. Items stored via libgnome-keyring with the - * GNOME_KEYRING_ITEM_NOTE item type will match. - */ - static const SecretSchema note_schema = { "org.gnome.keyring.Note", SECRET_SCHEMA_NONE, @@ -39,37 +27,6 @@ static const SecretSchema note_schema = { const SecretSchema * SECRET_SCHEMA_NOTE = ¬e_schema; -/** - * SECRET_SCHEMA_COMPAT_NETWORK: (skip) - * - * A predefined schema that is compatible with items stored via the - * libgnome-keyring 'network password' functions. This is meant to be used by - * applications migrating from libgnome-keyring which stored their secrets as - * 'network passwords'. It is not recommended that new code use this schema. - * - * When used to search for items using this schema, it will only match - * items that have the same schema. Items stored via libgnome-keyring with the - * GNOME_KEYRING_ITEM_NETWORK_PASSWORD item type will match. - * - * The following attributes exist in the schema: - * Attributes: - * user: - * The user name (string). - * domain: - * The login domain or realm (string). - * object: - * The object or path (string). - * protocol: - * The protocol (a string like 'http'). - * port: - * The network port (integer). - * server: - * The hostname or server (string). - * authtype: - * The authentication type (string). - * - */ - static const SecretSchema network_schema = { "org.gnome.keyring.NetworkPassword", SECRET_SCHEMA_NONE, @@ -97,6 +54,7 @@ const SecretSchema * SECRET_SCHEMA_COMPAT_NETWORK = &network_schema; * language bindings cannot, and must use this accessor. * * Returns: (transfer none): schema type + * * Since: 0.18.6 */ const SecretSchema * diff --git a/libsecret/secret-schemas.h b/libsecret/secret-schemas.h index c78a001..c61ee97 100644 --- a/libsecret/secret-schemas.h +++ b/libsecret/secret-schemas.h @@ -39,12 +39,67 @@ extern const SecretSchema * SECRET_SCHEMA_COMPAT_NETWORK; /** * SecretSchemaType: - * @SECRET_SCHEMA_TYPE_NOTE: Personal passwords; see %SECRET_SCHEMA_NOTE + * @SECRET_SCHEMA_TYPE_NOTE: Personal passwords * @SECRET_SCHEMA_TYPE_COMPAT_NETWORK: Network passwords from older - * libgnome-keyring storage; see %SECRET_SCHEMA_COMPAT_NETWORK + * libgnome-keyring storage * * Different types of schemas for storing secrets, intended for use with - * secret_get_schema(). + * [func@get_schema]. + * + * ## @SECRET_SCHEMA_NOTE + * + * A predefined schema for personal passwords stored by the user in the + * password manager. This schema has no attributes, and the items are not + * meant to be used automatically by applications. + * + * When used to search for items using this schema, it will only match + * items that have the same schema. Items stored via libgnome-keyring with the + * `GNOME_KEYRING_ITEM_NOTE` item type will match. + * + * ## @SECRET_SCHEMA_COMPAT_NETWORK + * + * A predefined schema that is compatible with items stored via the + * libgnome-keyring 'network password' functions. This is meant to be used by + * applications migrating from libgnome-keyring which stored their secrets as + * 'network passwords'. It is not recommended that new code use this schema. + * + * When used to search for items using this schema, it will only match + * items that have the same schema. Items stored via libgnome-keyring with the + * `GNOME_KEYRING_ITEM_NETWORK_PASSWORD` item type will match. + * + * The following attributes exist in the schema: + * + * ### Attributes: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
user:The user name (string).
domain:The login domain or realm (string).
object:The object or path (string).
protocol:The protocol (a string like 'http').
port:The network port (integer).
server:The hostname or server (string).
authtype:The authentication type (string).
* * Since: 0.18.6 */ diff --git a/libsecret/secret-service.c b/libsecret/secret-service.c index 455248c..bdb8bd7 100644 --- a/libsecret/secret-service.c +++ b/libsecret/secret-service.c @@ -30,59 +30,54 @@ #include "egg/egg-secure-memory.h" /** - * SECTION:secret-service - * @title: SecretService - * @short_description: the Secret Service + * SecretService: + * + * A proxy object representing the Secret Service. * * A #SecretService object represents the Secret Service implementation which * runs as a D-Bus service. * * Normally a single #SecretService object can be shared between multiple - * callers. The secret_service_get() method is used to access this #SecretService + * callers. The [func@Service.get] method is used to access this #SecretService * object. If a new independent #SecretService object is required, use - * secret_service_open(). + * [func@Service.open]. * * In order to securely transfer secrets to the Sercret Service, a session * is established. This session can be established while initializing a * #SecretService object by passing the %SECRET_SERVICE_OPEN_SESSION flag - * to the secret_service_get() or secret_service_open() functions. In order to + * to the [func@Service.get] or [func@Service.open] functions. In order to * establish a session on an already existing #SecretService, use the - * secret_service_ensure_session() function. + * [method@Service.ensure_session] function. * - * To search for items, use the secret_service_search() method. + * To search for items, use the [method@Service.search] method. * * Multiple collections can exist in the Secret Service, each of which contains - * secret items. In order to instantiate #SecretCollection objects which + * secret items. In order to instantiate [class@Collection] objects which * represent those collections while initializing a #SecretService then pass - * the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the secret_service_get() or - * secret_service_open() functions. In order to establish a session on an already - * existing #SecretService, use the secret_service_load_collections() function. - * To access the list of collections use secret_service_get_collections(). + * the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the [func@Service.get] or + * [func@Service.open] functions. In order to establish a session on an already + * existing #SecretService, use the [method@Service.load_collections] function. + * To access the list of collections use [method@Service.get_collections]. * * Certain actions on the Secret Service require user prompting to complete, * such as creating a collection, or unlocking a collection. When such a prompt - * is necessary, then a #SecretPrompt object is created by this library, and - * passed to the secret_service_prompt() method. In this way it is handled + * is necessary, then a [class@Prompt] object is created by this library, and + * passed to the [method@Service.prompt] method. In this way it is handled * automatically. * - * In order to customize prompt handling, override the prompt_async - * and prompt_finish virtual methods of the #SecretService class. + * In order to customize prompt handling, override the + * [vfunc@Service.prompt_async] and [vfunc@Service.prompt_finish] virtual + * methods of the #SecretService class. * * Stability: Stable */ -/** - * SecretService: - * - * A proxy object representing the Secret Service. - */ - /** * SecretServiceClass: * @parent_class: the parent class - * @collection_gtype: the #GType of the #SecretCollection objects instantiated + * @collection_gtype: the [alias@GLib.Type] of the [class@Collection] objects instantiated * by the #SecretService proxy - * @item_gtype: the #GType of the #SecretItem objects instantiated by the + * @item_gtype: the [alias@GLib.Type] of the [class@Item] objects instantiated by the * #SecretService proxy * @prompt_async: called to perform asynchronous prompting when necessary * @prompt_finish: called to complete an asynchronous prompt operation @@ -104,7 +99,7 @@ * #SecretService * * Flags which determine which parts of the #SecretService proxy are initialized - * during a secret_service_get() or secret_service_open() operation. + * during a [func@Service.get] or [func@Service.open] operation. */ EGG_SECURE_DEFINE_GLIB_GLOBALS (); @@ -587,15 +582,15 @@ secret_service_class_init (SecretServiceClass *klass) g_object_class_override_property (object_class, PROP_FLAGS, "flags"); /** - * SecretService:collections: + * SecretService:collections: (attributes org.gtk.Property.get=secret_service_get_collections) * - * A list of #SecretCollection objects representing the collections in + * A list of [class@Collection] objects representing the collections in * the Secret Service. This list may be %NULL if the collections have * not been loaded. * * To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS - * initialization flag when calling the secret_service_get() or - * secret_service_open() functions. Or call the secret_service_load_collections() + * initialization flag when calling the [func@Service.get] or + * [func@Service.open] functions. Or call the [method@Service.load_collections] * method. */ g_object_class_install_property (object_class, PROP_COLLECTIONS, @@ -1002,7 +997,7 @@ secret_service_get (SecretServiceFlags flags, * Secret Service. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_get_finish (GAsyncResult *result, @@ -1058,7 +1053,7 @@ secret_service_get_finish (GAsyncResult *result, * threads. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_get_sync (SecretServiceFlags flags, @@ -1090,8 +1085,8 @@ secret_service_get_sync (SecretServiceFlags flags, /** * secret_service_disconnect: * - * Disconnect the default #SecretService proxy returned by secret_service_get() - * and secret_service_get_sync(). + * Disconnect the default #SecretService proxy returned by [func@Service.get] + * and [func@Service.get_sync]. * * It is not necessary to call this function, but you may choose to do so at * program exit. It is useful for testing that memory is not leaked. @@ -1117,7 +1112,7 @@ secret_service_disconnect (void) * * Create a new #SecretService proxy for the Secret Service. * - * This function is rarely used, see secret_service_get() instead. + * This function is rarely used, see [func@Service.get] instead. * * The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the type * of a derived class. @@ -1155,7 +1150,7 @@ secret_service_open (GType service_gtype, * the Secret Service. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_open_finish (GAsyncResult *result, @@ -1188,7 +1183,7 @@ secret_service_open_finish (GAsyncResult *result, * * Create a new #SecretService proxy for the Secret Service. * - * This function is rarely used, see secret_service_get_sync() instead. + * This function is rarely used, see [func@Service.get_sync] instead. * * The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the * type of a derived class. @@ -1202,7 +1197,7 @@ secret_service_open_finish (GAsyncResult *result, * threads. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_open_sync (GType service_gtype, @@ -1226,7 +1221,7 @@ secret_service_open_sync (GType service_gtype, * Get the flags representing what features of the #SecretService proxy * have been initialized. * - * Use secret_service_ensure_session() or secret_service_load_collections() + * Use [method@Service.ensure_session] or [method@Service.load_collections] * to initialize further features and change the flags. * * Returns: the flags for features initialized @@ -1251,18 +1246,18 @@ secret_service_get_flags (SecretService *self) } /** - * secret_service_get_collections: + * secret_service_get_collections: (attributes org.gtk.Method.get_property=collections) * @self: the secret service proxy * - * Get a list of #SecretCollection objects representing all the collections + * Get a list of [class@Collection] objects representing all the collections * in the secret service. * * If the %SECRET_SERVICE_LOAD_COLLECTIONS flag was not specified when * initializing #SecretService proxy object, then this method will return - * %NULL. Use secret_service_load_collections() to load the collections. + * %NULL. Use [method@Service.load_collections] to load the collections. * * Returns: (transfer full) (element-type Secret.Collection) (nullable): a - * list of the collections in the secret service + * list of the collections in the secret service */ GList * secret_service_get_collections (SecretService *self) @@ -1364,7 +1359,7 @@ _secret_service_take_session (SecretService *self, * secret service proxy and the Secret Service itself. * * This will be %NULL if no session has been established. Use - * secret_service_ensure_session() to establish a session. + * [method@Service.ensure_session] to establish a session. * * Returns: (nullable): a string representing the algorithms for transferring * secrets @@ -1394,10 +1389,10 @@ secret_service_get_session_algorithms (SecretService *self) * secrets between this secret service proxy and the Secret Service itself. * * This will be %NULL if no session has been established. Use - * secret_service_ensure_session() to establish a session. + * [method@Service.ensure_session] to establish a session. * * Returns: (nullable): a string representing the D-Bus object path of the - * session + * session */ const gchar * secret_service_get_session_dbus_path (SecretService *self) @@ -1428,7 +1423,7 @@ secret_service_get_session_dbus_path (SecretService *self) * * It is not normally necessary to call this method, as the session is * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION - * to secret_service_get() in order to ensure that a session has been established + * to [func@Service.get] in order to ensure that a session has been established * by the time you get the #SecretService proxy. * * This method will return immediately and complete asynchronously. @@ -1500,7 +1495,7 @@ secret_service_ensure_session_finish (SecretService *self, * * It is not normally necessary to call this method, as the session is * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION - * to secret_service_get_sync() in order to ensure that a session has been + * to [func@Service.get_sync] in order to ensure that a session has been * established by the time you get the #SecretService proxy. * * This method may block indefinitely and should not be used in user interface @@ -1638,10 +1633,10 @@ on_ensure_collection (GObject *source, * * Ensure that the #SecretService proxy has loaded all the collections present * in the Secret Service. This affects the result of - * secret_service_get_collections(). + * [method@Service.get_collections]. * * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to - * secret_service_get_sync() in order to ensure that the collections have been + * [func@Service.get_sync] in order to ensure that the collections have been * loaded by the time you get the #SecretService proxy. * * This method will return immediately and complete asynchronously. @@ -1735,10 +1730,10 @@ secret_service_load_collections_finish (SecretService *self, * * Ensure that the #SecretService proxy has loaded all the collections present * in the Secret Service. This affects the result of - * secret_service_get_collections(). + * [method@Service.get_collections]. * * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to - * secret_service_get_sync() in order to ensure that the collections have been + * [func@Service.get_sync] in order to ensure that the collections have been * loaded by the time you get the #SecretService proxy. * * This method may block indefinitely and should not be used in user interface @@ -1801,7 +1796,7 @@ secret_service_load_collections_sync (SecretService *self, * @return_type: the variant type of the prompt result * @error: location to place an error on failure * - * Perform prompting for a #SecretPrompt. + * Perform prompting for a [class@Prompt]. * * Runs a prompt and performs the prompting. Returns a variant result if the * prompt was completed and not dismissed. The type of result depends on the @@ -1811,12 +1806,12 @@ secret_service_load_collections_sync (SecretService *self, * This function is called by other parts of this library to handle prompts * for the various actions that can require prompting. * - * Override the #SecretServiceClass prompt_sync virtual method + * Override the #SecretServiceClass [vfunc@Service.prompt_sync] virtual method * to change the behavior of the prompting. The default behavior is to simply - * run secret_prompt_perform_sync() on the prompt with a %NULL window_id. + * run [method@Prompt.perform_sync] on the prompt with a %NULL `window_id`. * * Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred, - * a variant result if the prompt was successful + * a variant result if the prompt was successful */ GVariant * secret_service_prompt_sync (SecretService *self, @@ -1847,14 +1842,14 @@ secret_service_prompt_sync (SecretService *self, * @callback: called when the operation completes * @user_data: data to be passed to the callback * - * Perform prompting for a #SecretPrompt. + * Perform prompting for a [class@Prompt]. * * This function is called by other parts of this library to handle prompts * for the various actions that can require prompting. * - * Override the #SecretServiceClass prompt_async virtual method + * Override the #SecretServiceClass [vfunc@Service.prompt_async] virtual method * to change the behavior of the prompting. The default behavior is to simply - * run secret_prompt_perform() on the prompt. + * run [method@Prompt.perform] on the prompt. */ void secret_service_prompt (SecretService *self, @@ -1882,14 +1877,14 @@ secret_service_prompt (SecretService *self, * @result: the asynchronous result passed to the callback * @error: location to place an error on failure * - * Complete asynchronous operation to perform prompting for a #SecretPrompt. + * Complete asynchronous operation to perform prompting for a [class@Prompt]. * * Returns a variant result if the prompt was completed and not dismissed. The * type of result depends on the action the prompt is completing, and is defined * in the Secret Service DBus API specification. * * Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred, - * a variant result if the prompt was successful + * a variant result if the prompt was successful */ GVariant * secret_service_prompt_finish (SecretService *self, @@ -1913,7 +1908,7 @@ secret_service_prompt_finish (SecretService *self, * @self: the secret service * * Get the GObject type for collections instantiated by this service. - * This will always be either #SecretCollection or derived from it. + * This will always be either [class@Collection] or derived from it. * * Returns: the gobject type for collections */ @@ -1941,7 +1936,7 @@ secret_service_get_collection_gtype (SecretService *self) * @self: the service * * Get the GObject type for items instantiated by this service. - * This will always be either #SecretItem or derived from it. + * This will always be either [class@Item] or derived from it. * * Returns: the gobject type for items */ diff --git a/libsecret/secret-util.c b/libsecret/secret-util.c index f011728..3b601bc 100644 --- a/libsecret/secret-util.c +++ b/libsecret/secret-util.c @@ -20,9 +20,9 @@ #include /** - * SECTION:secret-error - * @title: SecretError - * @short_description: libsecret errors + * SecretError + * + * libsecret errors * * Various errors reported by the libsecret library. No error returned from * the libsecret API is suitable for direct display to the user. It is up diff --git a/libsecret/secret-value.c b/libsecret/secret-value.c index d58feb3..19a2131 100644 --- a/libsecret/secret-value.c +++ b/libsecret/secret-value.c @@ -22,33 +22,27 @@ #include /** - * SECTION:secret-value - * @title: SecretValue - * @short_description: a value containing a secret + * SecretValue: + * + * A value containing a secret * * A #SecretValue contains a password or other secret value. * - * Use secret_value_get() to get the actual secret data, such as a password. + * Use [method@Value.get] to get the actual secret data, such as a password. * The secret data is not necessarily null-terminated, unless the content type * is "text/plain". * - * Each #SecretValue has a content type. For passwords, this is "text/plain". - * Use secret_value_get_content_type() to look at the content type. + * Each #SecretValue has a content type. For passwords, this is `text/plain`. + * Use [method@Value.get_content_type] to look at the content type. * * #SecretValue is reference counted and immutable. The secret data is only - * freed when all references have been released via secret_value_unref(). + * freed when all references have been released via [method@Value.unref]. * * Stability: Stable */ static gboolean is_password_value (SecretValue *value); -/** - * SecretValue: - * - * A secret value, like a password or other binary secret. - */ - EGG_SECURE_DECLARE (secret_value); struct _SecretValue { @@ -153,8 +147,8 @@ secret_value_new_full (gchar *secret, * @length: the length of the secret * * Get the secret data in the #SecretValue. The value is not necessarily - * null-terminated unless it was created with secret_value_new() or a - * null-terminated string was passed to secret_value_new_full(). + * null-terminated unless it was created with [ctor@Value.new] or a + * null-terminated string was passed to [ctor@Value.new_full]. * * Returns: (array length=length) (element-type guint8): the secret data */ @@ -173,7 +167,7 @@ secret_value_get (SecretValue *value, * @value: the value * * Get the secret data in the #SecretValue if it contains a textual - * value. The content type must be text/plain. + * value. The content type must be `text/plain`. * * Returns: (nullable): the content type */ @@ -193,7 +187,7 @@ secret_value_get_text (SecretValue *value) * @value: the value * * Get the content type of the secret value, such as - * text/plain. + * `text/plain`. * * Returns: the content type */ @@ -209,7 +203,7 @@ secret_value_get_content_type (SecretValue *value) * @value: value to reference * * Add another reference to the #SecretValue. For each reference - * secret_value_unref() should be called to unreference the value. + * [method@Value.unref] should be called to unreference the value. * * Returns: (transfer full): the value */ @@ -265,7 +259,7 @@ is_password_value (SecretValue *value) * #SecretValue as nonpageable memory. * * Returns: (transfer full): a new password string stored in nonpageable memory - * which must be freed with secret_password_free() when done + * which must be freed with [func@password_free] when done * * Since: 0.19.0 */ diff --git a/libsecret/secret-version.h.in b/libsecret/secret-version.h.in index 4c89d7f..8dae6a5 100644 --- a/libsecret/secret-version.h.in +++ b/libsecret/secret-version.h.in @@ -19,14 +19,6 @@ #ifndef __SECRET_VERSION_H__ #define __SECRET_VERSION_H__ -/** - * SECTION:secret-version - * @short_description: Variables and macros to check the libsecret version - * @title: Version Information - * - * Stability: Stable - */ - /** * SECRET_MAJOR_VERSION: * diff --git a/meson_options.txt b/meson_options.txt index 24c8f02..d6a6060 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -2,7 +2,7 @@ option('manpage', type: 'boolean', value: true, description: 'Build man pages') option('gcrypt', type: 'boolean', value: true, description: 'With gcrypt and transport encryption') option('debugging', type: 'boolean', value: false, description: 'Turn debugging on/off') option('vapi', type: 'boolean', value: true, description: 'Create VAPI file.') -option('gtk_doc', type: 'boolean', value: true, description: 'Build reference documentation using gtk-doc') +option('gtk_doc', type: 'boolean', value: true, description: 'Build reference documentation using gi-docgen') option('introspection', type: 'boolean', value: true, description: 'Create GIR file.') option('bashcompdir', type: 'string', value: '', description: 'Override default location for bash completion files') option('bash_completion', type: 'feature', value: 'auto', description: 'Install bash completion files') diff --git a/subprojects/gi-docgen.wrap b/subprojects/gi-docgen.wrap new file mode 100644 index 0000000..98cd921 --- /dev/null +++ b/subprojects/gi-docgen.wrap @@ -0,0 +1,6 @@ +[wrap-git] +directory=gi-docgen +url=https://gitlab.gnome.org/GNOME/gi-docgen.git +push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git +revision=main +depth=1