[libsecret: 1/2] Port documentation to gi-docgen
- From: Dhanuka Warusadura <dhanuka src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libsecret: 1/2] Port documentation to gi-docgen
- Date: Wed, 2 Feb 2022 12:19:15 +0000 (UTC)
commit 2c3a34cca46f523e0a1df62000c51c5e17d0b589
Author: Maximiliano <msandova gnome org>
Date: Wed Feb 2 12:19:14 2022 +0000
Port documentation to gi-docgen
.gitignore | 1 -
.gitlab-ci.yml | 29 +-
README.md | 5 +
docs/reference/libsecret/libsecret-c-examples.md | 251 ++++++
docs/reference/libsecret/libsecret-docs.sgml | 47 --
docs/reference/libsecret/libsecret-examples.sgml | 785 -------------------
docs/reference/libsecret/libsecret-js-examples.md | 170 +++++
docs/reference/libsecret/libsecret-overrides.txt | 2 -
.../libsecret/libsecret-python-examples.md | 152 ++++
docs/reference/libsecret/libsecret-sections.txt | 389 ----------
docs/reference/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 ---
.../reference/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(-)
---
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-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-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-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-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 <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:
+
+```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-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<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+Secret.password_storev.begin (example_schema, attributes, Secret.COLLECTION_DEFAULT,
+ "The label", "the password", null, (obj, async_res) => {
+ bool res = Secret.password_store.end (async_res);
+ /* ... do something now that the password has been stored */
+});
+```
+
+If you are already inside of an async function, you can also
+use the yield keyword:
+
+```vala
+var attributes = new GLib.HashTable<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+bool res = yield Secret.password_storev (example_schema, attributes,
+ Secret.COLLECTION_DEFAULT, "The label",
+ "the password", null);
+```
+
+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<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+Secret.password_lookupv.begin (example_schema, attributes, null, (obj, async_res) => {
+ string password = Secret.password_lookup.end (async_res);
+});
+```
+
+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<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+Secret.password_clearv.begin (example_schema, attributes, null, (obj, async_res) => {
+ bool removed = Secret.password_clearv.end (async_res);
+});
+```
+
+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<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+bool removed = Secret.password_clear_sync (example_schema, null,
+ "number", 8, "string", "eight", "even", true);
+/* removed will be true if the password was removed */
+```
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/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',
-]
-
-reference_ignore_headers = [
- 'mock-service.h',
- 'secret-dbus-generated.h',
- 'secret-private.h',
-]
+toml_data = configuration_data()
+toml_data.set('VERSION', meson.project_version())
-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
+<link linkend="libsecret-Password-storage">simple password API for storing and retrieving passwords</link>
+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
+<ulink url="http://standards.freedesktop.org/secret-service/";>Secret Service DBus API</ulink>
+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 <link linkend="migrating-schemas">focused on schemas</link>,
+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:
+
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td>GnomeKeyringAttributeList</td>
+ <td>a [struct@GLib.HashTable] of string keys and values</td>
+ </tr>
+ <tr>
+ <td>GnomeKeyringAttribute</td>
+ <td>a key/value pair in a [struct@GLib.HashTable] of strings</td>
+ </tr>
+ <tr>
+ <td>GnomeKeyringAttributeType</td>
+ <td>[struct@Schema]AttributeType</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ATTRIBUTE_TYPE_STRING</code></td>
+ <td><code>SECRET_SCHEMA_ATTRIBUTE_STRING</code></td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32</code></td>
+ <td><code>SECRET_SCHEMA_ATTRIBUTE_INTEGER</code></td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_attribute_list_index()</code></td>
+ <td>use [func@GLib.HashTable.lookup] on the attributes hash table</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_attribute_get_string()</code></td>
+ <td>use [func@GLib.HashTable.lookup] on the attributes hash table</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_attribute_get_uint32()</code></td>
+ <td>no equivalent, use [func@GLib.HashTable.lookup]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_attribute_list_append_string()</code></td>
+ <td>[func@attributes_build]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_attribute_list_append_uint32()</code></td>
+ <td>[func@attributes_build]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_attribute_list_copy()</code></td>
+ <td>[func GLib HashTable ref]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_attribute_list_free()</code></td>
+ <td>[func@GLib.HashTable.unref]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_attribute_list_index()</code></td>
+ <td>no equivalent, use [func@GLib.HashTable.lookup]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_attribute_list_new()</code></td>
+ <td>[func@attributes_build]</td>
+ </tr>
+</table>
+
+## 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:
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td>GnomeKeyringPasswordSchema</td>
+ <td>[struct@Schema]</td>
+ </tr>
+ <tr>
+ <td>GnomeKeyringPasswordSchemaAttribute</td>
+ <td>[struct@Schema]Attribute</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ITEM_APPLICATION_SECRET</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORD</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORD</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ITEM_PK_STORAGE</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ITEM_GENERIC_SECRET</code></td>
+ <td>no equivalent, define a specific schema with an appropriate dotted name</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ITEM_NETWORK_PASSWORD</code></td>
+ <td>the <code>SECRET_SCHEMA_COMPAT_NETWORK</code> schema, although not recommended for new uses</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ITEM_NOTE</code></td>
+ <td>the <code>SECRET_SCHEMA_NOTE</code> schema</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_NETWORK_PASSWORD</code></td>
+ <td>the <code>SECRET_SCHEMA_COMPAT_NETWORK</code> schema, although not recommended for new uses</td>
+ </tr>
+</table>
+
+## 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:
+
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_DEFAULT</code></td>
+ <td>[const@COLLECTION_DEFAULT]</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_SESSION</code></td>
+ <td>[const@COLLECTION_SESSION]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_store_password()</code></td>
+ <td>[func@password_store]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_store_password_sync()</code></td>
+ <td>[func@password_store_sync]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_set_network_password()</code></td>
+ <td>[func@password_store] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>
+ although this is not recommended for new uses.</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_set_network_password_sync()</code></td>
+ <td>[func@password_store_sync] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>
+ although this is not recommended for new uses.</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_create()</code></td>
+ <td>[func@Item.create], although using [func@password_store]
+ is simpler.</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_create_sync()</code></td>
+ <td>[func@Item.create], although using [func@password_store_sync]
+ is simpler.</td>
+ </tr>
+</table>
+
+## 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:
+
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_find_password()</code></td>
+ <td>[func@password_lookup]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_find_password_sync()</code></td>
+ <td>[func@password_lookup_sync]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_find_items()</code></td>
+ <td>[method@Service.search], with flags to fine tune behavior</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_find_itemsv()</code></td>
+ <td>[method@Service.search], with flags to fine tune behavior</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_find_items_sync()</code></td>
+ <td>[method@Service.search_sync], with flags to fine tune behavior</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_find_itemsv_sync()</code></td>
+ <td>[method@Service.search], with flags to fine tune behavior</td>
+ </tr>
+ <tr>
+ <td>GnomeKeyringFound</td>
+ <td>no equivalent, [method@Service.search] returns a [struct GLib List] of
+ [class@Item]<!-- -->s, and other methods return passwords directly.</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_found_copy()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_found_free()</code></td>
+ <td>[method@GObject.Object.unref] on the each of the items returned from
+ [method@Service.search]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_found_list_free()</code></td>
+ <td>[func GLib List.free_full] used with [method@GObject.Object.unref] on the items returned from
+ [method@Service.search]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_find_network_password()</code></td>
+ <td>[func@password_lookup] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>,
+ although this only returns one password and no attributes</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_find_network_password_sync()</code></td>
+ <td>[func@password_lookup_sync] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>,
+ although this only returns one password and no attributes</td>
+ </tr>
+ <tr>
+ <td>GnomeKeyringNetworkPasswordData</td>
+ <td>no equivalent, [func@password_lookup] gets the password directly
+ and no attributes</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_network_password_free()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_network_password_list_free()</code></td>
+ <td>no equivalent</td>
+ </tr>
+</table>
+
+## 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:
+
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_delete_password()</code></td>
+ <td>[func@password_clear], although we now try to delete
+ all unlocked matching items</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_delete_password_sync()</code></td>
+ <td>[func@password_clear_sync], although we now try to delete
+ all unlocked matching items</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_delete()</code></td>
+ <td>[method@Item.delete]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_delete_sync()</code></td>
+ <td>[method@Item.delete_sync]</td>
+ </tr>
+</table>
+
+## 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:
+
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_create()</code></td>
+ <td>[func@Item.create], although [func@password_store] may be simpler</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_create_sync()</code></td>
+ <td>[func@Item.create_sync], although [func@password_store_sync] may be simpler</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_delete()</code></td>
+ <td>[method@Item.delete], although [func@password_clear] may be simpler</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_delete_sync()</code></td>
+ <td>[method@Item.delete_sync], although [func@password_clear_sync] may be simpler</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_get_info()</code></td>
+ <td>properties are loaded on a [class@Item] automatically, use
+ [method@Item.load_secret] to load the secret</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_get_info_sync()</code></td>
+ <td>properties are loaded on a [class@Item] automatically, use
+ [method@Item.load_secret_sync] to load the secret</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_get_info_full()</code></td>
+ <td>properties are loaded on a [class@Item] automatically, use
+ [method@Item.load_secret] to load the secret</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_get_info_full_sync()</code></td>
+ <td>properties are loaded on a [class@Item] automatically, use
+ [method@Item.load_secret_sync] to load the secret</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_set_info()</code></td>
+ <td>use the appropriate setter methods on [class@Item]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_set_info_sync()</code></td>
+ <td>use the appropriate setter methods on [class@Item]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_get_attributes()</code></td>
+ <td>[method@Item.get_attributes]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_get_attributes_sync()</code></td>
+ <td>[method@Item.get_attributes]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_set_attributes()</code></td>
+ <td>[method@Item.set_attributes]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_set_attributes_sync()</code></td>
+ <td>[method@Item.set_attributes_sync]</td>
+ </tr>
+ <tr>
+ <td>GnomeKeyringItemType</td>
+ <td>replaced by the name of a [struct@Schema]</td>
+ </tr>
+ <tr>
+ <td>GnomeKeyringItemInfo</td>
+ <td>[class@Item]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_new()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_copy()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_free()</code></td>
+ <td>[method@GObject.Object.unref] on the [class@Item]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_get_display_name()</code></td>
+ <td>[method@Item.get_label]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_set_display_name()</code></td>
+ <td>[method@Item.set_label]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_get_ctime()</code></td>
+ <td>[method@Item.get_created]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_get_mtime()</code></td>
+ <td>[method@Item.get_modified]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_get_type()</code></td>
+ <td>[method@Item.get_schema_name]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_set_type()</code></td>
+ <td>[method@Item.set_attributes] with appropriate schema</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_get_secret()</code></td>
+ <td>[method@Item.get_secret]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_set_secret()</code></td>
+ <td>[method@Item.set_secret] and [method@Item.set_secret_sync]</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ITEM_INFO_BASICS</code></td>
+ <td>no equivalent, all basic item properties are loaded on [class@Item]
+ automatically</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_ITEM_INFO_SECRET</code></td>
+ <td>use [method@Item.load_secret] and [method@Item.load_secret_sync] to load
+ the secret for an item.</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_item_info_set_display_name()</code></td>
+ <td></td>
+ </tr>
+</table>
+
+## 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:
+
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_create()</code></td>
+ <td>[func@Collection.create]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_create_sync()</code></td>
+ <td>[func@Collection.create_sync]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_delete()</code></td>
+ <td>[method@Collection.delete]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_delete_sync()</code></td>
+ <td>[method@Collection.delete_sync]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_change_password()</code></td>
+ <td>no equivalent, use platform specific DBus APIs</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_change_password_sync()</code></td>
+ <td>no equivalent, use platform specific DBus APIs</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_list_keyring_names()</code></td>
+ <td>[method@Service.load_collections] and [method@Service.get_collections]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_list_keyring_names_sync()</code></td>
+ <td>[method@Service.load_collections_sync] and [method@Service.get_collections]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_set_default_keyring()</code></td>
+ <td>[method@Service.set_alias]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_set_default_keyring_sync()</code></td>
+ <td>[method@Service.set_alias_sync]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_get_default_keyring()</code></td>
+ <td>[func@Collection.for_alias] with [const@COLLECTION_DEFAULT]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_get_default_keyring_sync()</code></td>
+ <td>[func@Collection.for_alias_sync] with [const@COLLECTION_DEFAULT]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_list_item_ids()</code></td>
+ <td>[method@Collection.load_items] and [method@Collection.get_items]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_list_item_ids_sync()</code></td>
+ <td>[method@Collection.load_items_sync] and [method@Collection.get_items]</td>
+ </tr>
+ <tr>
+ <td>GnomeKeyringInfo</td>
+ <td>[class@Collection] and properties</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_get_info()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_get_info_sync()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_set_info()</code></td>
+ <td>no equivalent, use property setters on [class@Collection]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_set_info_sync()</code></td>
+ <td>no equivalent, use property setters on [class@Collection]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_info_free()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_info_copy()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_info_set_lock_on_idle()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_info_get_lock_on_idle()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_info_set_lock_timeout()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_info_get_lock_timeout()</code></td>
+ <td>no equivalent</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_info_get_mtime()</code></td>
+ <td>[method@Collection.get_modified]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_info_get_ctime()</code></td>
+ <td>[method@Collection.get_created]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_info_get_is_locked()</code></td>
+ <td>[method@Collection.get_locked]</td>
+ </tr>
+</table>
+
+## 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:
+
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_unlock()</code></td>
+ <td>[method@Service.unlock]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_unlock_sync()</code></td>
+ <td>[method@Service.unlock_sync]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_lock()</code></td>
+ <td>[method Service lock]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_lock_sync()</code></td>
+ <td>[method@Service.lock_sync]</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_lock_all()</code></td>
+ <td>no equivalent, use platform specific DBus APIs</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_lock_all_sync()</code></td>
+ <td>no equivalent, use platform specific DBus APIs</td>
+ </tr>
+</table>
+
+## Non-pageable memory
+
+libsecret no longer provides a full API for using non-pageable
+memory. Use the <ulink url="http://developer.gnome.org/gcr/stable/gcr-Non-pageable-Memory.html";>equivalent
API in the Gcr library</ulink>.
+
+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:
+
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_memory_alloc()</code></td>
+ <td>no equivalent, use Gcr</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_memory_free()</code></td>
+ <td>[func@password_free], although this only works on strings</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_memory_is_secure()</code></td>
+ <td>no equivalent, use Gcr</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_memory_new()</code></td>
+ <td>no equivalent, use Gcr</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_memory_realloc()</code></td>
+ <td>no equivalent, use Gcr</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_memory_strdup()</code></td>
+ <td>no equivalent, use [struct@Value] which is ref-counted, or use Gcr</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_memory_try_alloc()</code></td>
+ <td>no equivalent, use Gcr</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_memory_try_realloc()</code></td>
+ <td>no equivalent, use Gcr</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_free_password()</code></td>
+ <td>[func@password_free]</td>
+ </tr>
+</table>
+
+## 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:
+
+<table>
+ <tr>
+ <th>libgnome-keyring</th><th>libsecret</th>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_cancel_request()</code></td>
+ <td>[method@Gio.Cancellable.cancel] on a [class@Gio.Cancellable] passed to the relevant
operation</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_is_available()</code></td>
+ <td>no equivalent, the secret service is autostarted as necessary</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_result_to_message()</code></td>
+ <td>use the message in the [struct@GLib.Error], although most failures are not appropriate for
display to the user</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_OK</code></td>
+ <td>no [struct@GLib.Error] returned</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_DENIED</code></td>
+ <td>no longer used, item or collection is simply not unlocked</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_NO_KEYRING_DAEMON</code></td>
+ <td><code>G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND</code></td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_ALREADY_UNLOCKED</code></td>
+ <td>no error, success returned</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_NO_SUCH_KEYRING</code></td>
+ <td>keyrings no longer have names, accessing an missing DBus object has usual failure</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_BAD_ARGUMENTS</code></td>
+ <td><code>G_DBUS_ERROR_INVALID_ARGS</code> or precondition failure in libsecret, this is always
+ a programmer error</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_IO_ERROR</code></td>
+ <td>relevant DBus errors, or <code>SECRET_ERROR_PROTOCOL</code></td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_CANCELLED</code></td>
+ <td><code>G_IO_ERROR_CANCELLED</code></td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTS</code></td>
+ <td>no error, simply returns already existing keyring</td>
+ </tr>
+ <tr>
+ <td><code>GNOME_KEYRING_RESULT_NO_MATCH</code></td>
+ <td>on error, an empty list is returned</td>
+ </tr>
+ <tr>
+ <td><code>gnome_keyring_string_list_free()</code></td>
+ <td>no equivalent</td>
+ </tr>
+</table>
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/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 <string.h>
-/**
- * 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 <glib/gi18n-lib.h>
/**
- * 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 <glib/gi18n-lib.h>
/**
- * 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 <literal>xdg:schema</literal> 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 <egg/egg-secure-memory.h>
-/**
- * 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
- * <literal>org.freedesktop.Secret.Collection.Label</literal>. 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
- * <literal>org.freedesktop.Secret.Collection.Label</literal>. 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
- * <literal>org.freedesktop.Secret.Item.Label</literal>. 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
- * <literal>org.freedesktop.Secret.Item.Label</literal>. 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 <literal>prompt_async</literal> 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 <literal>prompt_async</literal> 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 <literal>(oayays)</literal> 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 <literal>(oayays)</literal> 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 <glib/gi18n-lib.h>
/**
- * SECTION:secret-prompt
- * @title: SecretPrompt
- * @short_description: a prompt in the Service
+ * SecretPrompt:
+ *
+ * A prompt in the Service
*
- * A #SecretPrompt represents a prompt in the Secret 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 <literal>%d</literal>
- * 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 <literal>%d</literal>
- * 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 <literal>%d</literal>
- * 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:
- *
- * <informalexample><programlisting language="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;
- * }
- * </programlisting></informalexample>
- *
- * 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
- * <literal>GNOME_KEYRING_ITEM_NOTE</literal> 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
- * <literal>GNOME_KEYRING_ITEM_NETWORK_PASSWORD</literal> item type will match.
- *
- * The following attributes exist in the schema:
- * <variablelist><title>Attributes:</title>
- * <varlistentry><term><literal>user</literal>:</term>
- * <listitem><para>The user name (string).</para></listitem></varlistentry>
- * <varlistentry><term><literal>domain</literal>:</term>
- * <listitem><para>The login domain or realm (string).</para></listitem></varlistentry>
- * <varlistentry><term><literal>object</literal>:</term>
- * <listitem><para>The object or path (string).</para></listitem></varlistentry>
- * <varlistentry><term><literal>protocol</literal>:</term>
- * <listitem><para>The protocol (a string like 'http').</para></listitem></varlistentry>
- * <varlistentry><term><literal>port</literal>:</term>
- * <listitem><para>The network port (integer).</para></listitem></varlistentry>
- * <varlistentry><term><literal>server</literal>:</term>
- * <listitem><para>The hostname or server (string).</para></listitem></varlistentry>
- * <varlistentry><term><literal>authtype</literal>:</term>
- * <listitem><para>The authentication type (string).</para></listitem></varlistentry>
- * </variablelist>
- */
-
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:
+ *
+ * <table>
+ * <tr>
+ * <td><tt>user</tt>:</td>
+ * <td>The user name (string).</td>
+ * </tr>
+ * <tr>
+ * <td><tt>domain</tt>:</td>
+ * <td>The login domain or realm (string).</td></tr>
+ * <tr>
+ * <td><tt>object</tt>:</td>
+ * <td>The object or path (string).</td>
+ * </tr>
+ * <tr>
+ * <td><tt>protocol</tt>:</td>
+ * <td>The protocol (a string like 'http').</td>
+ * </tr>
+ * <tr>
+ * <td><tt>port</tt>:</td>
+ * <td>The network port (integer).</td>
+ * </tr>
+ * <tr>
+ * <td><tt>server</tt>:</td>
+ * <td>The hostname or server (string).</td>
+ * </tr>
+ * <tr>
+ * <td><tt>authtype</tt>:</td>
+ * <td>The authentication type (string).</td>
+ * </tr>
+ * </table>
*
* 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 <literal>prompt_async</literal>
- * and <literal>prompt_finish</literal> 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 <literal>prompt_sync</literal> 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 <literal>window_id</literal>.
+ * 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 <literal>prompt_async</literal> 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 <string.h>
/**
- * 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 <string.h>
/**
- * 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 <literal>text/plain</literal>.
+ * 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
- * <literal>text/plain</literal>.
+ * `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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
