diff options
| author | Niels De Graef <nielsdegraef@gmail.com> | 2021-09-30 13:41:44 +0200 |
|---|---|---|
| committer | Corentin Noël <tintou@noel.tf> | 2021-11-10 10:51:39 +0000 |
| commit | 6fc2f87a5e02558d9550a533fc0266aea5a127c0 (patch) | |
| tree | fbb7ea3fabb25080e36a12738ab6504c30a34371 | |
| parent | 8617fe225a045a0eba701bdc0bf6349480720233 (diff) | |
| download | gcr-6fc2f87a5e02558d9550a533fc0266aea5a127c0.tar.gz | |
docs: Port from gtk-doc to gi-docgen
gtk-doc has been slowly dying for the past few years. With gi-docgen we
have a clear successor in sight to replace the voodoo magic one needs to
get the whole documentation setup.
See the [gi-docgen tutorial] for more info on how the system works.
Since we're now only the C compiler (and GIR) parse the C code, that
means we can also get rid of all the special escapes for the # character
in PKCS#11.
[gi-docgen tutorial]: https://gnome.pages.gitlab.gnome.org/gi-docgen/tutorial.html
91 files changed, 1038 insertions, 3667 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 1049863..a7da4f9 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -3,7 +3,7 @@ stages: - deploy variables: - DEPENDENCIES: dbus-daemon diffutils gcc gtk-doc libsecret-devel meson ninja-build openssh openssh-clients python redhat-rpm-config systemd-devel + DEPENDENCIES: dbus-daemon diffutils gcc gi-docgen libsecret-devel meson ninja-build openssh openssh-clients python redhat-rpm-config systemd-devel fedora:Werror: image: fedora:latest diff --git a/docs/reference/COPYING b/docs/COPYING index d5c1293..d5c1293 100644 --- a/docs/reference/COPYING +++ b/docs/COPYING diff --git a/docs/gck/gck.toml.in b/docs/gck/gck.toml.in new file mode 100644 index 0000000..696b940 --- /dev/null +++ b/docs/gck/gck.toml.in @@ -0,0 +1,34 @@ +[library] +namespace = "Gck" +version = "@GCK_VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/gcr/" +repository_url = "https://gitlab.gnome.org/GNOME/gcr.git" +authors = "GCK contributors" +license = "LGPL-2.0-or-later" +description = "GObject bindings for PKCS#11" +dependencies = [ "GObject-2.0", "Gio-2.0" ] +devhelp = true +search_index = true + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + + [dependencies."Gio-2.0"] + name = "Gio" + description = "GObject interfaces and objects" + docs_url = "https://developer.gnome.org/gio/stable" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/gcr/-/blob/master/" + +[extra] +content_files = [ + 'pkcs11-links.md', +] diff --git a/docs/gck/meson.build b/docs/gck/meson.build new file mode 100644 index 0000000..f06381b --- /dev/null +++ b/docs/gck/meson.build @@ -0,0 +1,34 @@ +gck_content_files = [ + 'pkcs11-links.md', +] + +gck_toml = configure_file( + input: 'gck.toml.in', + output: 'gck.toml', + configuration: { + 'GCK_VERSION': gck_major_version, + }, +) + +gck_docs = custom_target('gck-docs', + input: gck_gir[0], + output: 'gck-@0@'.format(gck_major_version), + command: [ + gi_docgen, + 'generate', + '--quiet', + '--fatal-warnings', + '--config', gck_toml, + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT@', + ], + depend_files: [ + gck_toml, + gck_content_files, + ], + build_by_default: true, + install: true, + install_dir: get_option('datadir') / 'doc', +) diff --git a/docs/gck/pkcs11-links.md b/docs/gck/pkcs11-links.md new file mode 100644 index 0000000..ad89d6c --- /dev/null +++ b/docs/gck/pkcs11-links.md @@ -0,0 +1,32 @@ +Title: About PKCS#11 + +About PKCS#11 +============= +PKCS#11 is an API for storing and using crypto objects, and performing crypto +operations on them. + +It is specified at the [RSA website] and a [handy PKCS#11 reference] is also +available. + +## PKCS#11 URIs +[PKCS#11 URIs] are a standard for referring to PKCS#11 modules, tokens, or +objects. What the PKCS#11 URI refers to depends on the context in which it is +used. + +A PKCS#11 URI can always resolve to more than one object, token or module. A +PKCS#11 URI that refers to a token, would (when used in a context that expects +objects) refer to all the token on that module. + +To parse a PKCS#11 URI, use the [func@uri_parse] function passing in the type of +context in which you're using the URI. To build a URI, use the [func@uri_build] +function. + +In most cases, the parsing or building of URIs is already handled for you in the +GCK library. For example: to enumerate objects that match a PKCS#11 URI use the +[func@modules_enumerate_uri] function. + + + +[RSA website]: http://www.rsa.com/rsalabs/node.asp?id=2133 +[handy PKCS#11 reference]: http://www.cryptsoft.com/pkcs11doc/ +[PKCS#11 URIs]: http://tools.ietf.org/html/draft-pechanec-pkcs11uri-03 diff --git a/docs/gcr/gcr-base.toml.in b/docs/gcr/gcr-base.toml.in new file mode 100644 index 0000000..3c746a0 --- /dev/null +++ b/docs/gcr/gcr-base.toml.in @@ -0,0 +1,40 @@ +[library] +namespace = "Gcr" +version = "@GCR_VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/gcr/" +repository_url = "https://gitlab.gnome.org/GNOME/gcr.git" +authors = "GCR contributors" +license = "LGPL-2.0-or-later" +description = "GObject and GUI library for high level crypto handling" +dependencies = [ "GObject-2.0", "Gio-2.0", "Gck-@GCK_VERSION@" ] +devhelp = true +search_index = true + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + + [dependencies."Gio-2.0"] + name = "Gio" + description = "GObject interfaces and objects" + docs_url = "https://developer.gnome.org/gio/stable" + + [dependencies."Gck-@GCK_VERSION@"] + name = "Gck" + description = "GObject bindings for PKCS#11" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/gcr/-/blob/master/" + +[extra] +content_files = [ + 'non-pageable-memory.md', + 'pkcs11-configuration.md', + 'trust-store.md', +] diff --git a/docs/gcr/meson.build b/docs/gcr/meson.build new file mode 100644 index 0000000..cf6532f --- /dev/null +++ b/docs/gcr/meson.build @@ -0,0 +1,36 @@ +gcr_base_content_files = [ + 'non-pageable-memory.md', + 'pkcs11-configuration.md', + 'trust-store.md', +] + +gcr_base_toml = configure_file( + input: 'gcr-base.toml.in', + output: '@BASENAME@', + configuration: { + 'GCR_VERSION': gcr_major_version, + 'GCK_VERSION': gck_major_version, + }, +) + +gcr_base_docs = custom_target('gcr-docs', + input: gcr_gir[0], + output: 'gcr-@0@'.format(gcr_major_version), + command: [ + gi_docgen, + 'generate', + '--quiet', + '--fatal-warnings', + '--add-include-path=@0@'.format(build_root / 'gck'), + '--config', gcr_base_toml, + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT@', + ], + depend_files: [ gcr_base_toml, gcr_base_content_files ], + depends: [ gck_gir[0] ], + build_by_default: true, + install: true, + install_dir: get_option('datadir') / 'doc', +) diff --git a/docs/gcr/non-pageable-memory.md b/docs/gcr/non-pageable-memory.md new file mode 100644 index 0000000..1f77f42 --- /dev/null +++ b/docs/gcr/non-pageable-memory.md @@ -0,0 +1,21 @@ +Title: Non-pageable memory + +Non-pageable memory +=================== +Normal allocated memory can be paged to disk at the whim of the operating +system. This can be a problem for sensitive information like passwords, keys +and secrets. + +The Gcr library holds passwords and keys in *non-pageable*, or *locked* memory. +This is only possible if the OS contains support for it. + +The set of `gcr_secure_memory_*()` functions allow applications to use secure +memory to hold passwords and other sensitive information. + +* [func@Gcr.secure_memory_alloc] +* [func@Gcr.secure_memory_try_alloc] +* [func@Gcr.secure_memory_realloc] +* [func@Gcr.secure_memory_try_realloc] +* [func@Gcr.secure_memory_is_secure] +* [func@Gcr.secure_memory_strdup] +* [func@Gcr.secure_memory_strfree] diff --git a/docs/gcr/pkcs11-configuration.md b/docs/gcr/pkcs11-configuration.md new file mode 100644 index 0000000..8c06f05 --- /dev/null +++ b/docs/gcr/pkcs11-configuration.md @@ -0,0 +1,16 @@ +Title: PKCS#11 configuration + +PKCS#11 configuration +===================== +The GCR library maintains a global list of PKCS#11 modules to use for +its various lookups and storage operations. Each module is represented by +a [class@Gck.Module] object. You can examine this list by using +[func@pkcs11_get_modules]. + +The list is configured automatically by looking for system installed +PKCS#11 modules. It's not not normally necessary to modify this list. But +if you have special needs, you can use the [func@pkcs11_set_modules] and +[func@pkcs11_add_module] (or [func@pkcs11_add_module_from_file]) to do so. + +Trust assertions are stored and looked up in specific PKCS#11 slots. +You can examine this list with [func@pkcs11_get_trust_lookup_slots]. diff --git a/docs/gcr/trust-store.md b/docs/gcr/trust-store.md new file mode 100644 index 0000000..1c97ec2 --- /dev/null +++ b/docs/gcr/trust-store.md @@ -0,0 +1,38 @@ +Title: Trust store +Description: Store/Lookup bits of information used for verifying certificates. + +Trust store +=========== +GCR provides functions to access information about which certificates the system +and user trusts, such as certificate authority trust anchors, or overrides +to the normal verification of certificates. + +These functions do not constitute a viable method for verifying certificates +used in TLS or other locations. Instead they support such verification by +providing some of the needed data for a trust decision. + +The storage is provided by pluggable PKCS#11 modules. + +Trust Anchors +------------- +Trust anchors are used to verify the certificate authority in a certificate +chain. Trust anchors are always valid for a given purpose. The most common +purpose is [const@PURPOSE_SERVER_AUTH] and is used for a client application to +verify that the certificate at the server side of a TLS connection is authorized +to act as such. To check if a certificate is a trust anchor, use +[func@Gcr.trust_is_certificate_anchored], or +[func@Gcr.trust_is_certificate_anchored_async] for the asynchronous version + +Pinned certificates +------------------- +Pinned certificates are used when a user overrides the default trust decision +for a given certificate. They're often used with self-signed certificates. +Pinned certificates are always only valid for a single peer such as the remote +host with which TLS is being performed. To lookup pinned certificates, use +[func@Gcr.trust_is_certificate_pinned], or +[func@Gcr.trust_is_certificate_pinned_async] for the asynchronous version. + +After the user has requested to override the trust decision about a given +certificate then a pinned certificates can be added by using the +[func@Gcr.trust_add_pinned_certificate] function, or +[func@Gcr.trust_add_pinned_certificate_async] for the asynchronous version. diff --git a/docs/meson.build b/docs/meson.build index f353516..b90095c 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -1,2 +1,12 @@ -subdir('reference/gck') -subdir('reference/gcr') +gi_docgen = find_program('gi-docgen') + +subdir('gck') +subdir('gcr') +subdir('ui') + +# Create a pseudo target that build all docs at once +alias_target('docs', + gck_docs, + gcr_base_docs, + gcr_ui_docs, +) diff --git a/docs/reference/gck/gck-docs.sgml b/docs/reference/gck/gck-docs.sgml deleted file mode 100644 index 7e8beec..0000000 --- a/docs/reference/gck/gck-docs.sgml +++ /dev/null @@ -1,37 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -<!ENTITY version SYSTEM "version.xml"> -]> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>Gck Library Reference Manual</title> - <releaseinfo> - For Gck &version;. - An online version of this documentation can be found at - <ulink role="online-location" url="http://developer.gnome.org/gck/stable/">http://developer.gnome.org/gck/stable/</ulink>. - </releaseinfo> - </bookinfo> - - <chapter id="reference"> - <title>PKCS#11 GObject Bindings</title> - <xi:include href="xml/gck-module.xml"/> - <xi:include href="xml/gck-slot.xml"/> - <xi:include href="xml/gck-session.xml"/> - <xi:include href="xml/gck-object.xml"/> - <xi:include href="xml/gck-attribute.xml"/> - <xi:include href="xml/gck-attributes.xml"/> - <xi:include href="xml/gck-object-cache.xml"/> - <xi:include href="xml/gck-enumerator.xml"/> - <xi:include href="xml/gck-modules.xml"/> - <xi:include href="xml/gck-error.xml"/> - <xi:include href="xml/gck-uri.xml"/> - <xi:include href="xml/gck-library.xml"/> - <xi:include href="xml/gck-misc.xml"/> - </chapter> - - <xi:include href="gck-pkcs11-links.xml"/> - <xi:include href="xml/annotation-glossary.xml"> - <xi:fallback /> - </xi:include> -</book> diff --git a/docs/reference/gck/gck-overrides.txt b/docs/reference/gck/gck-overrides.txt deleted file mode 100644 index 13f485f..0000000 --- a/docs/reference/gck/gck-overrides.txt +++ /dev/null @@ -1,2 +0,0 @@ -# These are manually-edited to override or add declarations to those scanned -# from the header files. diff --git a/docs/reference/gck/gck-pkcs11-links.xml b/docs/reference/gck/gck-pkcs11-links.xml deleted file mode 100644 index 9341ccf..0000000 --- a/docs/reference/gck/gck-pkcs11-links.xml +++ /dev/null @@ -1,25 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter xml:id="pkcs11-links"> - <title>About PKCS#11</title> - - <anchor id="CK-NOTIFY:CAPS"/> - <anchor id="CK-SLOT-ID:CAPS"/> - <anchor id="CK-FUNCTION-LIST-PTR:CAPS"/> - <anchor id="CK-RV:CAPS"/> - <anchor id="CK-SESSION-HANDLE:CAPS"/> - <anchor id="CK-OBJECT-HANDLE:CAPS"/> - <anchor id="CK-OBJECT-HANDLE-PTR:CAPS"/> - <anchor id="CK-ULONG:CAPS"/> - <anchor id="CK-BBOOL:CAPS"/> - - <para>PKCS#11 is an API for storing and using crypto objects, and performing - crypto operations on them.</para> - - <para>It is specified at the - <ulink href="http://www.rsa.com/rsalabs/node.asp?id=2133">RSA website</ulink> - and a <ulink href="http://www.cryptsoft.com/pkcs11doc/">handy reference</ulink> is also - available.</para> - -</chapter> diff --git a/docs/reference/gck/gck-sections.txt b/docs/reference/gck/gck-sections.txt deleted file mode 100644 index 93777f7..0000000 --- a/docs/reference/gck/gck-sections.txt +++ /dev/null @@ -1,484 +0,0 @@ -<SECTION> -<TITLE>Library Utilities</TITLE> -<FILE>gck-library</FILE> -GCK_CHECK_VERSION -GCK_MAJOR_VERSION -GCK_MICRO_VERSION -GCK_MINOR_VERSION -</SECTION> - -<SECTION> -<FILE>gck-attribute</FILE> -GckAttribute -gck_attribute_is_invalid -gck_attribute_get_boolean -gck_attribute_get_ulong -gck_attribute_get_string -gck_attribute_get_date -gck_attribute_get_data -gck_attribute_dump -gck_attribute_equal -gck_attribute_hash -gck_attribute_init -gck_attribute_init_boolean -gck_attribute_init_date -gck_attribute_init_string -gck_attribute_init_ulong -gck_attribute_init_empty -gck_attribute_init_invalid -gck_attribute_init_copy -gck_attribute_new -gck_attribute_new_boolean -gck_attribute_new_date -gck_attribute_new_string -gck_attribute_new_ulong -gck_attribute_new_empty -gck_attribute_new_invalid -gck_attribute_dup -gck_attribute_clear -gck_attribute_free -<SUBSECTION Standard> -GCK_TYPE_ATTRIBUTE -gck_attribute_get_type -</SECTION> - -<SECTION> -<FILE>gck-attributes</FILE> -GckAttributes -gck_attributes_new_empty -gck_attributes_at -gck_attributes_find -gck_attributes_find_boolean -gck_attributes_find_ulong -gck_attributes_find_string -gck_attributes_find_date -gck_attributes_count -gck_attributes_ref -gck_attributes_ref_sink -gck_attributes_unref -gck_attributes_contains -gck_attributes_to_string -gck_attributes_dump -GckBuilder -GckBuilderFlags -GCK_BUILDER_INIT -gck_builder_init -gck_builder_init_full -gck_builder_new -gck_builder_add_boolean -gck_builder_set_boolean -gck_builder_add_data -gck_builder_set_data -gck_builder_take_data -gck_builder_add_date -gck_builder_set_date -gck_builder_add_string -gck_builder_set_string -gck_builder_add_ulong -gck_builder_set_ulong -gck_builder_add_empty -gck_builder_set_empty -gck_builder_add_invalid -gck_builder_set_invalid -gck_builder_add_attribute -gck_builder_add_all -gck_builder_set_all -gck_builder_add_except -gck_builder_add_exceptv -gck_builder_add_only -gck_builder_add_onlyv -gck_builder_end -gck_builder_clear -gck_builder_steal -gck_builder_ref -gck_builder_unref -gck_builder_copy -gck_builder_find -gck_builder_find_boolean -gck_builder_find_date -gck_builder_find_string -gck_builder_find_ulong -gck_attributes_new -gck_attributes_add -gck_attributes_add_all -gck_attributes_add_boolean -gck_attributes_add_data -gck_attributes_add_date -gck_attributes_add_empty -gck_attributes_add_invalid -gck_attributes_add_string -gck_attributes_add_ulong -gck_attributes_dup -gck_attributes_new_full -gck_attributes_set -gck_attributes_set_all -gck_attributes_set_boolean -gck_attributes_set_date -gck_attributes_set_string -gck_attributes_set_ulong -<SUBSECTION Standard> -GCK_TYPE_BUILDER -GCK_TYPE_BUILDER_FLAGS -GCK_TYPE_ATTRIBUTES -gck_attributes_get_type -gck_attributes_get_boxed_type -gck_builder_flags_get_type -gck_builder_get_type -GckAllocator -</SECTION> - -<SECTION> -<FILE>gck-module</FILE> -GckModule -gck_module_initialize -gck_module_initialize_async -gck_module_initialize_finish -gck_module_new -gck_module_equal -gck_module_hash -gck_module_match -gck_module_get_path -gck_module_get_functions -gck_module_get_info -gck_module_get_slots -GckModuleInfo -gck_module_info_copy -gck_module_info_free -<SUBSECTION Standard> -GckModuleClass -gck_module_get_type -GCK_IS_MODULE -GCK_IS_MODULE_CLASS -GCK_MODULE -GCK_MODULE_CLASS -GCK_MODULE_GET_CLASS -GCK_TYPE_MODULE -GckModulePrivate -GCK_TYPE_MODULE_INFO -gck_module_info_get_type -</SECTION> - -<SECTION> -<FILE>gck-modules</FILE> -gck_modules_initialize_registered -gck_modules_initialize_registered_async -gck_modules_initialize_registered_finish -gck_modules_enumerate_objects -gck_modules_enumerate_uri -gck_modules_get_slots -gck_modules_object_for_uri -gck_modules_objects_for_uri -gck_modules_token_for_uri -gck_modules_tokens_for_uri -</SECTION> - -<SECTION> -<FILE>gck-slot</FILE> -GckMechanismInfo -gck_mechanism_info_copy -gck_mechanism_info_free -gck_mechanisms_length -gck_mechanisms_at -gck_mechanisms_check -GckSessionOptions -GckSlot -gck_slot_equal -gck_slot_hash -gck_slot_get_module -gck_slot_get_handle -gck_slot_get_info -gck_slot_match -gck_slot_get_token_info -gck_slot_get_mechanisms -gck_slot_get_mechanism_info -gck_slot_has_flags -gck_slot_enumerate_objects -gck_slots_enumerate_objects -gck_slot_open_session -gck_slot_open_session_full -gck_slot_open_session_full_async -gck_slot_open_session_async -gck_slot_open_session_finish -gck_slot_from_handle -GckSlotInfo -gck_slot_info_copy -gck_slot_info_free -GckTokenInfo -gck_token_info_copy -gck_token_info_free -<SUBSECTION Standard> -GckSlotClass -gck_slot_get_type -GCK_IS_SLOT -GCK_IS_SLOT_CLASS -GCK_SLOT -GCK_SLOT_CLASS -GCK_SLOT_GET_CLASS -GCK_TYPE_SLOT -GckSlotPrivate -GCK_TYPE_MECHANISM_INFO -GCK_TYPE_SLOT_INFO -GCK_TYPE_TOKEN_INFO -GckMechanisms -gck_mechanisms_free -gck_mechanism_info_get_type -gck_slot_info_get_type -gck_token_info_get_type -GCK_TYPE_SESSION_OPTIONS -gck_session_options_get_type -</SECTION> - -<SECTION> -<FILE>gck-session</FILE> -GckSession -gck_session_from_handle -gck_session_open -gck_session_open_async -gck_session_open_finish -gck_session_get_module -gck_session_get_slot -gck_session_get_handle -gck_session_get_info -gck_session_get_interaction -gck_session_login -gck_session_login_async -gck_session_login_finish -gck_session_logout -gck_session_logout_async -gck_session_logout_finish -gck_session_create_object -gck_session_create_object_async -gck_session_create_object_finish -gck_session_enumerate_objects -gck_session_find_handles -gck_session_find_handles_async -gck_session_find_handles_finish -gck_session_find_objects -gck_session_find_objects_async -gck_session_find_objects_finish -gck_session_encrypt -gck_session_encrypt_full -gck_session_encrypt_async -gck_session_encrypt_finish -gck_session_decrypt -gck_session_decrypt_full -gck_session_decrypt_async -gck_session_decrypt_finish -gck_session_login_interactive -gck_session_login_interactive_async -gck_session_login_interactive_finish -gck_session_set_interaction -gck_session_sign -gck_session_sign_full -gck_session_sign_async -gck_session_sign_finish -gck_session_verify -gck_session_verify_full -gck_session_verify_async -gck_session_verify_finish -gck_session_derive_key -gck_session_derive_key_async -gck_session_derive_key_finish -gck_session_derive_key_full -gck_session_generate_key_pair -gck_session_generate_key_pair_async -gck_session_generate_key_pair_finish -gck_session_generate_key_pair_full -gck_session_get_options -gck_session_get_state -gck_session_init_pin -gck_session_init_pin_async -gck_session_init_pin_finish -gck_session_set_pin -gck_session_set_pin_async -gck_session_set_pin_finish -gck_session_unwrap_key -gck_session_unwrap_key_async -gck_session_unwrap_key_finish -gck_session_unwrap_key_full -gck_session_wrap_key -gck_session_wrap_key_async -gck_session_wrap_key_finish -gck_session_wrap_key_full -GckSessionInfo -gck_session_info_copy -gck_session_info_free -GckMechanism -<SUBSECTION Standard> -gck_session_get_type -GckSessionClass -GCK_IS_SESSION -GCK_IS_SESSION_CLASS -GCK_SESSION -GCK_SESSION_CLASS -GCK_SESSION_GET_CLASS -GCK_TYPE_SESSION -GckSessionPrivate -GCK_TYPE_SESSION_INFO -gck_session_info_get_type -</SECTION> - -<SECTION> -<FILE>gck-object</FILE> -GckObject -GckObjectClass -gck_object_from_handle -gck_objects_from_handle_array -gck_object_equal -gck_object_hash -gck_object_get_module -gck_object_get_handle -gck_object_get_session -gck_object_destroy -gck_object_destroy_async -gck_object_destroy_finish -gck_object_set -gck_object_set_async -gck_object_set_finish -gck_object_get -gck_object_get_async -gck_object_get_finish -gck_object_get_data -gck_object_get_data_full -gck_object_get_data_async -gck_object_get_data_finish -gck_object_get_full -gck_object_get_template -gck_object_get_template_async -gck_object_get_template_finish -gck_object_set_template -gck_object_set_template_async -gck_object_set_template_finish -<SUBSECTION Standard> -gck_object_get_type -GCK_IS_OBJECT -GCK_IS_OBJECT_CLASS -GCK_OBJECT -GCK_OBJECT_CLASS -GCK_OBJECT_GET_CLASS -GCK_TYPE_OBJECT -GckObjectPrivate -</SECTION> - -<SECTION> -<FILE>gck-object-cache</FILE> -GckObjectCache -GckObjectCacheIface -gck_object_cache_get_attributes -gck_object_cache_set_attributes -gck_object_cache_fill -gck_object_cache_lookup -gck_object_cache_lookup_async -gck_object_cache_lookup_finish -gck_object_cache_update -gck_object_cache_update_async -gck_object_cache_update_finish -<SUBSECTION Standard> -gck_object_cache_get_type -GCK_IS_OBJECT_CACHE -GCK_OBJECT_CACHE -GCK_OBJECT_CACHE_GET_INTERFACE -GCK_TYPE_OBJECT_CACHE -</SECTION> - -<SECTION> -<FILE>gck-error</FILE> -GCK_VENDOR_CODE -GCK_ERROR -gck_message_from_rv -</SECTION> - -<SECTION> -<FILE>gck-uri</FILE> -GckUriData -GckUriError -GckUriFlags -GCK_URI_FOR_MODULE_WITH_VERSION -GCK_URI_FOR_OBJECT_ON_TOKEN -GCK_URI_FOR_OBJECT_ON_TOKEN_AND_MODULE -gck_uri_data_new -gck_uri_parse -gck_uri_build -gck_uri_data_copy -gck_uri_data_free -GCK_URI_ERROR -<SUBSECTION Private> -gck_uri_get_error_quark -GCK_URI_DATA_TYPE -gck_uri_data_get_type -gck_uri_error_get_quark -GCK_TYPE_URI_ERROR -GCK_TYPE_URI_FLAGS -gck_uri_error_get_type -gck_uri_flags_get_type -</SECTION> - -<SECTION> -<FILE>gck-enumerator</FILE> -GckEnumerator -gck_enumerator_next -gck_enumerator_next_async -gck_enumerator_next_finish -gck_enumerator_next_n -gck_enumerator_get_interaction -gck_enumerator_set_interaction -gck_enumerator_get_object_type -gck_enumerator_set_object_type -gck_enumerator_set_object_type_full -gck_enumerator_get_chained -gck_enumerator_set_chained -<SUBSECTION Standard> -GckEnumeratorClass -gck_enumerator_get_type -GckEnumeratorPrivate -GCK_ENUMERATOR -GCK_ENUMERATOR_CLASS -GCK_ENUMERATOR_GET_CLASS -GCK_IS_ENUMERATOR -GCK_IS_ENUMERATOR_CLASS -GCK_TYPE_ENUMERATOR -</SECTION> - -<SECTION> -<FILE>gck-password</FILE> -GckPassword -GckPasswordClass -gck_password_get_key -gck_password_get_module -gck_password_get_token -<SUBSECTION Private> -gck_password_get_type -GckPasswordPrivate -GCK_IS_PASSWORD -GCK_IS_PASSWORD_CLASS -GCK_PASSWORD -GCK_PASSWORD_CLASS -GCK_PASSWORD_GET_CLASS -GCK_TYPE_PASSWORD -</SECTION> - -<SECTION> -<FILE>gck-misc</FILE> -GckError -gck_list_ref_copy -gck_list_unref_free -gck_string_from_chars -gck_string_to_chars -gck_value_to_boolean -gck_value_to_ulong -GCK_INVALID -<SUBSECTION Private> -gck_get_error_quark -gck_error_get_quark -GCK_TYPE_LIST -gck_list_get_boxed_type -GCK_TYPE_ERROR -gck_error_get_type -</SECTION> - -<SECTION> -<FILE>gck-private</FILE> -<SUBSECTION Private> -GCK_URI_BAD_PREFIX -CKR_GCK_MODULE_PROBLEM -</SECTION> diff --git a/docs/reference/gck/gck.types b/docs/reference/gck/gck.types deleted file mode 100644 index a1a8375..0000000 --- a/docs/reference/gck/gck.types +++ /dev/null @@ -1,15 +0,0 @@ -gck_attributes_get_type -gck_builder_get_type -gck_module_info_get_type -gck_module_get_type -gck_enumerator_get_type -gck_slot_info_get_type -gck_token_info_get_type -gck_mechanism_info_get_type -gck_slot_get_type -gck_session_info_get_type -gck_session_get_type -gck_object_get_type -gck_object_cache_get_type -gck_password_get_type -gck_uri_data_get_type diff --git a/docs/reference/gck/meson.build b/docs/reference/gck/meson.build deleted file mode 100644 index 220d9db..0000000 --- a/docs/reference/gck/meson.build +++ /dev/null @@ -1,36 +0,0 @@ -version_xml = configure_file( - input: 'version.xml.in', - output: '@BASENAME@', - configuration: { 'VERSION': gck_version }, -) - -gck_docs_ignore_headers = [ - 'gck-private.h', - 'test-suite.h', - 'gck-mock.h', - 'gck-test.h', - 'pkcs11-trust-assertions.h', - 'pkcs11.h', - 'pkcs11n.h', - 'pkcs11x.h', - 'pkcs11i.h', -] - -gnome.gtkdoc('gck', - main_sgml: 'gck-docs.sgml', - content_files: files( - 'gck-pkcs11-links.xml', - ), - src_dir: [ - include_directories('../../../gck'), - ], - ignore_headers: gck_docs_ignore_headers, - dependencies: gck_dep, - gobject_typesfile: 'gck.types', - scan_args: [ - '--rebuild-types', - '--deprecated-guards=GCK_DISABLE_DEPRECATED', - ], - install: true, -) - diff --git a/docs/reference/gck/version.xml.in b/docs/reference/gck/version.xml.in deleted file mode 100644 index 27323da..0000000 --- a/docs/reference/gck/version.xml.in +++ /dev/null @@ -1 +0,0 @@ -@VERSION@
\ No newline at end of file diff --git a/docs/reference/gcr/gcr-docs.sgml b/docs/reference/gcr/gcr-docs.sgml deleted file mode 100644 index 749bebe..0000000 --- a/docs/reference/gcr/gcr-docs.sgml +++ /dev/null @@ -1,81 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -<!ENTITY version SYSTEM "version.xml"> -]> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>Gcr Library Reference Manual</title> - <releaseinfo> - for Gcr &version;. - An online version of this documentation can be found at - <ulink role="online-location" url="http://developer.gnome.org/gcr/stable/">http://developer.gnome.org/gcr/stable/</ulink>. - </releaseinfo> - </bookinfo> - - <part id="certificates"> - <title>Certificates</title> - <xi:include href="xml/gcr-certificate.xml"/> - <xi:include href="xml/gcr-simple-certificate.xml"/> - <xi:include href="xml/gcr-pkcs11-certificate.xml"/> - <xi:include href="xml/gcr-certificate-chain.xml"/> - <xi:include href="xml/gcr-certificate-request.xml"/> - </part> - - <part id="collections"> - <title>Collections</title> - <xi:include href="xml/gcr-collection.xml"/> - <xi:include href="xml/gcr-comparable.xml"/> - <xi:include href="xml/gcr-simple-collection.xml"/> - <xi:include href="xml/gcr-collection-model.xml"/> - </part> - - <part id="widgets"> - <title>Widgets</title> - <xi:include href="xml/gcr-certificate-widget.xml"/> - <xi:include href="xml/gcr-key-widget.xml"/> - <xi:include href="xml/gcr-column.xml"/> - <xi:include href="xml/gcr-combo-selector.xml"/> - <xi:include href="xml/gcr-import-button.xml"/> - <xi:include href="xml/gcr-list-selector.xml"/> - <xi:include href="xml/gcr-tree-selector.xml"/> - <xi:include href="xml/gcr-renderer.xml"/> - <xi:include href="xml/gcr-viewer.xml"/> - <xi:include href="xml/gcr-viewer-widget.xml"/> - <chapter> - <title>Widget Gallery</title> - <xi:include href="gcr-visual-index.xml" /> - </chapter> - </part> - - <part id="prompts"> - <title>Prompting</title> - <xi:include href="xml/gcr-prompt.xml"/> - <xi:include href="xml/gcr-prompt-dialog.xml"/> - <xi:include href="xml/gcr-system-prompt.xml"/> - <xi:include href="xml/gcr-system-prompter.xml"/> - <xi:include href="xml/gcr-ssh-askpass.xml"/> - </part> - - <part id="storage"> - <title>Storage</title> - <xi:include href="xml/gcr-trust.xml"/> - <xi:include href="xml/gcr-importer.xml"/> - <xi:include href="xml/gcr-import-interaction.xml"/> - <xi:include href="xml/gcr-parser.xml"/> - </part> - - <part id="misc"> - <title>Miscellaneous</title> - <xi:include href="xml/gcr-library.xml"/> - <xi:include href="xml/gcr-pkcs11.xml"/> - <xi:include href="xml/gcr-fingerprint.xml"/> - <xi:include href="xml/gcr-secret-exchange.xml"/> - <xi:include href="xml/gcr-secure-memory.xml"/> - <xi:include href="xml/gcr-secure-entry-buffer.xml"/> - </part> - - <xi:include href="xml/annotation-glossary.xml"> - <xi:fallback /> - </xi:include> -</book> diff --git a/docs/reference/gcr/gcr-overrides.txt b/docs/reference/gcr/gcr-overrides.txt deleted file mode 100644 index 13f485f..0000000 --- a/docs/reference/gcr/gcr-overrides.txt +++ /dev/null @@ -1,2 +0,0 @@ -# These are manually-edited to override or add declarations to those scanned -# from the header files. diff --git a/docs/reference/gcr/gcr-sections.txt b/docs/reference/gcr/gcr-sections.txt deleted file mode 100644 index de171dd..0000000 --- a/docs/reference/gcr/gcr-sections.txt +++ /dev/null @@ -1,899 +0,0 @@ -<SECTION> -<TITLE>Library Utilities</TITLE> -<FILE>gcr-library</FILE> -GCR_CHECK_VERSION -GCR_MAJOR_VERSION -GCR_MICRO_VERSION -GCR_MINOR_VERSION -</SECTION> - -<SECTION> -<FILE>gcr-parser</FILE> -<TITLE>GcrParser</TITLE> -GCR_DATA_ERROR -GcrDataError -GcrDataFormat -GcrParser -GcrParserClass -gcr_parser_new -gcr_parser_parse_bytes -gcr_parser_parse_data -gcr_parser_parse_stream -gcr_parser_parse_stream_async -gcr_parser_parse_stream_finish -gcr_parser_format_enable -gcr_parser_format_disable -gcr_parser_format_supported -gcr_parser_add_password -gcr_parser_get_parsed_label -gcr_parser_get_parsed_description -gcr_parser_get_parsed_attributes -gcr_parser_get_parsed_block -gcr_parser_get_parsed_bytes -gcr_parser_get_parsed_format -gcr_parser_get_filename -gcr_parser_set_filename -GcrParsed -gcr_parsed_ref -gcr_parsed_unref -gcr_parsed_get_attributes -gcr_parsed_get_data -gcr_parsed_get_bytes -gcr_parsed_get_description -gcr_parsed_get_format -gcr_parsed_get_label -gcr_parser_get_parsed -gcr_parsed_get_filename -<SUBSECTION Standard> -GCR_TYPE_PARSED -GcrParserPrivate -gcr_parsed_get_type -GCR_PARSER -GCR_IS_PARSER -GCR_TYPE_PARSER -gcr_parser_get_type -GCR_PARSER_CLASS -GCR_IS_PARSER_CLASS -GCR_PARSER_GET_CLASS -GCK_API_SUBJECT_TO_CHANGE -gcr_data_error_get_domain -GCR_TYPE_DATA_ERROR -GCR_TYPE_DATA_FORMAT -gcr_data_error_get_type -gcr_data_format_get_type -</SECTION> - -<SECTION> -<FILE>gcr-certificate</FILE> -GcrCertificate -GcrCertificateIface -gcr_certificate_get_der_data -gcr_certificate_get_issuer_cn -gcr_certificate_get_issuer_dn -gcr_certificate_get_issuer_name -gcr_certificate_get_issuer_part -gcr_certificate_get_issuer_raw -gcr_certificate_is_issuer -gcr_certificate_get_subject_cn -gcr_certificate_get_subject_dn -gcr_certificate_get_subject_name -gcr_certificate_get_subject_part -gcr_certificate_get_subject_raw -gcr_certificate_get_issued_date -gcr_certificate_get_expiry_date -gcr_certificate_get_serial_number -gcr_certificate_get_serial_number_hex -gcr_certificate_get_key_size -gcr_certificate_get_fingerprint -gcr_certificate_get_fingerprint_hex -gcr_certificate_get_basic_constraints -gcr_certificate_mixin_class_init -gcr_certificate_mixin_emit_notify -gcr_certificate_mixin_get_property -GCR_CERTIFICATE_MIXIN_IMPLEMENT_COMPARABLE -gcr_certificate_mixin_comparable_init -gcr_certificate_compare -gcr_certificate_get_icon -gcr_certificate_get_markup_text -<SUBSECTION Standard> -gcr_certificate_get_columns -GCR_CERTIFICATE -GCR_IS_CERTIFICATE -GCR_TYPE_CERTIFICATE -GCR_CERTIFICATE_GET_INTERFACE -gcr_certificate_get_type -<SUBSECTION Private> -GcrCertificateExtensionKeyUsage -GcrGeneralName -GcrGeneralNameType -</SECTION> - -<SECTION> -<FILE>gcr-certificate-request</FILE> -GcrCertificateRequest -GcrCertificateRequestFormat -gcr_certificate_request_capable -gcr_certificate_request_capable_async -gcr_certificate_request_capable_finish -gcr_certificate_request_prepare -gcr_certificate_request_get_format -gcr_certificate_request_get_private_key -gcr_certificate_request_set_cn -gcr_certificate_request_complete -gcr_certificate_request_complete_async -gcr_certificate_request_complete_finish -gcr_certificate_request_encode -<SUBSECTION Private> -GCR_CERTIFICATE_REQUEST -GCR_IS_CERTIFICATE_REQUEST -GCR_TYPE_CERTIFICATE_REQUEST -GCR_TYPE_CERTIFICATE_REQUEST_FORMAT -gcr_certificate_request_get_type -gcr_certificate_request_format_get_type -</SECTION> - -<SECTION> -<FILE>gcr-importer</FILE> -GcrImporter -GcrImporterIface -gcr_importer_get_interaction -gcr_importer_set_interaction -gcr_importer_import -gcr_importer_import_async -gcr_importer_import_finish -gcr_importer_register -gcr_importer_register_well_known -gcr_importer_create_for_parsed -gcr_importer_queue_for_parsed -gcr_importer_queue_and_filter_for_parsed -<SUBSECTION Standard> -GCR_IMPORTER -GCR_IS_IMPORTER -GCR_TYPE_IMPORTER -gcr_importer_get_type -GCR_IMPORTER_GET_INTERFACE -GCR_IMPORT_INTERACTION -GCR_IMPORT_INTERACTION_GET_INTERFACE -GCR_IS_IMPORT_INTERACTION -GCR_TYPE_IMPORT_INTERACTION -GcrImportInteraction -GcrImportInteractionIface -gcr_import_interaction_get_type -</SECTION> - -<SECTION> -<FILE>gcr-import-interaction</FILE> -GcrImportInteraction -GcrImportInteractionIface -gcr_import_interaction_supplement_prep -gcr_import_interaction_supplement -gcr_import_interaction_supplement_async -gcr_import_interaction_supplement_finish -</SECTION> - -<SECTION> -<FILE>gcr-import-button</FILE> -GcrImportButton -GcrImportButtonClass -gcr_import_button_new -gcr_import_button_add_parsed -<SUBSECTION Standard> -GCR_IMPORT_BUTTON -GCR_IMPORT_BUTTON_CLASS -GCR_IMPORT_BUTTON_GET_CLASS -GCR_IS_IMPORT_BUTTON -GCR_IS_IMPORT_BUTTON_CLASS -gcr_import_button_get_type -GCR_TYPE_IMPORT_BUTTON -<SUBSECTION Private> -GcrImportButtonPrivate -</SECTION> - -<SECTION> -<FILE>gcr-simple-certificate</FILE> -<TITLE>GcrSimpleCertificate</TITLE> -GcrSimpleCertificate -GcrSimpleCertificateClass -gcr_simple_certificate_new -gcr_simple_certificate_new_static -<SUBSECTION Standard> -GcrSimpleCertificatePrivate -GCR_SIMPLE_CERTIFICATE -GCR_IS_SIMPLE_CERTIFICATE -GCR_TYPE_SIMPLE_CERTIFICATE -gcr_simple_certificate_get_type -GCR_SIMPLE_CERTIFICATE_CLASS -GCR_IS_SIMPLE_CERTIFICATE_CLASS -GCR_SIMPLE_CERTIFICATE_GET_CLASS -</SECTION> - -<SECTION> -<FILE>gcr-pkcs11-certificate</FILE> -<TITLE>GcrPkcs11Certificate</TITLE> -GcrPkcs11Certificate -GcrPkcs11CertificateClass -gcr_pkcs11_certificate_lookup_issuer -gcr_pkcs11_certificate_lookup_issuer_async -gcr_pkcs11_certificate_lookup_issuer_finish -gcr_pkcs11_certificate_get_attributes -<SUBSECTION Standard> -gcr_pkcs11_certificate_get_type -GCR_IS_PKCS11_CERTIFICATE -GCR_IS_PKCS11_CERTIFICATE_CLASS -GcrPkcs11CertificatePrivate -GCR_PKCS11_CERTIFICATE -GCR_PKCS11_CERTIFICATE_CLASS -GCR_PKCS11_CERTIFICATE_GET_CLASS -GCR_TYPE_PKCS11_CERTIFICATE -</SECTION> - -<SECTION> -<FILE>gcr-trust</FILE> -GCR_PURPOSE_SERVER_AUTH -GCR_PURPOSE_CLIENT_AUTH -GCR_PURPOSE_EMAIL -GCR_PURPOSE_CODE_SIGNING -gcr_trust_is_certificate_anchored -gcr_trust_is_certificate_anchored_async -gcr_trust_is_certificate_anchored_finish -gcr_trust_is_certificate_pinned -gcr_trust_is_certificate_pinned_async -gcr_trust_is_certificate_pinned_finish -gcr_trust_add_pinned_certificate -gcr_trust_add_pinned_certificate_async -gcr_trust_add_pinned_certificate_finish -gcr_trust_remove_pinned_certificate -gcr_trust_remove_pinned_certificate_async -gcr_trust_remove_pinned_certificate_finish -</SECTION> - -<SECTION> -<FILE>gcr-pkcs11</FILE> -gcr_pkcs11_initialize -gcr_pkcs11_initialize_async -gcr_pkcs11_initialize_finish -gcr_pkcs11_get_modules -gcr_pkcs11_set_modules -gcr_pkcs11_add_module -gcr_pkcs11_add_module_from_file -gcr_pkcs11_get_trust_lookup_slots -gcr_pkcs11_get_trust_store_slot -gcr_pkcs11_get_trust_lookup_uris -gcr_pkcs11_set_trust_lookup_uris -gcr_pkcs11_get_trust_store_uri -gcr_pkcs11_set_trust_store_uri -</SECTION> - -<SECTION> -<FILE>gcr-certificate-chain</FILE> -GcrCertificateChain -GcrCertificateChainClass -GcrCertificateChainStatus -gcr_certificate_chain_new -gcr_certificate_chain_add -gcr_certificate_chain_get_certificate -gcr_certificate_chain_get_status -gcr_certificate_chain_get_anchor -gcr_certificate_chain_get_endpoint -gcr_certificate_chain_get_length -GcrCertificateChainFlags -gcr_certificate_chain_build -gcr_certificate_chain_build_async -gcr_certificate_chain_build_finish -GCR_TYPE_CERTIFICATE_CHAIN_FLAGS -GCR_TYPE_CERTIFICATE_CHAIN_STATUS -<SUBSECTION Standard> -gcr_certificate_chain_flags_get_type -gcr_certificate_chain_status_get_type -gcr_certificate_chain_get_type -GCR_CERTIFICATE_CHAIN -GCR_TYPE_CERTIFICATE_CHAIN -GCR_CERTIFICATE_CHAIN_CLASS -GCR_CERTIFICATE_CHAIN_GET_CLASS -GCR_IS_CERTIFICATE_CHAIN -GCR_IS_CERTIFICATE_CHAIN_CLASS -GcrCertificateChainPrivate -</SECTION> - -<SECTION> -<FILE>gcr-comparable</FILE> -GcrComparable -GcrComparableIface -gcr_comparable_compare -gcr_comparable_memcmp -<SUBSECTION Standard> -gcr_comparable_get_type -GCR_COMPARABLE -GCR_COMPARABLE_GET_INTERFACE -GCR_IS_COMPARABLE -GCR_TYPE_COMPARABLE -</SECTION> - -<SECTION> -<FILE>gcr-collection</FILE> -GcrCollection -gcr_collection_get_length -gcr_collection_get_objects -gcr_collection_contains -gcr_collection_emit_added -gcr_collection_emit_removed -<SUBSECTION Standard> -gcr_collection_get_type -GCR_COLLECTION -GCR_COLLECTION_GET_INTERFACE -GCR_IS_COLLECTION -GCR_TYPE_COLLECTION -GcrCollectionIface -</SECTION> - -<SECTION> -<FILE>gcr-simple-collection</FILE> -GcrSimpleCollection -GcrSimpleCollectionClass -gcr_simple_collection_new -gcr_simple_collection_add -gcr_simple_collection_remove -<SUBSECTION Standard> -gcr_simple_collection_get_type -GCR_IS_SIMPLE_COLLECTION -GCR_IS_SIMPLE_COLLECTION_CLASS -GCR_SIMPLE_COLLECTION -GCR_SIMPLE_COLLECTION_CLASS -GCR_SIMPLE_COLLECTION_GET_CLASS -GCR_TYPE_SIMPLE_COLLECTION -GcrSimpleCollectionPrivate -</SECTION> - -<SECTION> -<FILE>gcr-filter-collection</FILE> -GcrFilterCollection -GcrFilterCollectionClass -GcrFilterCollectionFunc -gcr_filter_collection_new_with_callback -gcr_filter_collection_set_callback -gcr_filter_collection_get_underlying -gcr_filter_collection_refilter -<SUBSECTION Standard> -gcr_filter_collection_get_type -GCR_FILTER_COLLECTION -GCR_FILTER_COLLECTION_CLASS -GCR_FILTER_COLLECTION_GET_CLASS -GCR_IS_FILTER_COLLECTION -GCR_IS_FILTER_COLLECTION_CLASS -GCR_TYPE_FILTER_COLLECTION -<SUBSECTION Private> -GcrFilterCollectionPrivate -</SECTION> - -<SECTION> -<FILE>gcr-union-collection</FILE> -GcrUnionCollection -GcrUnionCollectionClass -gcr_union_collection_new -gcr_union_collection_add -gcr_union_collection_take -gcr_union_collection_remove -gcr_union_collection_have -gcr_union_collection_size -gcr_union_collection_elements -<SUBSECTION Standard> -GCR_IS_UNION_COLLECTION -GCR_IS_UNION_COLLECTION_CLASS -GCR_TYPE_UNION_COLLECTION -GCR_UNION_COLLECTION -GCR_UNION_COLLECTION_CLASS -GCR_UNION_COLLECTION_GET_CLASS -GcrUnionCollectionPrivate -gcr_union_collection_get_type -</SECTION> - -<SECTION> -<FILE>gcr-collection-model</FILE> -GcrCollectionModel -GcrCollectionModelClass -GcrCollectionModelMode -gcr_collection_model_new -gcr_collection_model_new_full -gcr_collection_model_set_columns -gcr_collection_model_get_collection -gcr_collection_model_set_collection -gcr_collection_model_iter_for_object -gcr_collection_model_object_for_iter -gcr_collection_model_is_selected -gcr_collection_model_change_selected -gcr_collection_model_toggle_selected -gcr_collection_model_get_selected_objects -gcr_collection_model_set_selected_objects -gcr_collection_model_column_for_selected -<SUBSECTION Standard> -gcr_collection_model_get_type -GCR_COLLECTION_MODEL -GCR_COLLECTION_MODEL_CLASS -GCR_COLLECTION_MODEL_GET_CLASS -GCR_IS_COLLECTION_MODEL -GCR_IS_COLLECTION_MODEL_CLASS -GCR_TYPE_COLLECTION_MODEL -GCR_TYPE_COLLECTION_MODEL_MODE -gcr_collection_model_mode_get_type -<SUBSECTION Private> -GcrCollectionModelPrivate -</SECTION> - -<SECTION> -<FILE>gcr-column</FILE> -GcrColumn -GcrColumnFlags -<SUBSECTION Standard> -GCR_TYPE_COLUMN_FLAGS -gcr_column_flags_get_type -</SECTION> - -<SECTION> -<FILE>gcr-tree-selector</FILE> -GcrTreeSelector -GcrTreeSelectorClass -gcr_tree_selector_get_collection -gcr_tree_selector_get_columns -gcr_tree_selector_new -gcr_tree_selector_get_selected -gcr_tree_selector_set_selected -<SUBSECTION Standard> -gcr_tree_selector_get_type -GCR_IS_TREE_SELECTOR -GCR_IS_TREE_SELECTOR_CLASS -GCR_TREE_SELECTOR -GCR_TREE_SELECTOR_CLASS -GCR_TREE_SELECTOR_GET_CLASS -GCR_TYPE_TREE_SELECTOR -GcrTreeSelectorPrivate -</SECTION> - -<SECTION> -<FILE>gcr-list-selector</FILE> -GcrListSelector -GcrListSelectorClass -gcr_list_selector_new -gcr_list_selector_get_collection -gcr_list_selector_get_selected -gcr_list_selector_set_selected -<SUBSECTION Standard> -gcr_list_selector_get_type -GcrListSelectorPrivate -GCR_IS_LIST_SELECTOR -GCR_IS_LIST_SELECTOR_CLASS -GCR_LIST_SELECTOR -GCR_LIST_SELECTOR_CLASS -GCR_LIST_SELECTOR_GET_CLASS -GCR_TYPE_LIST_SELECTOR -</SECTION> - -<SECTION> -<FILE>gcr-combo-selector</FILE> -GcrComboSelector -GcrComboSelectorClass -gcr_combo_selector_get_collection -gcr_combo_selector_new -gcr_combo_selector_get_selected -gcr_combo_selector_set_selected -<SUBSECTION Standard> -gcr_combo_selector_get_type -GCR_IS_COMBO_SELECTOR -GCR_IS_COMBO_SELECTOR_CLASS -GCR_COMBO_SELECTOR -GCR_COMBO_SELECTOR_CLASS -GCR_COMBO_SELECTOR_GET_CLASS -GCR_TYPE_COMBO_SELECTOR -GcrComboSelectorPrivate -</SECTION> - -<SECTION> -<FILE>gcr-renderer</FILE> -GcrRenderer -GcrRendererIface -gcr_renderer_create -gcr_renderer_register -gcr_renderer_get_attributes -gcr_renderer_set_attributes -gcr_renderer_popuplate_popup -gcr_renderer_render_view -gcr_renderer_emit_data_changed -gcr_renderer_register_well_known -<SUBSECTION Standard> -gcr_renderer_get_type -GCR_IS_RENDERER -GCR_RENDERER -GCR_RENDERER_GET_INTERFACE -GCR_TYPE_RENDERER -</SECTION> - -<SECTION> -<FILE>gcr-viewer</FILE> -GcrViewer -GcrViewerIface -gcr_viewer_new -gcr_viewer_new_scrolled -gcr_viewer_add_renderer -gcr_viewer_insert_renderer -gcr_viewer_remove_renderer -gcr_viewer_count_renderers -gcr_viewer_get_renderer -<SUBSECTION Standard> -gcr_viewer_get_type -GCR_IS_VIEWER -GCR_TYPE_VIEWER -GCR_VIEWER -GCR_VIEWER_GET_INTERFACE -</SECTION> - -<SECTION> -<FILE>gcr-certificate-widget</FILE> -GCR_CERTIFICATE_COLUMNS -GcrCertificateWidget -GcrCertificateWidgetClass -GcrCertificateRenderer -GcrCertificateRendererClass -gcr_certificate_widget_new -gcr_certificate_widget_get_certificate -gcr_certificate_widget_set_certificate -gcr_certificate_renderer_new -gcr_certificate_renderer_new_for_attributes -gcr_certificate_renderer_get_certificate -gcr_certificate_renderer_set_certificate -<SUBSECTION Standard> -gcr_certificate_widget_get_type -GCR_CERTIFICATE_RENDERER -GCR_CERTIFICATE_RENDERER_CLASS -GCR_CERTIFICATE_RENDERER_GET_CLASS -GCR_IS_CERTIFICATE_RENDERER -GCR_IS_CERTIFICATE_RENDERER_CLASS -GCR_CERTIFICATE_WIDGET -GCR_CERTIFICATE_WIDGET_CLASS -GCR_CERTIFICATE_WIDGET_GET_CLASS -GCR_IS_CERTIFICATE_WIDGET -GCR_IS_CERTIFICATE_WIDGET_CLASS -GCR_TYPE_CERTIFICATE_RENDERER -GCR_TYPE_CERTIFICATE_WIDGET -GcrCertificateRendererPrivate -GcrCertificateWidgetPrivate -gcr_certificate_renderer_get_type -</SECTION> - -<SECTION> -<FILE>gcr-key-widget</FILE> -GcrKeyWidget -GcrKeyWidgetClass -GcrKeyRenderer -GcrKeyRendererClass -gcr_key_widget_new -gcr_key_widget_get_attributes -gcr_key_widget_set_attributes -gcr_key_renderer_new -gcr_key_renderer_get_attributes -gcr_key_renderer_set_attributes -<SUBSECTION Standard> -gcr_key_renderer_get_type -gcr_key_widget_get_type -GCR_IS_KEY_RENDERER -GCR_IS_KEY_RENDERER_CLASS -GCR_IS_KEY_WIDGET -GCR_IS_KEY_WIDGET_CLASS -GCR_KEY_RENDERER -GCR_KEY_RENDERER_CLASS -GCR_KEY_RENDERER_GET_CLASS -GCR_KEY_WIDGET -GCR_KEY_WIDGET_CLASS -GCR_KEY_WIDGET_GET_CLASS -GCR_TYPE_KEY_RENDERER -GCR_TYPE_KEY_WIDGET -GcrKeyRendererPrivate -GcrKeyWidgetPrivate -</SECTION> - -<SECTION> -<FILE>gcr-unlock-options-widget</FILE> -GcrUnlockOptionsWidget -GcrUnlockOptionsWidgetClass -GCR_UNLOCK_OPTION_ALWAYS -GCR_UNLOCK_OPTION_IDLE -GCR_UNLOCK_OPTION_SESSION -GCR_UNLOCK_OPTION_TIMEOUT -gcr_unlock_options_widget_new -gcr_unlock_options_widget_get_choice -gcr_unlock_options_widget_set_choice -gcr_unlock_options_widget_get_label -gcr_unlock_options_widget_set_label -gcr_unlock_options_widget_get_ttl -gcr_unlock_options_widget_set_ttl -gcr_unlock_options_widget_get_sensitive -gcr_unlock_options_widget_set_sensitive -<SUBSECTION Standard> -gcr_unlock_options_widget_get_type -GCR_IS_UNLOCK_OPTIONS_WIDGET -GCR_IS_UNLOCK_OPTIONS_WIDGET_CLASS -GCR_TYPE_UNLOCK_OPTIONS_WIDGET -GCR_UNLOCK_OPTIONS_WIDGET -GCR_UNLOCK_OPTIONS_WIDGET_CLASS -GCR_UNLOCK_OPTIONS_WIDGET_GET_CLASS -GcrUnlockOptionsWidgetPrivate -</SECTION> - -<SECTION> -<FILE>gcr-viewer-widget</FILE> -GcrViewerWidget -gcr_viewer_widget_new -gcr_viewer_widget_load_bytes -gcr_viewer_widget_load_data -gcr_viewer_widget_load_file -gcr_viewer_widget_get_parser -gcr_viewer_widget_get_viewer -gcr_viewer_widget_show_error -gcr_viewer_widget_clear_error -gcr_viewer_widget_get_display_name -gcr_viewer_widget_set_display_name -<SUBSECTION Standard> -gcr_viewer_widget_get_type -GCR_TYPE_VIEWER_WIDGET -GCR_IS_VIEWER_WIDGET -GCR_VIEWER_WIDGET -</SECTION> - -<SECTION> -<FILE>gcr-secret-exchange</FILE> -GcrSecretExchange -GcrSecretExchangeClass -GCR_SECRET_EXCHANGE_PROTOCOL_1 -gcr_secret_exchange_new -gcr_secret_exchange_begin -gcr_secret_exchange_receive -gcr_secret_exchange_get_protocol -gcr_secret_exchange_get_secret -gcr_secret_exchange_send -<SUBSECTION Standard> -gcr_secret_exchange_get_type -GCR_IS_SECRET_EXCHANGE -GCR_IS_SECRET_EXCHANGE_CLASS -GCR_SECRET_EXCHANGE -GCR_SECRET_EXCHANGE_CLASS -GCR_SECRET_EXCHANGE_GET_CLASS -GCR_TYPE_SECRET_EXCHANGE -GcrSecretExchangePrivate -</SECTION> - -<SECTION> -<FILE>gcr-fingerprint</FILE> -gcr_fingerprint_from_attributes -gcr_fingerprint_from_subject_public_key_info -</SECTION> - -<SECTION> -<FILE>gcr-secure-entry-buffer</FILE> -GcrSecureEntryBuffer -GcrSecureEntryBufferClass -gcr_secure_entry_buffer_new -<SUBSECTION Standard> -gcr_secure_entry_buffer_get_type -GCR_IS_SECURE_ENTRY_BUFFER -GCR_IS_SECURE_ENTRY_BUFFER_CLASS -GCR_SECURE_ENTRY_BUFFER -GCR_SECURE_ENTRY_BUFFER_CLASS -GCR_SECURE_ENTRY_BUFFER_GET_CLASS -GCR_TYPE_SECURE_ENTRY_BUFFER -<SUBSECTION Private> -GcrSecureEntryBufferPrivate -</SECTION> - -<SECTION> -<FILE>gcr-secure-memory</FILE> -gcr_secure_memory_new -gcr_secure_memory_alloc -gcr_secure_memory_try_alloc -gcr_secure_memory_realloc -gcr_secure_memory_try_realloc -gcr_secure_memory_strdup -gcr_secure_memory_strfree -gcr_secure_memory_free -gcr_secure_memory_is_secure -</SECTION> - -<SECTION> -<FILE>gcr-ssh-askpass</FILE> -GcrSshAskpass -gcr_ssh_askpass_new -gcr_ssh_askpass_get_interaction -gcr_ssh_askpass_child_setup -<SUBSECTION Standard> -GCR_IS_SSH_ASKPASS -GCR_IS_SSH_ASKPASS_CLASS -GCR_SSH_ASKPASS -GCR_SSH_ASKPASS_CLASS -GCR_SSH_ASKPASS_GET_CLASS -GCR_TYPE_SSH_ASKPASS -GcrSshAskpassClass -gcr_ssh_askpass_get_type -</SECTION> - -<SECTION> -<FILE>gcr-private</FILE> -<SUBSECTION Private> -GCR_GNUPG_COLLECTION -GCR_GNUPG_COLLECTION_CLASS -GCR_GNUPG_COLLECTION_GET_CLASS -GCR_GNUPG_KEY -GCR_GNUPG_KEY_CLASS -GCR_GNUPG_KEY_COLUMNS -GCR_GNUPG_KEY_GET_CLASS -GCR_IS_GNUPG_COLLECTION -GCR_IS_GNUPG_COLLECTION_CLASS -GCR_IS_GNUPG_KEY -GCR_IS_GNUPG_KEY_CLASS -GCR_TYPE_GNUPG_COLLECTION -GCR_TYPE_GNUPG_KEY -GCR_GNUPG_PROCESS -GCR_GNUPG_PROCESS_CLASS -GCR_GNUPG_PROCESS_GET_CLASS -GCR_IS_GNUPG_PROCESS -GCR_IS_GNUPG_PROCESS_CLASS -GCR_TYPE_GNUPG_PROCESS -GcrGnupgProcess -GcrGnupgProcessClass -GcrGnupgProcessPrivate -GcrGnupgProcessFlags -GcrGnupgCollection -GcrGnupgCollectionClass -GcrGnupgCollectionPrivate -GcrGnupgKey -GcrGnupgKeyClass -GcrGnupgKeyPrivate -GcrLineCallback -GCR_IS_MEMORY_ICON -GCR_IS_MEMORY_ICON_CLASS -GCR_MEMORY_ICON -GCR_MEMORY_ICON_CLASS -GCR_MEMORY_ICON_COLUMNS -GCR_MEMORY_ICON_GET_CLASS -GCR_TYPE_MEMORY_ICON -GcrMemoryIcon -GcrMemoryIconClass -GcrMemoryIconPrivate -GcrOpensshPubCallback -GCR_TYPE_IMPORTER_PROMPT_BEHAVIOR -gcr_importer_prompt_behavior_get_type -</SECTION> - -<SECTION> -<FILE>gcr-prompt</FILE> -GcrPrompt -GcrPromptIface -GcrPromptReply -gcr_prompt_password -gcr_prompt_password_async -gcr_prompt_password_finish -gcr_prompt_password_run -gcr_prompt_confirm -gcr_prompt_confirm_async -gcr_prompt_confirm_finish -gcr_prompt_confirm_run -gcr_prompt_reset -gcr_prompt_close -gcr_prompt_get_title -gcr_prompt_set_title -gcr_prompt_get_message -gcr_prompt_set_message -gcr_prompt_get_description -gcr_prompt_set_description -gcr_prompt_get_warning -gcr_prompt_set_warning -gcr_prompt_get_continue_label -gcr_prompt_set_continue_label -gcr_prompt_get_cancel_label -gcr_prompt_set_cancel_label -gcr_prompt_get_choice_label -gcr_prompt_set_choice_label -gcr_prompt_get_choice_chosen -gcr_prompt_set_choice_chosen -gcr_prompt_get_password_new -gcr_prompt_set_password_new -gcr_prompt_get_password_strength -gcr_prompt_get_caller_window -gcr_prompt_set_caller_window -<SUBSECTION Private> -gcr_prompt_get_type -gcr_prompt_reply_get_type -GCR_IS_PROMPT -GCR_PROMPT -GCR_PROMPT_GET_INTERFACE -GCR_TYPE_PROMPT -GCR_TYPE_PROMPT_REPLY -</SECTION> - -<SECTION> -<FILE>gcr-prompt-dialog</FILE> -GcrPromptDialog -GcrPromptDialogClass -<SUBSECTION Private> -GcrPromptDialogPrivate -gcr_prompt_dialog_get_type -GCR_IS_PROMPT_DIALOG -GCR_IS_PROMPT_DIALOG_CLASS -GCR_PROMPT_DIALOG -GCR_PROMPT_DIALOG_CLASS -GCR_PROMPT_DIALOG_GET_CLASS -GCR_TYPE_PROMPT_DIALOG -</SECTION> - -<SECTION> -<FILE>gcr-system-prompt</FILE> -GcrSystemPrompt -GcrSystemPromptClass -GCR_SYSTEM_PROMPT_ERROR -GcrSystemPromptError -gcr_system_prompt_open -gcr_system_prompt_open_async -gcr_system_prompt_open_finish -gcr_system_prompt_open_for_prompter -gcr_system_prompt_open_for_prompter_async -gcr_system_prompt_get_secret_exchange -gcr_system_prompt_close -gcr_system_prompt_close_async -gcr_system_prompt_close_finish -<SUBSECTION Private> -GcrSystemPromptPrivate -gcr_system_prompt_error_get_domain -gcr_system_prompt_error_get_type -gcr_system_prompt_get_type -GCR_IS_SYSTEM_PROMPT -GCR_IS_SYSTEM_PROMPT_CLASS -GCR_SYSTEM_PROMPT -GCR_SYSTEM_PROMPT_CLASS -GCR_SYSTEM_PROMPT_GET_CLASS -GCR_TYPE_SYSTEM_PROMPT -GCR_TYPE_SYSTEM_PROMPT_ERROR -</SECTION> - -<SECTION> -<FILE>gcr-system-prompter</FILE> -GcrSystemPrompter -GcrSystemPrompterClass -GcrSystemPrompterMode -gcr_system_prompter_new -gcr_system_prompter_register -gcr_system_prompter_unregister -gcr_system_prompter_get_mode -gcr_system_prompter_get_prompt_type -gcr_system_prompter_get_prompting -<SUBSECTION Private> -GcrSystemPrompterPrivate -gcr_system_prompter_get_type -gcr_system_prompter_mode_get_type -GCR_IS_SYSTEM_PROMPTER -GCR_IS_SYSTEM_PROMPTER_CLASS -GCR_SYSTEM_PROMPTER -GCR_SYSTEM_PROMPTER_CLASS -GCR_SYSTEM_PROMPTER_GET_CLASS -GCR_TYPE_SYSTEM_PROMPTER -GCR_TYPE_SYSTEM_PROMPTER_MODE -</SECTION> - -<SECTION> -<FILE>gcr-mock-prompter</FILE> -gcr_mock_prompter_start -gcr_mock_prompter_stop -gcr_mock_prompter_disconnect -gcr_mock_prompter_expect_confirm_cancel -gcr_mock_prompter_expect_confirm_ok -gcr_mock_prompter_expect_password_cancel -gcr_mock_prompter_expect_password_ok -gcr_mock_prompter_expect_close -gcr_mock_prompter_get_delay_msec -gcr_mock_prompter_set_delay_msec -gcr_mock_prompter_is_expecting -gcr_mock_prompter_is_prompting -</SECTION> - -<SECTION> -<FILE>GcrDBusPrompter</FILE> -</SECTION> - -<SECTION> -<FILE>GcrDBusPrompterCallback</FILE> -</SECTION> diff --git a/docs/reference/gcr/gcr-shooter.c b/docs/reference/gcr/gcr-shooter.c deleted file mode 100644 index 0ae3827..0000000 --- a/docs/reference/gcr/gcr-shooter.c +++ /dev/null @@ -1,466 +0,0 @@ - -#include "gcr-shooter.h" - -#include <gdk/gdk.h> -#include <gtk/gtk.h> -#include <gdk/gdkx.h> -#include <stdio.h> -#include <errno.h> -#include <sys/wait.h> -#include <unistd.h> -#include <X11/extensions/shape.h> - -#include <gdk-pixbuf/gdk-pixbuf.h> -#include <sys/types.h> -#include <sys/stat.h> -#include <sys/wait.h> -#include <signal.h> -#include <unistd.h> -#include <stdlib.h> -#include <fcntl.h> -#include <errno.h> -#include <locale.h> -#include <math.h> - -#define MAXIMUM_WM_REPARENTING_DEPTH 4 - -#define SMALL_WIDTH 240 -#define SMALL_HEIGHT 75 -#define MEDIUM_WIDTH 240 -#define MEDIUM_HEIGHT 165 -#define LARGE_WIDTH 240 -#define LARGE_HEIGHT 240 - -static Window -find_toplevel_window (Window xid) -{ - Window root, parent, *children; - guint nchildren; - - do { - if (XQueryTree (GDK_DISPLAY_XDISPLAY (gdk_display_get_default ()), xid, &root, - &parent, &children, &nchildren) == 0) { - g_warning ("Couldn't find window manager window"); - return None; - } - - if (root == parent) - return xid; - - xid = parent; - } while (TRUE); -} - - -static gboolean -adjust_size_callback (GcrShooterInfo *info) -{ - Window toplevel; - Window root; - GdkWindow *window; - gint tx; - gint ty; - guint twidth; - guint theight; - guint tborder_width; - guint tdepth; - gint target_width = 0; - gint target_height = 0; - - window = gtk_widget_get_window (info->window); - toplevel = find_toplevel_window (GDK_WINDOW_XID (window)); - XGetGeometry (GDK_WINDOW_XDISPLAY (window), toplevel, - &root, &tx, &ty, &twidth, &theight, &tborder_width, &tdepth); - - switch (info->size) { - case GCR_SHOOTER_SMALL: - target_width = SMALL_WIDTH; - target_height = SMALL_HEIGHT; - break; - case GCR_SHOOTER_MEDIUM: - target_width = MEDIUM_WIDTH; - target_height = MEDIUM_HEIGHT; - break; - case GCR_SHOOTER_LARGE: - target_width = LARGE_WIDTH; - target_height = LARGE_HEIGHT; - break; - case GCR_SHOOTER_ASIS: - target_width = twidth; - target_height = theight; - break; - } - - if (twidth > target_width || theight > target_height) { - gtk_widget_set_size_request (info->window, - 2 + target_width - (twidth - target_width), /* Dunno why I need the +2 fudge factor; */ - 2 + target_height - (theight - target_height)); - } - return FALSE; -} - -static void -realize_callback (GtkWidget *widget, GcrShooterInfo *info) -{ - gdk_threads_add_timeout (500, (GSourceFunc)adjust_size_callback, info); -} - -GcrShooterInfo* -gcr_shooter_info_new (const gchar *name, GtkWidget *widget, GcrShooterSize size) -{ - GcrShooterInfo *info; - - info = g_new0 (GcrShooterInfo, 1); - info->name = g_strdup (name); - info->size = size; - if (GTK_IS_WINDOW (widget)) { - info->window = widget; - gtk_window_set_resizable (GTK_WINDOW (info->window), FALSE); - info->include_decorations = TRUE; - g_signal_connect (info->window, "realize", G_CALLBACK (realize_callback), info); - } else { - info->window = gtk_window_new (GTK_WINDOW_TOPLEVEL); - gtk_window_set_has_resize_grip (GTK_WINDOW (info->window), FALSE); - info->include_decorations = FALSE; - gtk_widget_show_all (widget); - gtk_container_add (GTK_CONTAINER (info->window), widget); - } - info->no_focus = TRUE; - - gtk_widget_set_app_paintable (info->window, TRUE); - g_signal_connect (info->window, "focus", G_CALLBACK (gtk_true), NULL); - gtk_container_set_border_width (GTK_CONTAINER (info->window), 12); - - switch (size) { - case GCR_SHOOTER_SMALL: - gtk_widget_set_size_request (info->window, 240, 75); - break; - case GCR_SHOOTER_MEDIUM: - gtk_widget_set_size_request (info->window, 240, 165); - break; - case GCR_SHOOTER_LARGE: - gtk_widget_set_size_request (info->window, 240, 240); - break; - default: - break; - } - - return info; -} - -#define BLUR_RADIUS 5 -#define SHADOW_OFFSET (BLUR_RADIUS * 4 / 5) -#define SHADOW_OPACITY 0.75 - -typedef struct { - int size; - double *data; -} ConvFilter; - -static double -gaussian (double x, double y, double r) -{ - return ((1 / (2 * M_PI * r)) * - exp ((- (x * x + y * y)) / (2 * r * r))); -} - -static ConvFilter * -create_blur_filter (int radius) -{ - ConvFilter *filter; - int x, y; - double sum; - - filter = g_new0 (ConvFilter, 1); - filter->size = radius * 2 + 1; - filter->data = g_new (double, filter->size * filter->size); - - sum = 0.0; - - for (y = 0 ; y < filter->size; y++) { - for (x = 0 ; x < filter->size; x++) { - sum += filter->data[y * filter->size + x] = gaussian (x - (filter->size >> 1), - y - (filter->size >> 1), - radius); - } - } - - for (y = 0; y < filter->size; y++) { - for (x = 0; x < filter->size; x++) { - filter->data[y * filter->size + x] /= sum; - } - } - - return filter; - -} - -static GdkPixbuf * -create_shadow (GdkPixbuf *src) -{ - int x, y, i, j; - int width, height; - GdkPixbuf *dest; - static ConvFilter *filter = NULL; - int src_rowstride, dest_rowstride; - int src_bpp, dest_bpp; - guchar *src_pixels, *dest_pixels; - - if (!filter) - filter = create_blur_filter (BLUR_RADIUS); - - width = gdk_pixbuf_get_width (src) + BLUR_RADIUS * 2 + SHADOW_OFFSET; - height = gdk_pixbuf_get_height (src) + BLUR_RADIUS * 2 + SHADOW_OFFSET; - - dest = gdk_pixbuf_new (gdk_pixbuf_get_colorspace (src), - gdk_pixbuf_get_has_alpha (src), - gdk_pixbuf_get_bits_per_sample (src), - width, height); - gdk_pixbuf_fill (dest, 0); - src_pixels = gdk_pixbuf_get_pixels (src); - src_rowstride = gdk_pixbuf_get_rowstride (src); - src_bpp = gdk_pixbuf_get_has_alpha (src) ? 4 : 3; - - dest_pixels = gdk_pixbuf_get_pixels (dest); - dest_rowstride = gdk_pixbuf_get_rowstride (dest); - dest_bpp = gdk_pixbuf_get_has_alpha (dest) ? 4 : 3; - - for (y = 0; y < height; y++) { - for (x = 0; x < width; x++) { - int sumr = 0, sumg = 0, sumb = 0, suma = 0; - - for (i = 0; i < filter->size; i++) { - for (j = 0; j < filter->size; j++) { - int src_x, src_y; - - src_y = -(BLUR_RADIUS + SHADOW_OFFSET) + y - (filter->size >> 1) + i; - src_x = -(BLUR_RADIUS + SHADOW_OFFSET) + x - (filter->size >> 1) + j; - - if (src_y < 0 || src_y > gdk_pixbuf_get_height (src) || - src_x < 0 || src_x > gdk_pixbuf_get_width (src)) - continue; - - sumr += src_pixels [src_y * src_rowstride + - src_x * src_bpp + 0] * - filter->data [i * filter->size + j]; - sumg += src_pixels [src_y * src_rowstride + - src_x * src_bpp + 1] * - filter->data [i * filter->size + j]; - - sumb += src_pixels [src_y * src_rowstride + - src_x * src_bpp + 2] * - filter->data [i * filter->size + j]; - - if (src_bpp == 4) - suma += src_pixels [src_y * src_rowstride + - src_x * src_bpp + 3] * - filter->data [i * filter->size + j]; - } - } - - if (dest_bpp == 4) - dest_pixels [y * dest_rowstride + - x * dest_bpp + 3] = suma * SHADOW_OPACITY; - } - } - - return dest; -} - -GdkPixbuf * -create_shadowed_pixbuf (GdkPixbuf *src) -{ - GdkPixbuf *dest; - - dest = create_shadow (src); - - gdk_pixbuf_composite (src, dest, - BLUR_RADIUS, BLUR_RADIUS, - gdk_pixbuf_get_width (src), - gdk_pixbuf_get_height (src), - BLUR_RADIUS, BLUR_RADIUS, 1.0, 1.0, - GDK_INTERP_NEAREST, 255); - return dest; -} -static GdkPixbuf * -add_border_to_shot (GdkPixbuf *pixbuf) -{ - GdkPixbuf *retval; - - retval = gdk_pixbuf_new (GDK_COLORSPACE_RGB, TRUE, 8, - gdk_pixbuf_get_width (pixbuf) + 2, - gdk_pixbuf_get_height (pixbuf) + 2); - - /* Fill with solid black */ - gdk_pixbuf_fill (retval, 0xFF); - gdk_pixbuf_copy_area (pixbuf, - 0, 0, - gdk_pixbuf_get_width (pixbuf), - gdk_pixbuf_get_height (pixbuf), - retval, 1, 1); - - return retval; -} - -static GdkPixbuf * -remove_shaped_area (GdkPixbuf *pixbuf, Window window) -{ - GdkPixbuf *retval; - XRectangle *rectangles; - int rectangle_count, rectangle_order; - int i; - - retval = gdk_pixbuf_new (GDK_COLORSPACE_RGB, TRUE, 8, - gdk_pixbuf_get_width (pixbuf), - gdk_pixbuf_get_height (pixbuf)); - - gdk_pixbuf_fill (retval, 0); - rectangles = XShapeGetRectangles (GDK_DISPLAY_XDISPLAY (gdk_display_get_default ()), window, - ShapeBounding, &rectangle_count, &rectangle_order); - - for (i = 0; i < rectangle_count; i++) { - int y, x; - - for (y = rectangles[i].y; y < rectangles[i].y + rectangles[i].height; y++) { - guchar *src_pixels, *dest_pixels; - - src_pixels = gdk_pixbuf_get_pixels (pixbuf) + - y * gdk_pixbuf_get_rowstride (pixbuf) + - rectangles[i].x * (gdk_pixbuf_get_has_alpha (pixbuf) ? 4 : 3); - dest_pixels = gdk_pixbuf_get_pixels (retval) + - y * gdk_pixbuf_get_rowstride (retval) + - rectangles[i].x * 4; - - for (x = rectangles[i].x; x < rectangles[i].x + rectangles[i].width; x++) { - *dest_pixels++ = *src_pixels ++; - *dest_pixels++ = *src_pixels ++; - *dest_pixels++ = *src_pixels ++; - *dest_pixels++ = 255; - - if (gdk_pixbuf_get_has_alpha (pixbuf)) - src_pixels++; - } - } - } - - return retval; -} - -static GdkPixbuf * -take_window_shot (Window child, gboolean include_decoration) -{ - GdkWindow *window; - Window xid; - gint x_orig, y_orig; - gint x = 0, y = 0; - gint width, height; - - GdkPixbuf *tmp, *tmp2; - GdkPixbuf *retval; - - if (include_decoration) - xid = find_toplevel_window (child); - else - xid = child; - - window = gdk_x11_window_foreign_new_for_display (gdk_display_get_default (), xid); - - width = gdk_window_get_width (window); - height = gdk_window_get_height (window); - gdk_window_get_origin (window, &x_orig, &y_orig); - - if (x_orig < 0) { - x = - x_orig; - width = width + x_orig; - x_orig = 0; - } - - if (y_orig < 0) { - y = - y_orig; - height = height + y_orig; - y_orig = 0; - } - - if (x_orig + width > gdk_screen_width ()) - width = gdk_screen_width () - x_orig; - - if (y_orig + height > gdk_screen_height ()) - height = gdk_screen_height () - y_orig; - - tmp = gdk_pixbuf_get_from_window (window, x, y, width, height); - - if (include_decoration) - tmp2 = remove_shaped_area (tmp, xid); - else - tmp2 = add_border_to_shot (tmp); - - retval = create_shadowed_pixbuf (tmp2); - g_object_unref (tmp); - g_object_unref (tmp2); - - return retval; -} - -int -main (int argc, char **argv) -{ - GdkPixbuf *screenshot = NULL; - GError *error = NULL; - GtkAllocation allocation; - GcrShooterInfo *info; - GdkWindow *window; - const gchar *outdir; - XID id; - char *filename; - - /* - * If there's no DISPLAY, we silently error out. We don't want to break - * headless builds. - */ - - if (!gtk_init_check (&argc, &argv)) - return 0; - - if (argc < 2 || !argv[1]) { - g_printerr ("specify name of widget\n"); - return 2; - } - - info = gcr_widgets_create (argv[1]); - if (info == NULL) { - g_printerr ("no such widget: %s\n", argv[1]); - return 1; - } - - gtk_widget_show (info->window); - window = gtk_widget_get_window (info->window); - gtk_widget_get_allocation (info->window, &allocation); - - gtk_widget_show_now (info->window); - gtk_widget_queue_draw_area (info->window, - allocation.x, allocation.y, - allocation.width, allocation.height); - gdk_window_process_updates (window, TRUE); - - while (gtk_events_pending ()) - gtk_main_iteration (); - sleep (1); - - while (gtk_events_pending ()) - gtk_main_iteration (); - - id = gdk_x11_window_get_xid (window); - screenshot = take_window_shot (id, info->include_decorations); - - outdir = (argc >= 3) ? argv[2] : "."; - filename = g_strdup_printf ("%s/%s.png", outdir, info->name); - if (!gdk_pixbuf_save (screenshot, filename, "png", &error, NULL)) { - g_printerr ("couldn't write screenshot: %s: %s\n", filename, error->message); - g_clear_error (&error); - return 1; - } - g_free(filename); - gtk_widget_hide (info->window); - - return 0; -} diff --git a/docs/reference/gcr/gcr-shooter.h b/docs/reference/gcr/gcr-shooter.h deleted file mode 100644 index 407a364..0000000 --- a/docs/reference/gcr/gcr-shooter.h +++ /dev/null @@ -1,23 +0,0 @@ - -#include <gtk/gtk.h> - -typedef enum { - GCR_SHOOTER_SMALL, - GCR_SHOOTER_MEDIUM, - GCR_SHOOTER_LARGE, - GCR_SHOOTER_ASIS -} GcrShooterSize; - -typedef struct GcrShooterInfo { - GtkWidget *window; - gchar *name; - gboolean no_focus; - gboolean include_decorations; - GcrShooterSize size; -} GcrShooterInfo; - -GcrShooterInfo* gcr_widgets_create (const gchar *name); - -GcrShooterInfo* gcr_shooter_info_new (const gchar *name, - GtkWidget *widget, - GcrShooterSize size); diff --git a/docs/reference/gcr/gcr-visual-index.xml b/docs/reference/gcr/gcr-visual-index.xml deleted file mode 100644 index ced540a..0000000 --- a/docs/reference/gcr/gcr-visual-index.xml +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ -]> -<para role="gallery"> - <link linkend="GcrCertificateWidget"> - <inlinegraphic fileref="certificate-widget.png" format="PNG"></inlinegraphic> - </link> - <link linkend="GcrComboSelector"> - <inlinegraphic fileref="combo-selector.png" format="PNG"></inlinegraphic> - </link> - <link linkend="GcrImportButton"> - <inlinegraphic fileref="import-button.png" format="PNG"></inlinegraphic> - </link> - <link linkend="GcrListSelector"> - <inlinegraphic fileref="list-selector.png" format="PNG"></inlinegraphic> - </link> - <link linkend="GcrKeyWidget"> - <inlinegraphic fileref="key-widget.png" format="PNG"></inlinegraphic> - </link> - <link linkend="GcrTreeSelector"> - <inlinegraphic fileref="tree-selector.png" format="PNG"></inlinegraphic> - </link> - <link linkend="GcrViewerWidget"> - <inlinegraphic fileref="viewer-widget.png" format="PNG"></inlinegraphic> - </link> -</para>
\ No newline at end of file diff --git a/docs/reference/gcr/gcr-widgets.c b/docs/reference/gcr/gcr-widgets.c deleted file mode 100644 index d8458ed..0000000 --- a/docs/reference/gcr/gcr-widgets.c +++ /dev/null @@ -1,236 +0,0 @@ - -#include "gcr-shooter.h" -#include "gcr.h" - -static gpointer -load_gcr_test_file (const gchar *name, gsize *length) -{ - GError *error = NULL; - gchar *contents; - gchar *filename; - - filename = g_build_filename (TOPDIR, "gcr", "tests", "files", name, NULL); - if (!g_file_get_contents (filename, &contents, length, &error)) - g_error ("couldn't read file: %s: %s", filename, error->message); - g_free (filename); - return contents; -} - -static GcrShooterInfo * -create_certificate_widget (const gchar *name) -{ - GcrCertificate *certificate; - GtkWidget *widget; - GtkWidget *align; - gchar *contents; - gsize length; - - contents = load_gcr_test_file ("cacert.org.cer", &length); - certificate = gcr_simple_certificate_new (contents, length); - g_free (contents); - - widget = GTK_WIDGET (gcr_certificate_widget_new (certificate)); - g_object_unref (certificate); - - align = gtk_alignment_new (0.5, 0.5, 0.0, 0.0); - gtk_container_add (GTK_CONTAINER (align), widget); - - return gcr_shooter_info_new (name, align, GCR_SHOOTER_LARGE); -} - -static void -on_parser_key_parsed (GcrParser *parser, gpointer unused) -{ - GckAttributes **attrs = unused; - *attrs = gck_attributes_ref (gcr_parser_get_parsed_attributes (parser)); -} - -static GcrShooterInfo * -create_key_widget (const gchar *name) -{ - GError *error = NULL; - GckAttributes *attrs = NULL; - GtkWidget *widget; - GtkWidget *align; - GcrParser *parser; - gchar *contents; - gsize length; - - contents = load_gcr_test_file ("der-dsa-1024.key", &length); - parser = gcr_parser_new (); - g_signal_connect (parser, "parsed", G_CALLBACK (on_parser_key_parsed), &attrs); - if (!gcr_parser_parse_data (parser, contents, length, &error)) - g_error ("couldn't parse data: %s", error->message); - g_object_unref (parser); - g_free (contents); - - g_assert (attrs); - widget = GTK_WIDGET (gcr_key_widget_new (attrs)); - gck_attributes_unref (attrs); - - align = gtk_alignment_new (0.5, 0.5, 0.0, 0.0); - gtk_container_add (GTK_CONTAINER (align), widget); - - return gcr_shooter_info_new (name, align, GCR_SHOOTER_LARGE); -} - -static GcrShooterInfo * -create_combo_selector (const gchar *name) -{ - GcrComboSelector *selector; - GcrCertificate *certificate; - GcrCollection *collection; - GtkWidget *align; - gchar *contents; - gsize length; - - contents = load_gcr_test_file ("cacert.org.cer", &length); - certificate = gcr_simple_certificate_new (contents, length); - g_free (contents); - - collection = gcr_simple_collection_new (); - gcr_simple_collection_add (GCR_SIMPLE_COLLECTION (collection), G_OBJECT (certificate)); - - selector = gcr_combo_selector_new (collection); - g_object_unref (collection); - - gcr_combo_selector_set_selected (selector, G_OBJECT (certificate)); - g_object_unref (certificate); - - align = gtk_alignment_new (0.5, 0.5, 0.0, 0.0); - gtk_container_add (GTK_CONTAINER (align), GTK_WIDGET (selector)); - - return gcr_shooter_info_new (name, align, GCR_SHOOTER_MEDIUM); -} - -static GcrShooterInfo * -create_tree_selector (const gchar *name) -{ - GcrTreeSelector *selector; - GcrCertificate *certificate; - GcrCollection *collection; - GtkWidget *align; - gchar *contents; - gsize length; - GList *selected = NULL; - - collection = gcr_simple_collection_new (); - selector = gcr_tree_selector_new (collection, GCR_CERTIFICATE_COLUMNS); - - contents = load_gcr_test_file ("cacert.org.cer", &length); - certificate = gcr_simple_certificate_new (contents, length); - g_free (contents); - gcr_simple_collection_add (GCR_SIMPLE_COLLECTION (collection), G_OBJECT (certificate)); - selected = g_list_append (selected, certificate); - gcr_tree_selector_set_selected (selector, selected); - g_list_free (selected); - g_object_unref (certificate); - - contents = load_gcr_test_file ("der-certificate-dsa.cer", &length); - certificate = gcr_simple_certificate_new (contents, length); - g_free (contents); - gcr_simple_collection_add (GCR_SIMPLE_COLLECTION (collection), G_OBJECT (certificate)); - g_object_unref (certificate); - - g_object_unref (collection); - - align = gtk_alignment_new (0.5, 0.5, 0.0, 0.0); - gtk_container_add (GTK_CONTAINER (align), GTK_WIDGET (selector)); - - return gcr_shooter_info_new (name, align, GCR_SHOOTER_MEDIUM); -} - -static GcrShooterInfo * -create_list_selector (const gchar *name) -{ - GcrListSelector *selector; - GcrCertificate *certificate; - GcrCollection *collection; - GtkWidget *align; - gchar *contents; - gsize length; - GList *selected = NULL; - - collection = gcr_simple_collection_new (); - selector = gcr_list_selector_new (collection); - - contents = load_gcr_test_file ("cacert.org.cer", &length); - certificate = gcr_simple_certificate_new (contents, length); - g_free (contents); - gcr_simple_collection_add (GCR_SIMPLE_COLLECTION (collection), G_OBJECT (certificate)); - selected = g_list_append (selected, certificate); - gcr_list_selector_set_selected (selector, selected); - g_list_free (selected); - g_object_unref (certificate); - - contents = load_gcr_test_file ("der-certificate-dsa.cer", &length); - certificate = gcr_simple_certificate_new (contents, length); - g_free (contents); - gcr_simple_collection_add (GCR_SIMPLE_COLLECTION (collection), G_OBJECT (certificate)); - g_object_unref (certificate); - - g_object_unref (collection); - - align = gtk_alignment_new (0.5, 0.5, 0.0, 0.0); - gtk_container_add (GTK_CONTAINER (align), GTK_WIDGET (selector)); - - return gcr_shooter_info_new (name, align, GCR_SHOOTER_MEDIUM); -} - -static GcrShooterInfo * -create_import_button (const gchar *name) -{ - GcrImportButton *import; - GtkWidget *align; - - import = gcr_import_button_new ("Import"); - - align = gtk_alignment_new (0.5, 0.5, 0.0, 0.0); - gtk_container_add (GTK_CONTAINER (align), GTK_WIDGET (import)); - - return gcr_shooter_info_new (name, align, GCR_SHOOTER_MEDIUM); -} - -static GcrShooterInfo * -create_viewer_widget (const gchar *name) -{ - GcrViewerWidget *viewer; - GtkWidget *align; - gchar *contents; - gsize length; - - contents = load_gcr_test_file ("email.p12", &length); - viewer = gcr_viewer_widget_new (); - gcr_viewer_widget_load_data (viewer, "Email certificate", (gpointer)contents, length); - g_free (contents); - - align = gtk_alignment_new (0.5, 0.5, 0.0, 0.0); - gtk_container_add (GTK_CONTAINER (align), GTK_WIDGET (viewer)); - - return gcr_shooter_info_new (name, align, GCR_SHOOTER_LARGE); -} - -GcrShooterInfo* -gcr_widgets_create (const gchar *name) -{ - g_assert (name); - - if (g_str_equal (name, "certificate-widget")) - return create_certificate_widget (name); - else if (g_str_equal (name, "combo-selector")) - return create_combo_selector (name); - else if (g_str_equal (name, "import-button")) - return create_import_button (name); - else if (g_str_equal (name, "key-widget")) - return create_key_widget (name); - else if (g_str_equal (name, "list-selector")) - return create_list_selector (name); - else if (g_str_equal (name, "tree-selector")) - return create_tree_selector (name); - else if (g_str_equal (name, "viewer-widget")) - return create_viewer_widget (name); - else - g_assert_not_reached (); - - return NULL; -} diff --git a/docs/reference/gcr/gcr.types b/docs/reference/gcr/gcr.types deleted file mode 100644 index c222b4a..0000000 --- a/docs/reference/gcr/gcr.types +++ /dev/null @@ -1,29 +0,0 @@ -gcr_certificate_chain_get_type -gcr_certificate_get_type -gcr_certificate_renderer_get_type -gcr_certificate_widget_get_type -gcr_collection_get_type -gcr_collection_model_get_type -gcr_combo_selector_get_type -gcr_comparable_get_type -gcr_filter_collection_get_type -gcr_import_button_get_type -gcr_importer_get_type -gcr_key_renderer_get_type -gcr_key_widget_get_type -gcr_list_selector_get_type -gcr_parser_get_type -gcr_pkcs11_certificate_get_type -gcr_prompt_get_type -gcr_prompt_dialog_get_type -gcr_renderer_get_type -gcr_secure_entry_buffer_get_type -gcr_simple_certificate_get_type -gcr_simple_collection_get_type -gcr_system_prompt_get_type -gcr_system_prompter_get_type -gcr_tree_selector_get_type -gcr_union_collection_get_type -gcr_unlock_options_widget_get_type -gcr_viewer_get_type -gcr_viewer_widget_get_type diff --git a/docs/reference/gcr/meson.build b/docs/reference/gcr/meson.build deleted file mode 100644 index 43528c8..0000000 --- a/docs/reference/gcr/meson.build +++ /dev/null @@ -1,83 +0,0 @@ -version_xml = configure_file( - input: 'version.xml.in', - output: '@BASENAME@', - configuration: { 'VERSION': gcr_version }, -) - -gcr_docs_images = [ - 'images/certificate-widget.png', - 'images/combo-selector.png', - 'images/import-button.png', - 'images/list-selector.png', - 'images/key-widget.png', - 'images/tree-selector.png', - 'images/viewer-widget.png', -] - -gcr_docs_ignore_headers = [ - 'console-interaction.h', - 'eggimagemenuitem.h', - 'gcr-callback-output-stream.h', - 'gcr-certificate-exporter.h', - 'gcr-certificate-basics-widget.h', - 'gcr-certificate-details-widget.h', - 'gcr-certificate-request-renderer.h', - 'gcr-dbus-constants.h', - 'gcr-dbus-generated.h', - 'gcr-deprecated.h', - 'gcr-deprecated-base.h', - 'gcr-display-scrolled.h', - 'gcr-display-view.h', - 'gcr-failure-renderer.h', - 'gcr-gnupg-importer.h', - 'gcr-gnupg-renderer.h', - 'gcr-icons.h', - 'gcr-import-dialog.h', - 'gcr-internal.h', - 'gcr-live-search.h', - 'gcr-marshal.h', - 'gcr-menu-button.h', - 'gcr-oids.h', - 'gcr-openpgp.h', - 'gcr-pkcs11-importer.h', - 'gcr-pkcs11-import-interaction.h', - 'gcr-pkcs11-import-dialog.h', - 'gcr-pkcs11-renderer.h', - 'gcr-record.h', - 'gcr-single-collection.h', - 'gcr-ssh-agent-interaction.h', - 'gcr-ssh-agent-preload.h', - 'gcr-ssh-agent-private.h', - 'gcr-ssh-agent-process.h', - 'gcr-ssh-agent-service.h', - 'gcr-ssh-agent-util.h', - 'gcr-ssh-agent-test.h', - 'gcr-unlock-renderer.h', - 'gcr-viewer-window.h', - 'gcr-xxx.h', - 'gcr-zzz.h', -] - -gnome.gtkdoc('gcr', - main_sgml: 'gcr-docs.sgml', - content_files: files( - 'gcr-visual-index.xml', - ), - src_dir: [ - include_directories('../../../gcr'), - include_directories('../../../ui'), - ], - ignore_headers: gcr_docs_ignore_headers, - dependencies: [ gcr_base_dep, gcr_ui_dep ], - gobject_typesfile: 'gcr.types', - html_assets: gcr_docs_images, - scan_args: [ - '--rebuild-types', - '--deprecated-guards=GCR_DISABLE_DEPRECATED', - ], - install: true, -) - -install_data(gcr_docs_images, - install_dir: gnome.gtkdoc_html_dir('gcr'), -) diff --git a/docs/reference/gcr/version.xml.in b/docs/reference/gcr/version.xml.in deleted file mode 100644 index 27323da..0000000 --- a/docs/reference/gcr/version.xml.in +++ /dev/null @@ -1 +0,0 @@ -@VERSION@
\ No newline at end of file diff --git a/docs/ui/gcr-ui.toml.in b/docs/ui/gcr-ui.toml.in new file mode 100644 index 0000000..4ccf466 --- /dev/null +++ b/docs/ui/gcr-ui.toml.in @@ -0,0 +1,56 @@ +[library] +namespace = "GcrUi" +version = "@GCR_VERSION@" +browse_url = "https://gitlab.gnome.org/GNOME/gcr/" +repository_url = "https://gitlab.gnome.org/GNOME/gcr.git" +authors = "GCR contributors" +license = "LGPL-2.0-or-later" +description = "Library providing GTK widgets for high level crypto" +dependencies = [ "GObject-2.0", "Gio-2.0", "Gtk-3.0", "Gck-@GCK_VERSION@", "Gcr-@GCR_VERSION@" ] +devhelp = true +search_index = true + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://developer.gnome.org/gobject/stable" + + [dependencies."Gio-2.0"] + name = "Gio" + description = "GObject interfaces and objects" + docs_url = "https://developer.gnome.org/gio/stable" + + [dependencies."Gtk-3.0"] + name = "Gtk" + description = "The GTK UI toolkit" + docs_url = "https://docs.gtk.org/gtk4/" + + [dependencies."Gck-@GCK_VERSION@"] + name = "Gck" + description = "GObject bindings for PKCS#11" + + [dependencies."Gcr-@GCR_VERSION@"] + name = "Gcr" + description = "GObject library for high level crypto parsing" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[source-location] +base_url = "https://gitlab.gnome.org/GNOME/gcr/-/blob/master/" + +[extra] +content_files = [ + 'widget-gallery.md', +] +content_images = [ + 'images/certificate-widget.png', + 'images/combo-selector.png', + 'images/import-button.png', + 'images/key-widget.png', + 'images/list-selector.png', + 'images/tree-selector.png', + 'images/viewer-widget.png', +] diff --git a/docs/reference/gcr/images/certificate-widget.png b/docs/ui/images/certificate-widget.png Binary files differindex e3c9158..e3c9158 100644 --- a/docs/reference/gcr/images/certificate-widget.png +++ b/docs/ui/images/certificate-widget.png diff --git a/docs/reference/gcr/images/combo-selector.png b/docs/ui/images/combo-selector.png Binary files differindex 073f483..073f483 100644 --- a/docs/reference/gcr/images/combo-selector.png +++ b/docs/ui/images/combo-selector.png diff --git a/docs/reference/gcr/images/import-button.png b/docs/ui/images/import-button.png Binary files differindex 9166bb8..9166bb8 100644 --- a/docs/reference/gcr/images/import-button.png +++ b/docs/ui/images/import-button.png diff --git a/docs/reference/gcr/images/key-widget.png b/docs/ui/images/key-widget.png Binary files differindex db3a371..db3a371 100644 --- a/docs/reference/gcr/images/key-widget.png +++ b/docs/ui/images/key-widget.png diff --git a/docs/reference/gcr/images/list-selector.png b/docs/ui/images/list-selector.png Binary files differindex 7f9c688..7f9c688 100644 --- a/docs/reference/gcr/images/list-selector.png +++ b/docs/ui/images/list-selector.png diff --git a/docs/reference/gcr/images/tree-selector.png b/docs/ui/images/tree-selector.png Binary files differindex 7bcd1a1..7bcd1a1 100644 --- a/docs/reference/gcr/images/tree-selector.png +++ b/docs/ui/images/tree-selector.png diff --git a/docs/reference/gcr/images/viewer-widget.png b/docs/ui/images/viewer-widget.png Binary files differindex 1933e04..1933e04 100644 --- a/docs/reference/gcr/images/viewer-widget.png +++ b/docs/ui/images/viewer-widget.png diff --git a/docs/ui/meson.build b/docs/ui/meson.build new file mode 100644 index 0000000..49ea4ca --- /dev/null +++ b/docs/ui/meson.build @@ -0,0 +1,35 @@ +gcr_ui_content_files = [ + 'widget-gallery.md', +] + +gcr_ui_toml = configure_file( + input: 'gcr-ui.toml.in', + output: '@BASENAME@', + configuration: { + 'GCR_VERSION': gcr_major_version, + 'GCK_VERSION': gck_major_version, + }, +) + +gcr_ui_docs = custom_target('gcr-ui-docs', + input: gcr_ui_gir[0], + output: 'gcr-ui-@0@'.format(gcr_major_version), + command: [ + gi_docgen, + 'generate', + '--quiet', + '--fatal-warnings', + '--add-include-path=@0@'.format(build_root / 'gck'), + '--add-include-path=@0@'.format(build_root / 'gcr'), + '--config', gcr_ui_toml, + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '@INPUT@', + ], + depend_files: [ gcr_ui_toml, gcr_ui_content_files ], + depends: [ gck_gir[0], gcr_gir[0] ], + build_by_default: true, + install: true, + install_dir: get_option('datadir') / 'doc', +) diff --git a/docs/ui/widget-gallery.md b/docs/ui/widget-gallery.md new file mode 100644 index 0000000..27e1e90 --- /dev/null +++ b/docs/ui/widget-gallery.md @@ -0,0 +1,20 @@ +Title: Widget gallery + +Widget gallery +============== + +Selector widgets +---------------- +[](class.ComboSelector.html) +[](class.ListSelector.html) +[](class.TreeSelector.html) + +Display widgets +--------------- +[](class.CertificateWidget.html) +[](class.KeyWidget.html) +[](class.ViewerWidget.html) + +Import widgets +-------------- +[](class.ImportButton.html) diff --git a/gck/gck-attributes.c b/gck/gck-attributes.c index 8612a28..de10a67 100644 --- a/gck/gck-attributes.c +++ b/gck/gck-attributes.c @@ -32,16 +32,18 @@ #include <string.h> /** - * SECTION:gck-attribute - * @title: GckAttribute - * @short_description: A PKCS11 attribute. + * GckAttribute: + * @type: The attribute type, such as `CKA_LABEL`. + * @value: (array length=length): The value of the attribute. May be %NULL. + * @length: The length of the attribute. May be [const@INVALID] if the + * attribute is invalid. * - * This structure represents a PKCS11 CK_ATTRIBUTE. These attributes contain i - * about a PKCS11 object. Use gck_object_get() or gck_object_set() to set and - * attributes on an object. + * This structure represents a PKCS#11 `CK_ATTRIBUTE`. These attributes contain + * information about a PKCS#11 object. Use [method@Object.get] or + * [method@Object.set] to set and attributes on an object. * - * Although you are free to allocate a #GckAttribute in your own code, no functions in - * this library will operate on such an attribute. + * Although you are free to allocate a `GckAttribute` in your own code, no + * functions in this library will operate on such an attribute. */ G_STATIC_ASSERT (sizeof (GckAttribute) == sizeof (CK_ATTRIBUTE)); @@ -156,7 +158,7 @@ G_DEFINE_BOXED_TYPE (GckBuilder, gck_builder, * GckBuilder: * * A builder for a set of attributes. Add attributes to a builder, and then use - * gck_builder_end() to get the completed #GckAttributes. + * [method@Builder.end] to get the completed [struct@Attributes]. * * The fields of #GckBuilder are private and not to be accessed directly. */ @@ -166,7 +168,7 @@ G_DEFINE_BOXED_TYPE (GckBuilder, gck_builder, * @GCK_BUILDER_NONE: no special flags * @GCK_BUILDER_SECURE_MEMORY: use non-pageable memory for the values of the attributes * - * Flags to be used with a gck_builder_init_full() and gck_builder_new(). + * Flags to be used with a [method@Builder.init_full] and [ctor@Builder.new]. */ /** @@ -174,19 +176,19 @@ G_DEFINE_BOXED_TYPE (GckBuilder, gck_builder, * * Values that can be assigned to a #GckBuilder allocated on the stack. * - * <informalexample><programlisting> + * ```c * GckBuilder builder = GCK_BUILDER_INIT; - * </programlisting></informalexample> + * ``` */ /** * gck_builder_new: * @flags: flags for the new builder * - * Create a new #GckBuilder not allocated on the stack, so it can be shared + * Create a new `GckBuilder` not allocated on the stack, so it can be shared * across a single scope, and referenced / unreferenced. * - * Normally a #GckBuilder is created on the stack, and simply initialized. + * Normally a `GckBuilder` is created on the stack, and simply initialized. * * If the %GCK_BUILDER_SECURE_MEMORY flag is specified then non-pageable memory * will be used for the various values of the attributes in the builder @@ -209,7 +211,7 @@ gck_builder_new (GckBuilderFlags flags) * gck_builder_ref: * @builder: the builder * - * Add a reference to a builder that was created with gck_builder_new(). The + * Add a reference to a builder that was created with [ctor@Builder.new]. The * builder must later be unreferenced again with gck_builder_unref(). * * It is an error to use this function on builders that were allocated on the @@ -289,8 +291,8 @@ gck_builder_init_full (GckBuilder *builder, * This is equivalent to initializing a builder variable with the * %GCK_BUILDER_INIT constant, or setting it to zeroed memory. * - * <informalexample><programlisting> - * /<!-- -->* Equivalent ways of initializing a GckBuilder *<!-- -->/ + * ```c + * // Equivalent ways of initializing a GckBuilder * GckBuilder builder = GCK_BUILDER_INIT; * GckBuilder builder2; * GckBuilder builder3; @@ -298,7 +300,7 @@ gck_builder_init_full (GckBuilder *builder, * gck_builder_init (&builder2); * * memset (&builder3, 0, sizeof (builder3)); - * </programlisting></informalexample> + * ``` */ void gck_builder_init (GckBuilder *builder) @@ -387,7 +389,7 @@ builder_copy (GckBuilder *builder, * @builder: the builder to copy * * Make a copy of the builder and its state. The new builder is allocated - * with gck_builder_new() and should be freed with gck_builder_unref(). + * with [ctor@Builder.new] and should be freed with gck_builder_unref(). * * Attribute value memory is automatically shared between the two builders, * and is only freed when both are gone. @@ -428,8 +430,8 @@ gck_builder_copy (GckBuilder *builder) * using the standard GLib memory allocation routines. * * %NULL may be specified for the @value argument, in which case an empty - * attribute is created. GCK_INVALID may be specified for the length, in - * which case an invalid attribute is created in the PKCS\#11 style. + * attribute is created. [const@INVALID] may be specified for the length, in + * which case an invalid attribute is created in the PKCS#11 style. */ void gck_builder_take_data (GckBuilder *builder, @@ -474,8 +476,8 @@ gck_builder_take_data (GckBuilder *builder, * The memory in @value is copied by the builder. * * %NULL may be specified for the @value argument, in which case an empty - * attribute is created. GCK_INVALID may be specified for the length, in - * which case an invalid attribute is created in the PKCS\#11 style. + * attribute is created. [const@INVALID] may be specified for the length, in + * which case an invalid attribute is created in the PKCS#11 style. */ void gck_builder_add_data (GckBuilder *builder, @@ -516,8 +518,8 @@ gck_builder_add_data (GckBuilder *builder, * The memory in @value is copied by the builder. * * %NULL may be specified for the @value argument, in which case an empty - * attribute is created. GCK_INVALID may be specified for the length, in - * which case an invalid attribute is created in the PKCS\#11 style. + * attribute is created. [const@INVALID] may be specified for the length, in + * which case an invalid attribute is created in the PKCS#11 style. */ void gck_builder_set_data (GckBuilder *builder, @@ -584,7 +586,7 @@ gck_builder_set_empty (GckBuilder *builder, * @builder: the builder * @attr_type: the new attribute type * - * Add a new attribute to the builder that is invalid in the PKCS\#11 sense. + * Add a new attribute to the builder that is invalid in the PKCS#11 sense. * Unconditionally adds a new attribute, even if one with the same @attr_type * already exists. */ @@ -605,7 +607,7 @@ gck_builder_add_invalid (GckBuilder *builder, * @builder: the builder * @attr_type: the attribute type * - * Set an attribute on the builder that is invalid in the PKCS\#11 sense. + * Set an attribute on the builder that is invalid in the PKCS#11 sense. * If an attribute with @attr_type already exists in the builder then it is * changed to the new value, otherwise an attribute is added. */ @@ -810,7 +812,7 @@ gck_builder_set_string (GckBuilder *builder, * or not an attribute with the same type already exists on the builder. * * The @attr attribute must have been created or owned by the Gck library. - * If you call this function on an arbitrary #GckAttribute that is allocated on + * If you call this function on an arbitrary `GckAttribute` that is allocated on * the stack or elsewhere, then this will result in undefined behavior. * * As an optimization, the attribute memory value is automatically shared @@ -856,7 +858,7 @@ gck_builder_add_all (GckBuilder *builder, * @builder: the builder * @attrs: the attributes to add * @only_type: the first type of attribute to add - * @...: the remaining attribute types to add, ending with %GCK_INVALID + * @...: the remaining attribute types to add, ending with [const@INVALID] * * Add the attributes specified in the argument list from @attrs to the * builder. The attributes are added uncondititionally whether or not @@ -864,10 +866,10 @@ gck_builder_add_all (GckBuilder *builder, * * The variable arguments must be unsigned longs. * - * <informalexample><programlisting> - * /<!-- -->* Add the CKA_ID and CKA_CLASS attributes from attrs to builder *<!-- -->/ + * ```c + * // Add the CKA_ID and CKA_CLASS attributes from attrs to builder * gck_builder_add_only (builder, attrs, CKA_ID, CKA_CLASS, GCK_INVALID); - * </programlisting></informalexample> + * ``` * * As an optimization, the attribute memory values are automatically shared * between the attributes and the builder. @@ -908,11 +910,11 @@ gck_builder_add_only (GckBuilder *builder, * builder. The attributes are added uncondititionally whether or not * attributes with the same types already exist in the builder. * - * <informalexample><programlisting> - * /<!-- -->* Add the CKA_ID and CKA_CLASS attributes from attrs to builder *<!-- -->/ + * ```c + * // Add the CKA_ID and CKA_CLASS attributes from attrs to builder * gulong only[] = { CKA_ID, CKA_CLASS }; * gck_builder_add_onlyv (builder, attrs, only, 2); - * </programlisting></informalexample> + * ``` * * As an optimization, the attribute memory values are automatically shared * between the attributes and the builder. @@ -942,7 +944,7 @@ gck_builder_add_onlyv (GckBuilder *builder, * @builder: the builder * @attrs: the attributes to add * @except_type: the first type of attribute to to exclude - * @...: the remaining attribute types to exclude, ending with %GCK_INVALID + * @...: the remaining attribute types to exclude, ending with [const@INVALID] * * Add the attributes in @attrs to the builder, with the exception of those * in the argument list. The attributes are added uncondititionally whether or @@ -950,10 +952,10 @@ gck_builder_add_onlyv (GckBuilder *builder, * * The variable arguments must be unsigned longs. * - * <informalexample><programlisting> - * /<!-- -->* Add all attributes in attrs except CKA_CLASS to the builder *<!-- -->/ + * ```c + * // Add all attributes in attrs except CKA_CLASS to the builder * gck_builder_add_except (builder, attrs, CKA_CLASS, GCK_INVALID); - * </programlisting></informalexample> + * ``` * * As an optimization, the attribute memory values are automatically shared * between the attributes and the builder. @@ -995,11 +997,11 @@ gck_builder_add_except (GckBuilder *builder, * uncondititionally whether or not attributes with the same types already * exist in the builder. * - * <informalexample><programlisting> - * /<!-- -->* Add all attributes in attrs except CKA_CLASS to the builder *<!-- -->/ - * gulong except_types[] = { CKA_CLASS }; + * ```c + * // Add all attributes in attrs except CKA_CLASS to the builder + * unsigned long except_types[] = { CKA_CLASS }; * gck_builder_add_exceptv (builder, attrs, except_types, 1); - * </programlisting></informalexample> + * ``` * * As an optimization, the attribute memory values are automatically shared * between the attributes and the builder. @@ -1057,12 +1059,12 @@ gck_builder_set_all (GckBuilder *builder, * @attr_type: the type of attribute to find * * Find an attribute in the builder. Both valid and invalid attributes (in - * the PKCS\#11 sense) are returned. If multiple attributes exist for the given + * the PKCS#11 sense) are returned. If multiple attributes exist for the given * attribute type, then the first one is returned. * - * The returned #GckAttribute is owned by the builder and may not be modified - * in any way. It is only valid until another attribute is added to or set on - * the builder, or until the builder is cleared or unreferenced. + * The returned [struct@Attribute] is owned by the builder and may not be + * modified in any way. It is only valid until another attribute is added to or + * set on the builder, or until the builder is cleared or unreferenced. * * Returns: the attribute or %NULL if not found */ @@ -1102,7 +1104,7 @@ find_attribute_boolean (GckAttribute *attrs, * @value: (out): the location to place the found value * * Find a boolean attribute in the builder that has the type @attr_type, is - * of the correct boolean size, and is not invalid in the PKCS\#11 sense. + * of the correct boolean size, and is not invalid in the PKCS#11 sense. * If multiple attributes exist for the given attribute type, then the first\ * one is returned. * @@ -1146,8 +1148,8 @@ find_attribute_ulong (GckAttribute *attrs, * @value: (out): the location to place the found value * * Find a unsigned long attribute in the builder that has the type @attr_type, - * is of the correct unsigned long size, and is not invalid in the PKCS\#11 sense. - * If multiple attributes exist for the given attribute type, then the first\ + * is of the correct unsigned long size, and is not invalid in the PKCS#11 sense. + * If multiple attributes exist for the given attribute type, then the first * one is returned. * * Returns: whether a valid unsigned long attribute was found @@ -1195,7 +1197,7 @@ find_attribute_string (GckAttribute *attrs, * @value: (out): the location to place the found value * * Find a string attribute in the builder that has the type @attr_type, has a - * non %NULL value pointer, and is not invalid in the PKCS\#11 sense. + * non %NULL value pointer, and is not invalid in the PKCS#11 sense. * If multiple attributes exist for the given attribute type, then the first * one is returned. * @@ -1240,7 +1242,7 @@ find_attribute_date (GckAttribute *attrs, * @value: (out): the location to place the found value * * Find a date attribute in the builder that has the type @attr_type, is of - * the correct date size, and is not invalid in the PKCS\#11 sense. + * the correct date size, and is not invalid in the PKCS#11 sense. * If multiple attributes exist for the given attribute type, then the first * one is returned. * @@ -1308,7 +1310,7 @@ gck_builder_steal (GckBuilder *builder) * * Complete the #GckBuilder, and return the attributes contained in the builder. * The #GckBuilder will be cleared after this function call, and it is no - * longer necessary to use gck_builder_clear() on it, although it is also + * longer necessary to use [method@Builder.clear] on it, although it is also * permitted. The builder may be used again to build another set of attributes * after this function call. * @@ -1367,20 +1369,11 @@ gck_builder_clear (GckBuilder *builder) } /** - * GckAttribute: - * @type: The attribute type, such as CKA_LABEL. - * @value: (array length=length): The value of the attribute. May be %NULL. - * @length: The length of the attribute. May be GCK_INVALID if the attribute is invalid. - * - * This structure represents a PKCS11 CK_ATTRIBUTE. - */ - -/** * gck_attribute_is_invalid: * @attr: The attribute to check. * - * Check if the PKCS\#11 attribute represents 'invalid' or 'not found' - * according to the PKCS\#11 spec. That is, having length + * Check if the PKCS#11 attribute represents 'invalid' or 'not found' + * according to the PKCS#11 spec. That is, having length * of (CK_ULONG)-1. * * Return value: Whether the attribute represents invalid or not. @@ -1396,7 +1389,7 @@ gck_attribute_is_invalid (const GckAttribute *attr) * gck_attribute_get_boolean: * @attr: The attribute to retrieve value from. * - * Get the CK_BBOOL of a PKCS\#11 attribute. No conversion + * Get the CK_BBOOL of a PKCS#11 attribute. No conversion * is performed. It is an error to pass an attribute to this * function unless you're know it's supposed to contain a * boolean value. @@ -1420,7 +1413,7 @@ gck_attribute_get_boolean (const GckAttribute *attr) * gck_attribute_get_ulong: * @attr: The attribute to retrieve value from. * - * Get the CK_ULONG value of a PKCS\#11 attribute. No + * Get the CK_ULONG value of a PKCS#11 attribute. No * conversion is performed. It is an error to pass an attribute * to this function unless you're know it's supposed to contain * a value of the right type. @@ -1444,7 +1437,7 @@ gck_attribute_get_ulong (const GckAttribute *attr) * gck_attribute_get_string: * @attr: The attribute to retrieve value from. * - * Get the string value of a PKCS\#11 attribute. No + * Get the string value of a PKCS#11 attribute. No * conversion is performed. It is an error to pass an attribute * to this function unless you're know it's supposed to contain * a value of the right type. @@ -1470,7 +1463,7 @@ gck_attribute_get_string (const GckAttribute *attr) * @attr: The attribute to retrieve value from. * @value: The date value to fill in with the parsed date. * - * Get the CK_DATE of a PKCS\#11 attribute. No + * Get the CK_DATE of a PKCS#11 attribute. No * conversion is performed. It is an error to pass an attribute * to this function unless you're know it's supposed to contain * a value of the right type. @@ -1546,14 +1539,14 @@ gck_attribute_get_data (const GckAttribute *attr, /** * gck_attribute_init: (skip) * @attr: an uninitialized attribute - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: (array length=length): The raw value of the attribute. * @length: The length of the raw value. * - * Initialize a PKCS\#11 attribute. This copies the value memory + * Initialize a PKCS#11 attribute. This copies the value memory * into an internal buffer. * - * When done with the attribute you should use gck_attribute_clear() + * When done with the attribute you should use [method@Attribute.clear] * to free the internal memory. **/ void @@ -1580,13 +1573,13 @@ gck_attribute_init (GckAttribute *attr, /** * gck_attribute_init_invalid: (skip) * @attr: an uninitialized attribute - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * - * Initialize a PKCS\#11 attribute to an 'invalid' or 'not found' + * Initialize a PKCS#11 attribute to an 'invalid' or 'not found' * state. Specifically this sets the value length to (CK_ULONG)-1 - * as specified in the PKCS\#11 specification. + * as specified in the PKCS#11 specification. * - * When done with the attribute you should use gck_attribute_clear() + * When done with the attribute you should use [method@Attribute.clear] * to free the internal memory. **/ void @@ -1602,12 +1595,12 @@ gck_attribute_init_invalid (GckAttribute *attr, /** * gck_attribute_init_empty: (skip) * @attr: an uninitialized attribute - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * - * Initialize a PKCS\#11 attribute to an empty state. The attribute + * Initialize a PKCS#11 attribute to an empty state. The attribute * type will be set, but no data will be set. * - * When done with the attribute you should use gck_attribute_clear() + * When done with the attribute you should use [method@Attribute.clear] * to free the internal memory. **/ void @@ -1623,13 +1616,13 @@ gck_attribute_init_empty (GckAttribute *attr, gulong attr_type) /** * gck_attribute_init_boolean: (skip) * @attr: an uninitialized attribute - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: the boolean value of the attribute * - * Initialize a PKCS\#11 attribute to boolean. This will result - * in a CK_BBOOL attribute from the PKCS\#11 specs. + * Initialize a PKCS#11 attribute to boolean. This will result + * in a CK_BBOOL attribute from the PKCS#11 specs. * - * When done with the attribute you should use gck_attribute_clear() + * When done with the attribute you should use [method@Attribute.clear] * to free the internal memory. **/ void @@ -1645,13 +1638,13 @@ gck_attribute_init_boolean (GckAttribute *attr, /** * gck_attribute_init_date: (skip) * @attr: an uninitialized attribute - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: the date value of the attribute * - * Initialize a PKCS\#11 attribute to a date. This will result - * in a CK_DATE attribute from the PKCS\#11 specs. + * Initialize a PKCS#11 attribute to a date. This will result + * in a CK_DATE attribute from the PKCS#11 specs. * - * When done with the attribute you should use gck_attribute_clear() + * When done with the attribute you should use [method@Attribute.clear] * to free the internal memory. **/ void @@ -1671,13 +1664,13 @@ gck_attribute_init_date (GckAttribute *attr, /** * gck_attribute_init_ulong: (skip) * @attr: an uninitialized attribute - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: the ulong value of the attribute * - * Initialize a PKCS\#11 attribute to a unsigned long. This will result - * in a CK_ULONG attribute from the PKCS\#11 specs. + * Initialize a PKCS#11 attribute to a unsigned long. This will result + * in a CK_ULONG attribute from the PKCS#11 specs. * - * When done with the attribute you should use gck_attribute_clear() + * When done with the attribute you should use [method@Attribute.clear] * to free the internal memory. **/ void @@ -1693,15 +1686,15 @@ gck_attribute_init_ulong (GckAttribute *attr, /** * gck_attribute_init_string: (skip) * @attr: an uninitialized attribute - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: the null terminated string value of the attribute * - * Initialize a PKCS\#11 attribute to a string. This will result + * Initialize a PKCS#11 attribute to a string. This will result * in an attribute containing the text, but not the null terminator. * The text in the attribute will be of the same encoding as you pass * to this function. * - * When done with the attribute you should use gck_attribute_clear() + * When done with the attribute you should use [method@Attribute.clear] * to free the internal memory. **/ void @@ -1719,11 +1712,11 @@ G_DEFINE_BOXED_TYPE (GckAttribute, gck_attribute, /** * gck_attribute_new: - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: the raw value of the attribute * @length: the length of the attribute * - * Create a new PKCS\#11 attribute. The value will be copied + * Create a new PKCS#11 attribute. The value will be copied * into the new attribute. * * Returns: (transfer full): the new attribute; when done with the attribute @@ -1741,11 +1734,11 @@ gck_attribute_new (gulong attr_type, /** * gck_attribute_new_invalid: - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * - * Create a new PKCS\#11 attribute as 'invalid' or 'not found' + * Create a new PKCS#11 attribute as 'invalid' or 'not found' * state. Specifically this sets the value length to (CK_ULONG)-1 - * as specified in the PKCS\#11 specification. + * as specified in the PKCS#11 specification. * * Returns: (transfer full): the new attribute; when done with the attribute * use gck_attribute_free() to free it @@ -1760,9 +1753,9 @@ gck_attribute_new_invalid (gulong attr_type) /** * gck_attribute_new_empty: - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * - * Create a new PKCS\#11 attribute with empty data. + * Create a new PKCS#11 attribute with empty data. * * Returns: (transfer full): the new attribute; when done with the attribute * use gck_attribute_free() to free it @@ -1777,11 +1770,11 @@ gck_attribute_new_empty (gulong attr_type) /** * gck_attribute_new_boolean: - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: the boolean value of the attribute * - * Initialize a PKCS\#11 attribute to boolean. This will result - * in a CK_BBOOL attribute from the PKCS\#11 specs. + * Initialize a PKCS#11 attribute to boolean. This will result + * in a CK_BBOOL attribute from the PKCS#11 specs. * * Returns: (transfer full): the new attribute; when done with the attribute u * gck_attribute_free() to free it @@ -1797,11 +1790,11 @@ gck_attribute_new_boolean (gulong attr_type, /** * gck_attribute_new_date: - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: the date value of the attribute * - * Initialize a PKCS\#11 attribute to a date. This will result - * in a CK_DATE attribute from the PKCS\#11 specs. + * Initialize a PKCS#11 attribute to a date. This will result + * in a CK_DATE attribute from the PKCS#11 specs. * * Returns: (transfer full): the new attribute; when done with the attribute u * gck_attribute_free() to free it @@ -1817,11 +1810,11 @@ gck_attribute_new_date (gulong attr_type, /** * gck_attribute_new_ulong: - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: the ulong value of the attribute * - * Initialize a PKCS\#11 attribute to a unsigned long. This will result - * in a CK_ULONG attribute from the PKCS\#11 specs. + * Initialize a PKCS#11 attribute to a unsigned long. This will result + * in a `CK_ULONG` attribute from the PKCS#11 specs. * * Returns: (transfer full): the new attribute; when done with the attribute u * gck_attribute_free() to free it @@ -1837,10 +1830,10 @@ gck_attribute_new_ulong (gulong attr_type, /** * gck_attribute_new_string: - * @attr_type: the PKCS\#11 attribute type to set on the attribute + * @attr_type: the PKCS#11 attribute type to set on the attribute * @value: the null-terminated string value of the attribute * - * Initialize a PKCS\#11 attribute to a string. This will result + * Initialize a PKCS#11 attribute to a string. This will result * in an attribute containing the text, but not the null terminator. * The text in the attribute will be of the same encoding as you pass * to this function. @@ -1861,7 +1854,7 @@ gck_attribute_new_string (gulong attr_type, * gck_attribute_dup: * @attr: the attribute to duplicate * - * Duplicate the PKCS\#11 attribute. All value memory is + * Duplicate the PKCS#11 attribute. All value memory is * also copied. * * The @attr must have been allocated or initialized by a Gck function or @@ -1888,12 +1881,12 @@ gck_attribute_dup (const GckAttribute *attr) * @dest: An uninitialized attribute. * @src: An attribute to copy. * - * Initialize a PKCS\#11 attribute as a copy of another attribute. + * Initialize a PKCS#11 attribute as a copy of another attribute. * This copies the value memory as well. * * When done with the copied attribute you should use - * gck_attribute_clear() to free the internal memory. - **/ + * [method@Attribute.clear] to free the internal memory. + */ void gck_attribute_init_copy (GckAttribute *dest, const GckAttribute *src) @@ -1941,7 +1934,7 @@ gck_attribute_clear (GckAttribute *attr) * @attr: (type Gck.Attribute): attribute to free * * Free an attribute and its allocated memory. These is usually - * used with attributes that are allocated by gck_attribute_new() + * used with attributes that are allocated by [ctor@Attribute.new] * or a similar function. **/ void @@ -2012,19 +2005,13 @@ gck_attribute_hash (gconstpointer attr) } /** - * SECTION:gck-attributes - * @title: GckAttributes - * @short_description: A set of PKCS11 attributes. - * - * A set of GckAttribute structures. These attributes contain information - * about a PKCS11 object. Use gck_object_get() or gck_object_set() to set and retrieve - * attributes on an object. - */ - -/** * GckAttributes: * - * A set of GckAttribute structures. + * A set of [struct@Attribute] structures. + * + * These attributes contain information about a PKCS11 object. Use + * [method@Object.get] or [method@Object.set] to set and retrieve attributes on + * an object. */ /** @@ -2032,7 +2019,8 @@ gck_attribute_hash (gconstpointer attr) * @data: Memory to allocate or deallocate. * @length: New length of memory. * - * An allocator used to allocate data for the attributes in this GckAttributes set. + * An allocator used to allocate data for the attributes in this + * [struct@Attributes] set. * * This is a function that acts like g_realloc. Specifically it frees when length is * set to zero, it allocates when data is set to %NULL, and it reallocates when both @@ -2058,7 +2046,7 @@ gck_attributes_get_boxed_type (void) * * Creates an GckAttributes array with empty attributes * - * Terminate the argument list with %GCK_INVALID. + * Terminate the argument list with [const@INVALID]. * * The returned set of attributes is floating, and should either be passed to * another gck library function which consumes this floating reference, or if @@ -2092,7 +2080,7 @@ gck_attributes_new_empty (gulong first_type, * * Get attribute at the specified index in the attribute array. * - * Use gck_attributes_count() to determine how many attributes are + * Use [method@Attributes.count] to determine how many attributes are * in the array. * * Returns: (transfer none): the specified attribute @@ -2252,12 +2240,12 @@ gck_attributes_ref (GckAttributes *attrs) * gck_attributes_ref_sink: * @attrs: an attribute array * - * #GckAttributes uses a floating reference count system. gck_builder_end() - * and gck_attributes_new_empty() both return floating references. + * #GckAttributes uses a floating reference count system. [method@Builder.end] + * and [ctor@Attributes.new_empty] both return floating references. * - * Calling gck_attributes_ref_sink() on a #GckAttributes with a floating + * Calling this function on a `GckAttributes` with a floating * reference will convert the floating reference into a full reference. - * Calling gck_attributes_ref_sink() on a non-floating #GckAttributes results + * Calling this function on a non-floating `GckAttributes` results * in an additional normal reference being added. * * In other words, if the @attrs is floating, then this call "assumes @@ -2822,9 +2810,9 @@ gck_attributes_to_string (GckAttributes *attrs) /** * gck_attributes_new: - * @reserved: Should be set to always be GCK_INVALID + * @reserved: Should be set to always be [const@INVALID] * - * Create a new empty GckAttributes array. + * Create a new empty `GckAttributes` array. * * The returned set of attributes is floating, and should either be passed to * another gck library function which consumes this floating reference, or if @@ -2847,7 +2835,7 @@ gck_attributes_new (gulong reserved) * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_set_all() instead. + * Deprecated: 3.4: Use [method@Builder.set_all] instead. * * Returns: returns %NULL **/ @@ -2865,7 +2853,7 @@ gck_attributes_new_full (GckAllocator allocator) * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_set_all() instead. + * Deprecated: 3.4: Use [method@Builder.set_all] instead. * * Returns: (transfer none): returns %NULL **/ @@ -2884,7 +2872,7 @@ gck_attributes_add (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_set_data() instead. + * Deprecated: 3.4: Use [method@Builder.set_data] instead. **/ void gck_attributes_set (GckAttributes *attrs, @@ -2902,7 +2890,7 @@ gck_attributes_set (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_add_data() instead. + * Deprecated: 3.4: Use [method@Builder.add_data] instead. * * Returns: (transfer none): returns %NULL **/ @@ -2923,7 +2911,7 @@ gck_attributes_add_data (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_add_invalid() instead + * Deprecated: 3.4: Use [method@Builder.add_invalid] instead * * Returns: (transfer none): returns %NULL **/ @@ -2942,7 +2930,7 @@ gck_attributes_add_invalid (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_add_empty() instead. + * Deprecated: 3.4: Use [method@Builder.add_empty] instead. * * Returns: (transfer none): returns %NULL **/ @@ -2962,7 +2950,7 @@ gck_attributes_add_empty (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_add_boolean() instead. + * Deprecated: 3.4: Use [method@Builder.add_boolean] instead. * * Returns: (transfer none): returns %NULL **/ @@ -2983,7 +2971,7 @@ gck_attributes_add_boolean (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_set_boolean() instead. + * Deprecated: 3.4: Use [method@Builder.set_boolean] instead. */ void gck_attributes_set_boolean (GckAttributes *attrs, @@ -3002,7 +2990,7 @@ gck_attributes_set_boolean (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_add_string() instead. + * Deprecated: 3.4: Use [method@Builder.add_string] instead. * * Returns: (transfer none): returns %NULL **/ @@ -3023,7 +3011,7 @@ gck_attributes_add_string (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_set_string() instead. + * Deprecated: 3.4: Use [method@Builder.set_string] instead. */ void gck_attributes_set_string (GckAttributes *attrs, @@ -3041,7 +3029,7 @@ gck_attributes_set_string (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_add_date() instead. + * Deprecated: 3.4: Use [method@Builder.add_date] instead. * * Returns: (transfer none): returns %NULL **/ @@ -3062,7 +3050,7 @@ gck_attributes_add_date (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_set_date() instead. + * Deprecated: 3.4: Use [method@Builder.set_date] instead. */ void gck_attributes_set_date (GckAttributes *attrs, @@ -3080,7 +3068,7 @@ gck_attributes_set_date (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_add_ulong() instead. + * Deprecated: 3.4: Use [method@Builder.add_ulong] instead. * * Returns: (transfer none): returns %NULL **/ @@ -3101,7 +3089,7 @@ gck_attributes_add_ulong (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_set_ulong() instead. + * Deprecated: 3.4: Use [method@Builder.set_ulong] instead. */ void gck_attributes_set_ulong (GckAttributes *attrs, @@ -3118,7 +3106,7 @@ gck_attributes_set_ulong (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_add_all() instead. + * Deprecated: 3.4: Use [method@Builder.add_all] instead. */ void gck_attributes_add_all (GckAttributes *attrs, @@ -3134,7 +3122,7 @@ gck_attributes_add_all (GckAttributes *attrs, * * #GckAttributes are now immutable. This method no longer does anything. * - * Deprecated: 3.4: Use gck_builder_set_all() instead. + * Deprecated: 3.4: Use [method@Builder.set_all] instead. */ void gck_attributes_set_all (GckAttributes *attrs, @@ -3149,7 +3137,7 @@ gck_attributes_set_all (GckAttributes *attrs, * * #GckAttributes are now immutable, and can be used in mulitple places. * - * Deprecated: 3.4: Use gck_attributes_ref() or gck_builder_add_all() instead. + * Deprecated: 3.4: Use gck_attributes_ref() or [method@Builder.add_all] instead. * * Returns: (transfer none): a new floating #GckAttributes */ diff --git a/gck/gck-enumerator.c b/gck/gck-enumerator.c index 16a8923..c1b82ee 100644 --- a/gck/gck-enumerator.c +++ b/gck/gck-enumerator.c @@ -28,16 +28,14 @@ #include <string.h> /** - * SECTION:gck-enumerator - * @title: GckEnumerator - * @short_description: Enumerates through PKCS\#11 objects. + * GckEnumerator: * - * A GckEnumerator can be used to enumerate through PKCS\#11 objects. It will - * automatically create sessions as necessary. + * Can be used to enumerate through PKCS#11 objects. It will automatically + * create sessions as necessary. * - * Use gck_modules_enumerate_objects() or gck_modules_enumerate_uri() to create - * an enumerator. To get the objects use gck_enumerator_next() or - * gck_enumerator_next_async() functions. + * Use [func@modules_enumerate_objects] or [func@modules_enumerate_uri] to + * create an enumerator. To get the objects, use [method@Enumerator.next] or + * [method@Enumerator.next_async] functions. */ enum { @@ -47,12 +45,6 @@ enum { PROP_CHAINED }; -/** - * GckEnumerator: - * - * An object that allows enumerating of objects across modules, tokens. - */ - typedef struct _GckEnumeratorResult { gulong handle; GckSession *session; diff --git a/gck/gck-misc.c b/gck/gck-misc.c index e44241b..1ebebb4 100644 --- a/gck/gck-misc.c +++ b/gck/gck-misc.c @@ -1,4 +1,3 @@ -/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */ /* gck-misc.c - the GObject PKCS#11 wrapper library Copyright (C) 2008, Stefan Walter @@ -36,30 +35,19 @@ EGG_SECURE_DEFINE_GLIB_GLOBALS (); /** - * SECTION:gck-library - * @title: Library Utilities - * @short_description: Library utilities such as version checks - * - * Basic library utilities such as version checks. - */ - -/** * GCK_CHECK_VERSION: * @major: the major version to check for * @minor: the minor version to check for * @micro: the micro version to check for * - * Checks the version of the Gck libarry that is being compiled + * Checks the version of the Gck library that is being compiled * against. * - * <example> - * <title>Checking the version of the Gck library</title> - * <programlisting> + * ``` * #if !GCK_CHECK_VERSION (3, 0, 0) * #warning Old Gck version, disabling functionality * #endif - * </programlisting> - * </example> + * ``` * * Returns: %TRUE if the version of the GLib header files * is the same as or newer than the passed-in version. @@ -84,23 +72,6 @@ EGG_SECURE_DEFINE_GLIB_GLOBALS (); */ /** - * SECTION:gck-error - * @title: Errors - * @short_description: Gck Errors and error codes. - * - * Errors are returned as GError structures. The code member of GError - * contains the raw PKCS11 CK_RV result value. - */ - -/** - * SECTION:gck-private - * @title: Private, not used in docs - * @short_description: Should not show up in docs - * - * Should not show up in the docs - */ - -/** * GCK_INVALID: * * Used as a terminator at the end of variable argument lists. @@ -109,17 +80,20 @@ EGG_SECURE_DEFINE_GLIB_GLOBALS (); /** * GCK_VENDOR_CODE: * - * Custom PKCS11 errors that originate from the gck library, are + * Custom PKCS#11 errors that originate from the gck library, are * based at this error code. */ /** * GckError: * @GCK_ERROR_MODULE_PROBLEM: a result code that signifies there was a problem - * loading a PKCS\#11 module, usually a shared library + * loading a PKCS#11 module, usually a shared library * - * Various error codes. All the CKR_XXX error codes from PKCS\#11 are also + * Various error codes. All the `CKR_XXX` error codes from PKCS#11 are also * relevant error codes. + * + * Note that errors are returned as [class@GLib.Error] structures. The `code` + * member of the error then contains the raw PKCS#11 `CK_RV` result value. */ /** @@ -151,13 +125,13 @@ gck_error_get_quark (void) /** * gck_message_from_rv: - * @rv: The PKCS\#11 return value to get a message for. + * @rv: The PKCS#11 return value to get a message for. * - * Get a message for a PKCS\#11 return value or error code. Do not - * pass CKR_OK or other such non errors to this function. + * Get a message for a PKCS#11 return value or error code. Do not + * pass `CKR_OK` or other non-errors to this function. * * Return value: The user readable message. - **/ + */ const gchar* gck_message_from_rv (gulong rv) { @@ -287,15 +261,6 @@ _gck_rv_from_error (GError *error, return catch_all_code; } -/** - * SECTION:gck-misc - * @title: Miscellaneous Functions - * @short_description: Other miscellaneous functions. - * - * A few supporting functions that come in handy when dealing with the gck - * library or PKCS11 in general. - */ - GType gck_list_get_boxed_type (void) { @@ -353,9 +318,9 @@ gck_list_ref_copy (GList *reflist) * @data: The character data to turn into a null terminated string. * @max: The maximum length of the charater data. * - * Create a string from a set of PKCS\#11 characters. This is - * similar to g_strndup, except for that it also strips trailing - * spaces. These space padded strings are often used in PKCS\#11 + * Create a string from a set of PKCS#11 characters. This is + * similar to [func@GLib.strndup], except for that it also strips trailing + * spaces. These space padded strings are often used in PKCS#11 * structures. * * If the space padded string is filled with null characters then @@ -386,7 +351,7 @@ gck_string_from_chars (const guchar *data, gsize max) * @max: The maximum length of the charater buffer. * @string: The string to place in the buffer. * - * Create a space padded PKCS\#11 string from a null terminated string. + * Create a space padded PKCS#11 string from a null terminated string. * The string must be shorter than the buffer or %FALSE will be * returned. * @@ -441,7 +406,7 @@ _gck_ulong_equal (gconstpointer v1, gconstpointer v2) * @length: length of memory * @result: A location to store the result * - * Convert CK_ULONG type memory to a boolean. + * Convert `CK_ULONG` type memory to a boolean. * * Returns: Whether the conversion was successful. */ @@ -463,7 +428,7 @@ gck_value_to_ulong (const guchar *value, * @length: length of memory * @result: A location to store the result * - * Convert CK_BBOOL type memory to a boolean. + * Convert `CK_BBOOL` type memory to a boolean. * * Returns: Whether the conversion was successful. */ diff --git a/gck/gck-module.c b/gck/gck-module.c index 1fa7584..a50f78d 100644 --- a/gck/gck-module.c +++ b/gck/gck-module.c @@ -35,21 +35,14 @@ #include <string.h> /** - * SECTION:gck-module - * @title: GckModule - * @short_description: A loaded and initialized PKCS\#11 module. - * - * A GckModule object holds a loaded PKCS\#11 module. A PKCS\#11 module is a shared library. - * - * You can load and initialize a PKCS\#11 module with the gck_module_initialize() call. If you already - * have a loaded and initialized module that you'd like to use with the various gck functions, then - * you can use gck_module_new(). - */ - -/** * GckModule: * - * Holds a loaded and initialized PKCS\#11 module. + * Holds a loaded PKCS#11 module. A PKCS#11 module is a shared library. + * + * You can load and initialize a PKCS#11 module with the + * [func@Module.initialize] call. If you already have a loaded and + * initialized module that you'd like to use with the various Gck functions, + * then you can use [ctor@Module.new]. */ /** @@ -62,9 +55,9 @@ * @library_version_major: The major version of the library. * @library_version_minor: The minor version of the library. * - * Holds information about the PKCS#11 module. + * Holds information about the PKCS#11 module. * - * This structure corresponds to CK_MODULE_INFO in the PKCS\#11 standard. The + * This structure corresponds to `CK_MODULE_INFO` in the PKCS#11 standard. The * strings are %NULL terminated for easier use. * * Use gck_module_info_free() to release this structure when done with it. @@ -365,13 +358,13 @@ free_initialize (Initialize *args) /** * gck_module_initialize: - * @path: The file system path to the PKCS\#11 module to load. + * @path: The file system path to the PKCS#11 module to load. * @cancellable: (nullable): optional cancellation object * @error: A location to store an error resulting from a failed load. * - * Load and initialize a PKCS\#11 module represented by a GckModule object. + * Load and initialize a PKCS#11 module represented by a GckModule object. * - * Return value: (transfer full): The loaded PKCS\#11 module or %NULL if failed. + * Return value: (transfer full): The loaded PKCS#11 module or %NULL if failed. **/ GckModule* gck_module_initialize (const gchar *path, @@ -402,13 +395,13 @@ gck_module_initialize (const gchar *path, /** * gck_module_initialize_async: - * @path: the file system path to the PKCS\#11 module to load + * @path: the file system path to the PKCS#11 module to load * @cancellable: (nullable): optional cancellation object * @callback: a callback which will be called when the operation completes * @user_data: data to pass to the callback * - * Asynchronously load and initialize a PKCS\#11 module represented by a - * #GckModule object. + * Asynchronously load and initialize a PKCS#11 module represented by a + * [class@Module] object. **/ void gck_module_initialize_async (const gchar *path, @@ -464,13 +457,13 @@ gck_module_initialize_finish (GAsyncResult *result, /** * gck_module_new: (skip) - * @funcs: Initialized PKCS\#11 function list pointer + * @funcs: Initialized PKCS#11 function list pointer * - * Create a GckModule representing a PKCS\#11 module. It is assumed that + * Create a [class@Module] representing a PKCS#11 module. It is assumed that * this the module is already initialized. In addition it will not be * finalized when complete. * - * Return value: The new PKCS\#11 module. + * Return value: The new PKCS#11 module. **/ GckModule* gck_module_new (CK_FUNCTION_LIST_PTR funcs) @@ -493,7 +486,7 @@ _gck_module_new_initialized (CK_FUNCTION_LIST_PTR funcs) * @module2: (type Gck.Module): a pointer to the second #GckModule * * Checks equality of two modules. Two GckModule objects can point to the same - * underlying PKCS\#11 module. + * underlying PKCS#11 module. * * Return value: %TRUE if module1 and module2 are equal. * %FALSE if either is not a GckModule. @@ -520,8 +513,8 @@ gck_module_equal (gconstpointer module1, gconstpointer module2) * * Create a hash value for the GckModule. * - * This function is intended for easily hashing a GckModule to add to - * a GHashTable or similar data structure. + * This function is intended for easily hashing a [class@Module] to add to + * a [struct@GLib.HashTable] or similar data structure. * * Return value: An integer that can be used as a hash value, or 0 if invalid. **/ @@ -577,7 +570,7 @@ _gck_module_info_to_pkcs11 (GckModuleInfo* module_info, CK_INFO_PTR info) * gck_module_get_info: * @self: The module to get info for. * - * Get the info about a PKCS\#11 module. + * Get the info about a PKCS#11 module. * * Returns: (transfer full): the module info; release this with gck_module_info_free() **/ @@ -654,7 +647,7 @@ gck_module_get_slots (GckModule *self, gboolean token_present) * @self: The module for which to get the path. * * Get the file path of this module. This may not be an absolute path, and - * usually reflects the path passed to gck_module_initialize(). + * usually reflects the path passed to [func@Module.initialize]. * * Return value: The path, do not modify or free this value. **/ @@ -669,7 +662,7 @@ gck_module_get_path (GckModule *self) * gck_module_get_functions: (skip) * @self: The module for which to get the function list. * - * Get the PKCS\#11 function list for the module. + * Get the PKCS#11 function list for the module. * * Return value: The function list, do not modify this structure. **/ @@ -685,7 +678,7 @@ gck_module_get_functions (GckModule *self) * @self: the module to match * @uri: the uri to match against the module * - * Check whether the PKCS\#11 URI matches the module + * Check whether the PKCS#11 URI matches the module * * Returns: whether the URI matches or not */ diff --git a/gck/gck-modules.c b/gck/gck-modules.c index 63a2e07..97d7f01 100644 --- a/gck/gck-modules.c +++ b/gck/gck-modules.c @@ -35,10 +35,8 @@ #include <string.h> #include <stdlib.h> -/** - * SECTION:gck-modules - * @title: GckModule lists - * @short_description: Dealing with lists of PKCS\#11 modules. +/* + * GckModule lists: * * These functions are useful for dealing with lists of modules, and performing * operations on all of them. @@ -135,7 +133,7 @@ gck_modules_initialize_registered_async (GCancellable *cancellable, * @error: location to place an error on failure * * Finishes the asynchronous operation to initialize the registered - * PKCS\#11 modules. + * PKCS#11 modules. * * Returns: (transfer full) (element-type Gck.Module): a list of newly * initialized #GckModule objects @@ -197,7 +195,7 @@ gck_modules_get_slots (GList *modules, gboolean token_present) * * This call will not block but will return an enumerator immediately. * - * If the @attrs #GckAttributes is floating, it is consumed. + * If the @attrs [struct@Attributes] is floating, it is consumed. * * Return value: (transfer full): A new enumerator, which should be released * with g_object_unref(). @@ -330,7 +328,7 @@ gck_modules_tokens_for_uri (GList *modules, * * Find an object that matches a URI. * - * This call can block. Use gck_modules_enumerate_uri() for a non-blocking + * This call can block. Use [func@modules_enumerate_uri] for a non-blocking * version. * * Returns: (transfer full) (nullable): A new #GckObject which should be released with @@ -367,7 +365,7 @@ gck_modules_object_for_uri (GList *modules, * * Find objects that match a URI. * - * This call can block. Use gck_modules_enumerate_uri() for a non-blocking + * This call can block. Use [func@modules_enumerate_uri] for a non-blocking * version. * * Returns: (transfer full) (element-type Gck.Object): A list of #GckObject which @@ -405,7 +403,7 @@ gck_modules_objects_for_uri (GList *modules, * * Enumerate objects that match a URI. * - * This call will not block. Use the #GckEnumerator functions in order to + * This call will not block. Use the [class@Enumerator] functions in order to * get at the actual objects that match. * * Returns: (transfer full): A new #GckEnumerator, or %NULL if an error occurs. diff --git a/gck/gck-object-cache.c b/gck/gck-object-cache.c index fd1e170..d86867d 100644 --- a/gck/gck-object-cache.c +++ b/gck/gck-object-cache.c @@ -1,4 +1,3 @@ -/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */ /* gck-object-cache.c - the GObject PKCS#11 wrapper library Copyright (C) 2011 Collabora Ltd. @@ -28,20 +27,13 @@ #include <string.h> /** - * SECTION:gck-object-cache - * @title: GckObjectCache - * @short_description: An interface which holds attributes for a PKCS\#11 object - * - * #GckObjectCache is an interface implemented by derived classes of - * #GckObject to indicate which attributes they'd like an enumerator to retrieve. - * These attributes are then cached on the object and can be retrieved through - * the #GckObjectCache:attributes property. - */ - -/** * GckObjectCache: * - * An interface implemented on an #GckObject which contains a cache of attributes. + * An interface implemented by derived classes of [class@Object] to indicate + * which attributes they'd like an enumerator to retrieve. + * + * These attributes are then cached on the object and can be retrieved through + * the [property@ObjectCache:attributes] property. */ /** @@ -52,9 +44,10 @@ * @n_default_types: number of attribute types to be retrieved * @fill: virtual method to add attributes to the cache * - * Interface for #GckObjectCache. If the @default_types field is set by - * a implementing class, then the a #GckEnumerator which has been setup using - * gck_enumerator_set_object_type() + * Interface for [iface@ObjectCache]. If the @default_types field is + * implemented by a implementing class, then that will be used by a + * [class@Enumerator] which has been setup using + * [method@Enumerator.set_object_type] * * The implementation for @populate should add the attributes to the * cache. It must be thread safe. diff --git a/gck/gck-object.c b/gck/gck-object.c index 1521626..284b1f3 100644 --- a/gck/gck-object.c +++ b/gck/gck-object.c @@ -28,31 +28,24 @@ #include <string.h> /** - * SECTION:gck-object - * @title: GckObject - * @short_description: Represents a PKCS11 object such as a key or certificate. - * - * A GckObject holds a handle to a PKCS11 object such as a key or certificate. Token objects - * are stored on the token persistently. Others are transient and are called session objects. - */ - -/** * GckObject: * - * Represents a PKCS11 object handle such as a key or certifiacte. + * Holds a handle to a PKCS11 object such as a key or certificate. Token + * objects are stored on the token persistently. Others are transient and are + * called session objects. */ /** * GckObjectClass: * @parent: derived from this * - * The class for a #GckObject. + * The class for a [class@Object]. * * If the @attribute_types field is set by a derived class, then the a - * #GckEnumerator which has been setup using gck_enumerator_set_object_type() + * #GckEnumerator which has been setup using [method@Enumerator.set_object_type] * with this derived type will retrieve these attributes when enumerating. In * this case the class must implement an 'attributes' property of boxed type - * GCK_TYPE_ATTRIBUTES. + * `GCK_TYPE_ATTRIBUTES`. */ /* @@ -202,15 +195,15 @@ gck_object_class_init (GckObjectClass *klass) */ /** - * gck_object_from_handle: + * gck_object_from_handle: (constructor) * @session: The session through which this object is accessed or created. - * @object_handle: The raw CK_OBJECT_HANDLE of the object. + * @object_handle: The raw `CK_OBJECT_HANDLE` of the object. * - * Initialize a GckObject from a raw PKCS\#11 handle. Normally you would use - * gck_session_create_object() or gck_session_find_objects() to access objects. + * Initialize a GckObject from a raw PKCS#11 handle. Normally you would use + * [method@Session.create_object] or [method@Session.find_objects] to access + * objects. * - * Return value: (transfer full): The new GckObject. You should use - * g_object_unref() when done with this object. + * Return value: (transfer full): The new object **/ GckObject * gck_object_from_handle (GckSession *session, @@ -238,7 +231,7 @@ gck_object_from_handle (GckSession *session, * @object_handles: (array length=n_object_handles): The raw object handles. * @n_object_handles: The number of raw object handles. * - * Initialize a list of GckObject from raw PKCS\#11 handles. The handles argument must contain + * Initialize a list of GckObject from raw PKCS#11 handles. The handles argument must contain * contiguous CK_OBJECT_HANDLE handles in an array. * * Returns: (transfer full) (element-type Gck.Object): The list of #GckObject @@ -267,7 +260,7 @@ gck_objects_from_handle_array (GckSession *session, * @object2: (type Gck.Object): a pointer to the second #GckObject * * Checks equality of two objects. Two GckObject objects can point to the same - * underlying PKCS\#11 object. + * underlying PKCS#11 object. * * Return value: %TRUE if object1 and object2 are equal. * %FALSE if either is not a GckObject. @@ -335,7 +328,7 @@ gck_object_hash (gconstpointer object) * gck_object_get_handle: * @self: The object. * - * Get the raw PKCS\#11 handle of a GckObject. + * Get the raw PKCS#11 handle of a GckObject. * * Return value: the raw CK_OBJECT_HANDLE object handle **/ @@ -350,7 +343,7 @@ gck_object_get_handle (GckObject *self) * gck_object_get_module: * @self: The object. * - * Get the PKCS\#11 module to which this object belongs. + * Get the PKCS#11 module to which this object belongs. * * Returns: (transfer full): the module, which should be unreffed after use **/ @@ -367,7 +360,7 @@ gck_object_get_module (GckObject *self) * gck_object_get_session: * @self: The object * - * Get the PKCS\#11 session assigned to make calls on when operating + * Get the PKCS#11 session assigned to make calls on when operating * on this object. * * This will only return a session if it was set explitly on this @@ -406,7 +399,7 @@ perform_destroy (Destroy *args) * @cancellable: Optional cancellable object, or %NULL to ignore. * @error: A location to return an error. * - * Destroy a PKCS\#11 object, deleting it from storage or the session. + * Destroy a PKCS#11 object, deleting it from storage or the session. * This call may block for an indefinite period. * * Return value: Whether the call was successful or not. @@ -431,7 +424,7 @@ gck_object_destroy (GckObject *self, GCancellable *cancellable, GError **error) * @callback: Callback which is called when operation completes. * @user_data: Data to pass to the callback. * - * Destroy a PKCS\#11 object, deleting it from storage or the session. + * Destroy a PKCS#11 object, deleting it from storage or the session. * This call will return immediately and complete asynchronously. **/ void @@ -457,7 +450,7 @@ gck_object_destroy_async (GckObject *self, GCancellable *cancellable, * @result: The result of the destory operation passed to the callback. * @error: A location to store an error. * - * Get the status of the operation to destroy a PKCS\#11 object, begun with + * Get the status of the operation to destroy a PKCS#11 object, begun with * gck_object_destroy_async(). * * Return value: Whether the object was destroyed successfully or not. @@ -508,7 +501,7 @@ free_set_attributes (SetAttributes *args) * @cancellable: Optional cancellable object, or %NULL to ignore. * @error: A location to return an error. * - * Set PKCS\#11 attributes on an object. This call may block for an indefinite period. + * Set PKCS#11 attributes on an object. This call may block for an indefinite period. * * If the @attrs #GckAttributes is floating, it is consumed. * @@ -546,7 +539,7 @@ gck_object_set (GckObject *self, GckAttributes *attrs, * @callback: Callback which is called when operation completes. * @user_data: Data to pass to the callback. * - * Set PKCS\#11 attributes on an object. This call will return + * Set PKCS#11 attributes on an object. This call will return * immediately and completes asynchronously. * * If the @attrs #GckAttributes is floating, it is consumed. @@ -577,7 +570,7 @@ gck_object_set_async (GckObject *self, GckAttributes *attrs, GCancellable *cance * @result: The result of the destory operation passed to the callback. * @error: A location to store an error. * - * Get the status of the operation to set attributes on a PKCS\#11 object, + * Get the status of the operation to set attributes on a PKCS#11 object, * begun with gck_object_set_async(). * * Return value: Whether the attributes were successfully set on the object or not. @@ -658,7 +651,7 @@ free_get_attributes (GetAttributes *args) * Get the specified attributes from the object. This call may * block for an indefinite period. * - * Returns: (transfer full): the resulting PKCS\#11 attributes, or %NULL if an + * Returns: (transfer full): the resulting PKCS#11 attributes, or %NULL if an * error occurred; the result must be unreffed when you're finished * with it **/ @@ -882,7 +875,7 @@ free_get_attribute_data (GetAttributeData *args) * * This call may block for an indefinite period. * - * Returns: (transfer full) (array length=n_data): the resulting PKCS\#11 + * Returns: (transfer full) (array length=n_data): the resulting PKCS#11 * attribute data, or %NULL if an error occurred **/ guchar * @@ -913,7 +906,7 @@ gck_object_get_data (GckObject *self, * * This call may block for an indefinite period. * - * Returns: (transfer full) (array length=n_data): The resulting PKCS\#11 + * Returns: (transfer full) (array length=n_data): The resulting PKCS#11 * attribute data, or %NULL if an error occurred. **/ guchar * @@ -996,7 +989,7 @@ gck_object_get_data_async (GckObject *self, gulong attr_type, GckAllocator alloc * an object. For convenience the returned data has an extra null terminator, * not included in the returned length. * - * Returns: (transfer full) (array length=n_data): The PKCS\#11 attribute data + * Returns: (transfer full) (array length=n_data): The PKCS#11 attribute data * or %NULL if an error occurred. **/ guchar * @@ -1236,7 +1229,7 @@ free_get_template (get_template_args *args) * * This call may block for an indefinite period. * - * Returns: (transfer full): the resulting PKCS\#11 attribute template, or %NULL + * Returns: (transfer full): the resulting PKCS#11 attribute template, or %NULL * if an error occurred **/ GckAttributes * @@ -1268,19 +1261,19 @@ gck_object_get_template (GckObject *self, gulong attr_type, * gck_object_get_template_async: * @self: The object to get an attribute template from. * @attr_type: The template attribute type. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @callback: Called when the operation completes. * @user_data: Data to be passed to the callback. * - * Get an attribute template from the object. The attr_type must be for + * Get an attribute template from the object. The @attr_type must be for * an attribute which returns a template. * * This call will return immediately and complete asynchronously. **/ void gck_object_get_template_async (GckObject *self, gulong attr_type, - GCancellable *cancellable, GAsyncReadyCallback callback, - gpointer user_data) + GCancellable *cancellable, GAsyncReadyCallback callback, + gpointer user_data) { GckCall *call; get_template_args *args; @@ -1306,7 +1299,7 @@ gck_object_get_template_async (GckObject *self, gulong attr_type, * Get the result of an operation to get attribute template from * an object. * - * Returns: (transfer full): the resulting PKCS\#11 attribute template, or %NULL + * Returns: (transfer full): the resulting PKCS#11 attribute template, or %NULL * if an error occurred **/ GckAttributes * diff --git a/gck/gck-password.c b/gck/gck-password.c index 717c5ca..13bb8f9 100644 --- a/gck/gck-password.c +++ b/gck/gck-password.c @@ -30,28 +30,22 @@ #include <string.h> /** - * SECTION:gck-password - * @title: GckPassword - * @short_description: Represents a password hich is requested of the user - * - * This is used in conjuction with GTlsInteraction. #GckPassword is a - * GTlsPassword which contains additional information about which PKCS\#11 - * token or key the password is being requested for. - */ - -/** * GckPassword: * - * A #GTlsPasswordClass that contains information about the PKCS\#11 token - * or key the password is being requested for. + * Represents a password which is requested of the user. + * + * This is used in conjuction with [class@Gio.TlsInteraction]. `GckPassword` is + * a [class@Gio.TlsPassword] which contains additional information about which + * PKCS#11 token or key the password is being requested for. */ /** * GckPasswordClass: * @parent: parent class * - * The class for #GTlsPassword. + * The class struct for [class@Password]. */ + enum { PROP_0, PROP_MODULE, @@ -164,7 +158,7 @@ gck_password_class_init (GckPasswordClass *klass) /** * GckPassword:module: * - * The PKCS\#11 module that is requesting the password + * The PKCS#11 module that is requesting the password */ g_object_class_install_property (gobject_class, PROP_MODULE, g_param_spec_object ("module", "Module", "PKCS11 Module", @@ -173,7 +167,7 @@ gck_password_class_init (GckPasswordClass *klass) /** * GckPassword:token: * - * The PKCS\#11 token the password is for, if this is set then + * The PKCS#11 token the password is for, if this is set then * the GckPassword:object property will be %NULL */ g_object_class_install_property (gobject_class, PROP_TOKEN, @@ -183,7 +177,7 @@ gck_password_class_init (GckPasswordClass *klass) /** * GckPassword:key: * - * The PKCS\#11 key that the password is being requested for. If this + * The PKCS#11 key that the password is being requested for. If this * is set then the GckPassword:token property will be %NULL */ g_object_class_install_property (gobject_class, PROP_KEY, @@ -195,7 +189,7 @@ gck_password_class_init (GckPasswordClass *klass) * gck_password_get_module: * @self: the password object * - * Get the PKCS\#11 module that is requesting the password. + * Get the PKCS#11 module that is requesting the password. * * Returns: (transfer full): the module that is requesting the password, which * must be unreferenced after use @@ -214,7 +208,7 @@ gck_password_get_module (GckPassword *self) * gck_password_get_token: * @self: the password object * - * If the password request is to unlock a PKCS\#11 token, then this is the + * If the password request is to unlock a PKCS#11 token, then this is the * slot containing that token. * * Returns: (transfer full): the slot that contains the token, or %NULL if not @@ -234,7 +228,7 @@ gck_password_get_token (GckPassword *self) * gck_password_get_key: * @self: the password object * - * If the password request is to unlock a PKCS\#11 key, then this is the + * If the password request is to unlock a PKCS#11 key, then this is the * the object representing that key. * * Returns: (transfer full): the password is for this key, or %NULL if not diff --git a/gck/gck-session.c b/gck/gck-session.c index 99f7cdd..4c5fe08 100644 --- a/gck/gck-session.c +++ b/gck/gck-session.c @@ -1,4 +1,3 @@ -/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */ /* gck-session.h - the GObject PKCS#11 wrapper library Copyright (C) 2008, Stefan Walter @@ -32,18 +31,12 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gck-session - * @title: GckSession - * @short_description: Represents an open PKCS11 session. - * - * Before performing any PKCS11 operations, a session must be opened. This is - * analogous to an open database handle, or a file handle. - */ - -/** * GckSession: * * Represents an open PKCS11 session. + * + * Before performing any PKCS11 operations, a session must be opened. This is + * analogous to an open database handle, or a file handle. */ /** @@ -335,7 +328,7 @@ gck_session_class_init (GckSessionClass *klass) /** * GckSession:opening-flags: * - * Raw PKCS\#11 flags used to open the PKCS\#11 session. + * Raw PKCS#11 flags used to open the PKCS#11 session. */ g_object_class_install_property (gobject_class, PROP_OPENING_FLAGS, g_param_spec_ulong ("opening-flags", "Opening flags", "PKCS#11 open session flags", @@ -345,7 +338,7 @@ gck_session_class_init (GckSessionClass *klass) /** * GckSession:app-data: * - * Raw PKCS\#11 application data used to open the PKCS\#11 session. + * Raw PKCS#11 application data used to open the PKCS#11 session. */ g_object_class_install_property (gobject_class, PROP_APP_DATA, g_param_spec_pointer ("app-data", "App data", "PKCS#11 application data", @@ -587,11 +580,11 @@ gck_session_info_free (GckSessionInfo *session_info) /** * gck_session_from_handle: * @slot: The slot which the session belongs to. - * @session_handle: the raw PKCS\#11 handle of the session + * @session_handle: the raw PKCS#11 handle of the session * @options: Session options. Those which are used during opening a session have no effect. * - * Initialize a GckSession object from a raw PKCS\#11 session handle. - * Usually one would use the gck_slot_open_session() function to + * Initialize a session object from a raw PKCS#11 session handle. + * Usually one would use the [method@Slot.open_session] function to * create a session. * * Returns: (transfer full): the new GckSession object @@ -618,7 +611,7 @@ gck_session_from_handle (GckSlot *slot, * gck_session_get_handle: * @self: The session object. * - * Get the raw PKCS\#11 session handle from a GckSession object. + * Get the raw PKCS#11 session handle from a session object. * * Return value: The raw session handle. **/ @@ -633,7 +626,7 @@ gck_session_get_handle (GckSession *self) * gck_session_get_module: * @self: The session object. * - * Get the PKCS\#11 module to which this session belongs. + * Get the PKCS#11 module to which this session belongs. * * Returns: (transfer full): the module, which should be unreffed after use **/ @@ -648,7 +641,7 @@ gck_session_get_module (GckSession *self) * gck_session_get_slot: * @self: The session object. * - * Get the PKCS\#11 slot to which this session belongs. + * Get the PKCS#11 slot to which this session belongs. * * Return value: (transfer full): The slot, which should be unreffed after use. **/ @@ -709,7 +702,7 @@ gck_session_get_info (GckSession *self) * gck_session_get_state: * @self: the session * - * Get the session state. The state is the various PKCS\#11 CKS_XXX flags. + * Get the session state. The state is the various PKCS#11 CKS_XXX flags. * * Returns: the session state */ @@ -812,7 +805,7 @@ gck_session_set_interaction (GckSession *self, * @slot: the slot to open session on * @options: session options * @interaction: (nullable): optional interaction for logins or object authentication - * @cancellable: optional cancellation object + * @cancellable: (nullable): optional cancellation object * @error: location to place error or %NULL * * Open a session on the slot. This call may block for an indefinite period. @@ -915,11 +908,11 @@ perform_init_pin (InitPin *args) * @pin: (nullable) (array length=n_pin): the user's PIN, or %NULL for * protected authentication path * @n_pin: the length of the PIN - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error. * * Initialize the user's pin on this slot that this session is opened on. - * According to the PKCS\#11 standards, the session must be logged in with + * According to the PKCS#11 standards, the session must be logged in with * the CKU_SO user type. * * This call may block for an indefinite period. @@ -940,13 +933,13 @@ gck_session_init_pin (GckSession *self, const guchar *pin, gsize n_pin, * @self: Initialize PIN for this session's slot. * @pin: (nullable) (array length=n_pin): the user's PIN, or %NULL for protected authentication path * @n_pin: the length of the PIN - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @callback: Called when the operation completes. * @user_data: Data to pass to the callback. * * Initialize the user's pin on this slot that this session is opened on. - * According to the PKCS\#11 standards, the session must be logged in with - * the CKU_SO user type. + * According to the PKCS#11 standards, the session must be logged in with + * the `CKU_SO` user type. * * This call will return immediately and completes asynchronously. **/ @@ -1020,7 +1013,7 @@ perform_set_pin (SetPin *args) * @new_pin: (nullable) (array length=n_new_pin): the user's new PIN, or %NULL * for protected authentication path * @n_new_pin: The length of the PIN. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error. * * Change the user's pin on this slot that this session is opened on. @@ -1047,7 +1040,7 @@ gck_session_set_pin (GckSession *self, const guchar *old_pin, gsize n_old_pin, * @new_pin: (nullable) (array length=n_new_pin): the user's new PIN, or %NULL * for protected authentication path * @n_new_pin: the length of the new PIN - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @callback: Called when the operation completes. * @user_data: Data to pass to the callback. * @@ -1123,7 +1116,7 @@ perform_login (Login *args) * @pin: (nullable) (array length=n_pin): the user's PIN, or %NULL for * protected authentication path * @n_pin: The length of the PIN. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error. * * Login the user on the session. This call may block for @@ -1147,7 +1140,7 @@ gck_session_login (GckSession *self, gulong user_type, const guchar *pin, * @pin: (nullable) (array length=n_pin): the user's PIN, or %NULL for * protected authentication path * @n_pin: The length of the PIN. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @callback: Called when the operation completes. * @user_data: Data to pass to the callback. * @@ -1216,7 +1209,7 @@ perform_interactive (Interactive *args) * @self: session to use for login * @user_type: the type of login user * @interaction: (nullable): interaction to request PIN when necessary - * @cancellable: optional cancellation object, or %NULL + * @cancellable: (nullable): optional cancellation object, or %NULL * @error: location to return an error * * Login the user on the session requesting the password interactively @@ -1251,7 +1244,7 @@ gck_session_login_interactive (GckSession *self, * @self: session to use for login * @user_type: the type of login user * @interaction: (nullable): interaction to request PIN when necessary - * @cancellable: optional cancellation object, or %NULL + * @cancellable: (nullable): optional cancellation object, or %NULL * @callback: called when the operation completes * @user_data: data to pass to the callback * @@ -1317,7 +1310,7 @@ perform_logout (GckArguments *args) /** * gck_session_logout: * @self: Logout of this session. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error. * * Log out of the session. This call may block for an indefinite period. @@ -1368,8 +1361,6 @@ gck_session_logout_finish (GckSession *self, GAsyncResult *result, GError **erro } - - /* CREATE OBJECT */ typedef struct _CreateObject { @@ -1413,10 +1404,10 @@ perform_create_object (CreateObject *args) * gck_session_create_object: * @self: The session to create the object on. * @attrs: The attributes to create the object with. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error, or %NULL. * - * Create a new PKCS\#11 object. This call may block for an + * Create a new PKCS#11 object. This call may block for an * indefinite period. * * If the @attrs #GckAttributes is floating, it is consumed. @@ -1447,14 +1438,14 @@ gck_session_create_object (GckSession *self, GckAttributes *attrs, * gck_session_create_object_async: * @self: The session to create the object on. * @attrs: The attributes to create the object with. - * @cancellable: Optional cancellation object or %NULL. + * @cancellable: (nullable): Optional cancellation object or %NULL. * @callback: Called when the operation completes. * @user_data: Data to pass to the callback. * - * Create a new PKCS\#11 object. This call will return immediately + * Create a new PKCS#11 object. This call will return immediately * and complete asynchronously. * - * If the @attrs #GckAttributes is floating, it is consumed. + * If @attrs is a floating reference, it is consumed. **/ void gck_session_create_object_async (GckSession *self, GckAttributes *attrs, @@ -1481,7 +1472,7 @@ gck_session_create_object_async (GckSession *self, GckAttributes *attrs, * @result: The result passed to the callback. * @error: A location to return an error, or %NULL. * - * Get the result of creating a new PKCS\#11 object. + * Get the result of creating a new PKCS#11 object. * * Return value: (transfer full): the newly created object or %NULL if an error occurred **/ @@ -1498,7 +1489,6 @@ gck_session_create_object_finish (GckSession *self, GAsyncResult *result, GError } - /* FIND OBJECTS */ typedef struct _FindObjects { @@ -1581,14 +1571,14 @@ perform_find_objects (FindObjects *args) * gck_session_find_handles: * @self: the session to find objects on * @match: the attributes to match against objects - * @cancellable: optional cancellation object or %NULL + * @cancellable: (nullable): optional cancellation object or %NULL * @n_handles: location to return number of handles * @error: a location to return an error or %NULL * * Find the objects matching the passed attributes. This call may * block for an indefinite period. * - * If the @match #GckAttributes is floating, it is consumed. + * If @match is a floating reference, it is consumed. * * Returns: (transfer full) (array length=n_handles) (nullable): a list of * the matching objects, which may be empty @@ -1625,14 +1615,14 @@ gck_session_find_handles (GckSession *self, * gck_session_find_handles_async: * @self: the session to find objects on * @match: the attributes to match against the objects - * @cancellable: optional cancellation object or %NULL + * @cancellable: (nullable): optional cancellation object or %NULL * @callback: called when the operation completes * @user_data: data to pass to the callback * * Find the objects matching the passed attributes. This call will * return immediately and complete asynchronously. * - * If the @match #GckAttributes is floating, it is consumed. + * If @match is a floating reference, it is consumed. **/ void gck_session_find_handles_async (GckSession *self, @@ -1694,13 +1684,13 @@ gck_session_find_handles_finish (GckSession *self, * gck_session_find_objects: * @self: The session to find objects on. * @match: the attributes to match - * @cancellable: Optional cancellation object or %NULL. + * @cancellable: (nullable): Optional cancellation object or %NULL. * @error: A location to return an error or %NULL. * * Find the objects matching the passed attributes. This call may * block for an indefinite period. * - * If the @match #GckAttributes is floating, it is consumed. + * If @match is a floating reference, it is consumed. * * Returns: (transfer full) (element-type Gck.Object): a list of the matching * objects, which may be empty @@ -1733,7 +1723,7 @@ gck_session_find_objects (GckSession *self, * gck_session_find_objects_async: * @self: The session to find objects on. * @match: The attributes to match. - * @cancellable: Optional cancellation object or %NULL. + * @cancellable: (nullable): Optional cancellation object or %NULL. * @callback: Called when the operation completes. * @user_data: Data to pass to the callback. * @@ -1796,7 +1786,7 @@ gck_session_find_objects_finish (GckSession *self, * * Setup an enumerator for listing matching objects available via this session. * - * If the @match #GckAttributes is floating, it is consumed. + * If @match is a floating reference, it is consumed. * * This call will not block but will return an enumerator immediately. * @@ -1864,13 +1854,13 @@ perform_generate_key_pair (GenerateKeyPair *args) * @private_attrs: Additional attributes for the generated private key. * @public_key: (optional) (out): location to return the resulting public key * @private_key: (optional) (out): location to return the resulting private key. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error, or %NULL. * - * Generate a new key pair of public and private keys. This call may block for an - * indefinite period. + * Generate a new key pair of public and private keys. This call may block for + * an indefinite period. * - * If the @public_attrs and/or @private_attrs #GckAttributes is floating, it is + * If @public_attrs and/or @private_attrs is a floating reference, it is * consumed. * * Return value: %TRUE if the operation succeeded. @@ -1893,13 +1883,13 @@ gck_session_generate_key_pair (GckSession *self, gulong mech_type, * @private_attrs: Additional attributes for the generated private key. * @public_key: (optional) (out): a location to return the resulting public key * @private_key: (optional) (out): a location to return the resulting private key - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error, or %NULL. * * Generate a new key pair of public and private keys. This call may block for an * indefinite period. * - * If the @public_attrs and/or @private_attrs #GckAttributes is floating, it is + * If @public_attrs and/or @private_attrs is a floating reference, it is * consumed. * * Return value: %TRUE if the operation succeeded. @@ -1949,14 +1939,14 @@ gck_session_generate_key_pair_full (GckSession *self, * @mechanism: The mechanism to use for key generation. * @public_attrs: Additional attributes for the generated public key. * @private_attrs: Additional attributes for the generated private key. - * @cancellable: Optional cancellation object or %NULL. + * @cancellable: (nullable): Optional cancellation object or %NULL. * @callback: Called when the operation completes. * @user_data: Data to pass to the callback. * * Generate a new key pair of public and private keys. This call will * return immediately and complete asynchronously. * - * If the @public_attrs and/or @private_attrs #GckAttributes is floating, it is + * If @public_attrs and/or @private_attrs is a floating reference, it is * consumed. **/ void @@ -2073,7 +2063,7 @@ perform_wrap_key (WrapKey *args) * @mech_type: The mechanism type to use for wrapping. * @wrapped: The key to wrap. * @n_result: A location in which to return the length of the wrapped data. - * @cancellable: A #GCancellable or %NULL + * @cancellable: (nullable): A #GCancellable or %NULL * @error: A location to return an error, or %NULL. * * Wrap a key into a byte stream. This call may block for an @@ -2097,7 +2087,7 @@ gck_session_wrap_key (GckSession *self, GckObject *key, gulong mech_type, * @mechanism: The mechanism to use for wrapping. * @wrapped: The key to wrap. * @n_result: A location in which to return the length of the wrapped data. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error, or %NULL. * * Wrap a key into a byte stream. This call may block for an @@ -2143,7 +2133,7 @@ gck_session_wrap_key_full (GckSession *self, GckObject *wrapper, GckMechanism *m * @wrapper: The key to use for wrapping. * @mechanism: The mechanism to use for wrapping. * @wrapped: The key to wrap. - * @cancellable: Optional cancellation object or %NULL. + * @cancellable: (nullable): Optional cancellation object or %NULL. * @callback: Called when the operation completes. * @user_data: Data to pass to the callback. * @@ -2259,13 +2249,13 @@ perform_unwrap_key (UnwrapKey *args) * @input: (array length=n_input): the wrapped data as a byte stream * @n_input: The length of the wrapped data. * @attrs: Additional attributes for the unwrapped key. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error, or %NULL. * * Unwrap a key from a byte stream. This call may block for an * indefinite period. * - * If the @attrs #GckAttributes is floating, it is consumed. + * If @attrs is a floating reference, it is consumed. * * Returns: (transfer full): the new unwrapped key or %NULL if the * operation failed @@ -2292,13 +2282,13 @@ gck_session_unwrap_key (GckSession *self, * @input: (array length=n_input): the wrapped data as a byte stream * @n_input: The length of the wrapped data. * @attrs: Additional attributes for the unwrapped key. - * @cancellable: Optional cancellation object, or %NULL. + * @cancellable: (nullable): Optional cancellation object, or %NULL. * @error: A location to return an error, or %NULL. * * Unwrap a key from a byte stream. This call may block for an * indefinite period. * - * If the @attrs #GckAttributes is floating, it is consumed. + * If @attrs is a floating reference, it is consumed. * * Returns: (transfer full): the new unwrapped key or %NULL if the operation * failed @@ -2347,14 +2337,14 @@ gck_session_unwrap_key_full (GckSession *self, * @input: (array length=n_input): the wrapped data as a byte stream * @n_input: The length of the wrapped data. * @attrs: Additional attributes for the unwrapped key. - * @cancellable: Optional cancellation object or %NULL. + * @cancellable: (nullable): Optional cancellation object or %NULL. * @callback: Called when the operation completes. * @user_data: Data to pass to the callback. * * Unwrap a key from a byte stream. This call will * return immediately and complete asynchronously. * - * If the @attrs #GckAttributes is floating, it is consumed. + * If @attrs is a floating reference, it is consumed. **/ void gck_session_unwrap_key_async (GckSession *self, diff --git a/gck/gck-slot.c b/gck/gck-slot.c index 435fe61..8ec121e 100644 --- a/gck/gck-slot.c +++ b/gck/gck-slot.c @@ -31,18 +31,13 @@ #include <time.h> /** - * SECTION:gck-slot - * @title: GckSlot - * @short_description: Represents a PKCS\#11 slot that can contain a token. - * - * A PKCS11 slot can contain a token. As an example, a slot might be a card reader, and the token - * the card. If the PKCS\#11 module is not a hardware driver, often the slot and token are equivalent. - */ - -/** * GckSlot: * - * Represents a PKCS11 slot. + * Represents a PKCS#11 slot that can contain a token. + * + * A PKCS#11 slot can contain a token. As an example, a slot might be a card + * reader, and the token the card. If the PKCS#11 module is not a hardware + * driver, often the slot and token are equivalent. */ enum { @@ -421,7 +416,7 @@ gck_mechanisms_check (GArray *mechanisms, ...) * @slot2: (type Gck.Slot): a pointer to the second #GckSlot * * Checks equality of two slots. Two GckSlot objects can point to the same - * underlying PKCS\#11 slot. + * underlying PKCS#11 slot. * * Return value: %TRUE if slot1 and slot2 are equal. * %FALSE if either is not a GckSlot. @@ -470,9 +465,9 @@ gck_slot_hash (gconstpointer slot) /** * gck_slot_from_handle: * @module: The module that this slot is on. - * @slot_id: The raw PKCS\#11 handle or slot id of this slot. + * @slot_id: The raw PKCS#11 handle or slot id of this slot. * - * Create a new GckSlot object for a raw PKCS\#11 handle. + * Create a new GckSlot object for a raw PKCS#11 handle. * * Returns: (transfer full): The new GckSlot object. **/ @@ -490,7 +485,7 @@ gck_slot_from_handle (GckModule *module, * gck_slot_get_handle: * @self: The slot to get the handle of. * - * Get the raw PKCS\#11 handle of a slot. + * Get the raw PKCS#11 handle of a slot. * * Return value: the raw CK_SLOT_ID handle **/ @@ -979,9 +974,9 @@ gck_slot_open_session (GckSlot *self, * gck_slot_open_session_full: (skip) * @self: The slot to open a session on. * @options: The options to open the new session with. - * @pkcs11_flags: Additional raw PKCS\#11 flags. + * @pkcs11_flags: Additional raw PKCS#11 flags. * @app_data: Application data for notification callback. - * @notify: PKCS\#11 notification callback. + * @notify: PKCS#11 notification callback. * @cancellable: Optional cancellation object, or %NULL. * @error: A location to return an error, or %NULL. * @@ -1054,9 +1049,9 @@ on_open_session_complete (GObject *source, * gck_slot_open_session_full_async: (skip) * @self: The slot to open a session on. * @options: Options to open the new session with. - * @pkcs11_flags: Additional raw PKCS\#11 flags. + * @pkcs11_flags: Additional raw PKCS#11 flags. * @app_data: Application data for notification callback. - * @notify: PKCS\#11 notification callback. + * @notify: PKCS#11 notification callback. * @cancellable: (nullable): Optional cancellation object, or %NULL. * @callback: Called when the operation completes. * @user_data: Data to pass to the callback. @@ -1122,7 +1117,7 @@ gck_slot_open_session_finish (GckSlot *self, GAsyncResult *result, GError **erro * @self: the slot to match * @uri: the uri to match against the slot * - * Check whether the PKCS\#11 URI matches the slot + * Check whether the PKCS#11 URI matches the slot * * Returns: whether the URI matches or not */ diff --git a/gck/gck-uri.c b/gck/gck-uri.c index 7187042..bd524a4 100644 --- a/gck/gck-uri.c +++ b/gck/gck-uri.c @@ -35,38 +35,16 @@ #include <stdlib.h> /** - * SECTION:gck-uri - * @title: PKCS11 URIs - * @short_description: Parsing and building PKCS\#11 URIs. - * - * <ulink href='http://tools.ietf.org/html/draft-pechanec-pkcs11uri-03'>PKCS\#11 URIs</ulink> - * are a standard for referring to PKCS\#11 modules, tokens, or objects. What the - * PKCS\#11 URI refers to depends on the context in which it is used. - * - * A PKCS\#11 URI can always resolve to more than one object, token or module. A - * PKCS\#11 URI that refers to a token, would (when used in a context that expects - * objects) refer to all the token on that module. - * - * In most cases the parsing or building of URIs is handled elsewhere in the GCK - * library. For example to enumerate objects that match a PKCS\#11 URI use the - * gck_modules_enumerate_uri() function. - * - * To parse a PKCS\#11 URI use the gck_uri_parse() function passing in the type of - * context in which you're using the URI. To build a URI use the gck_uri_build() - * function. - **/ - -/** * GckUriData: - * @any_unrecognized: whether any parts of the PKCS\#11 URI were unsupported or unrecognized. - * @module_info: information about the PKCS\#11 modules matching the URI. - * @token_info: information about the PKCS\#11 tokens matching the URI. - * @attributes: information about the PKCS\#11 objects matching the URI. + * @any_unrecognized: whether any parts of the PKCS#11 URI were unsupported or unrecognized. + * @module_info: information about the PKCS#11 modules matching the URI. + * @token_info: information about the PKCS#11 tokens matching the URI. + * @attributes: information about the PKCS#11 objects matching the URI. * - * Information about the contents of a PKCS\#11 URI. Various fields may be %NULL + * Information about the contents of a PKCS#11 URI. Various fields may be %NULL * depending on the context that the URI was parsed for. * - * Since PKCS\#11 URIs represent a set which results from the intersections of + * Since PKCS#11 URIs represent a set which results from the intersections of * all of the URI parts, if @any_recognized is set to %TRUE then usually the URI * should be treated as not matching anything. */ @@ -79,7 +57,7 @@ * @GCK_URI_WITH_VERSION: the URI has specific version numbers for module and/or token * @GCK_URI_FOR_ANY: parse all recognized components of the URI. * - * Which parts of the PKCS\#11 URI will be parsed or formatted. These can be + * Which parts of the PKCS#11 URI will be parsed or formatted. These can be * combined. */ @@ -109,7 +87,7 @@ * @GCK_URI_BAD_VERSION: bad URI version component * @GCK_URI_NOT_FOUND: piece of the URI was not found * - * Various error codes used with PKCS\#11 URIs + * Various error codes used with PKCS#11 URIs */ /** @@ -186,7 +164,7 @@ gck_uri_data_new (void) * @flags: the context in which the URI will be used. * @error: a #GError, or %NULL. * - * Parse a PKCS\#11 URI for use in a given context. + * Parse a PKCS#11 URI for use in a given context. * * The result will contain the fields that are relevant for * the given context. See #GckUriData for more info. @@ -266,10 +244,10 @@ gck_uri_parse (const gchar *string, GckUriFlags flags, GError **error) * @uri_data: the info to build the URI from. * @flags: The context that the URI is for * - * Build a PKCS\#11 URI. The various parts relevant to the flags + * Build a PKCS#11 URI. The various parts relevant to the flags * specified will be used to build the URI. * - * Return value: a newly allocated string containing a PKCS\#11 URI. + * Return value: a newly allocated string containing a PKCS#11 URI. */ gchar* gck_uri_build (GckUriData *uri_data, GckUriFlags flags) diff --git a/gcr/gcr-certificate-chain.c b/gcr/gcr-certificate-chain.c index 1793869..f34eae8 100644 --- a/gcr/gcr-certificate-chain.c +++ b/gcr/gcr-certificate-chain.c @@ -33,11 +33,9 @@ #include "egg/egg-error.h" /** - * SECTION:gcr-certificate-chain - * @title: GcrCertificateChain - * @short_description: A certificate chain + * GcrCertificateChain: * - * #GcrCertificateChain represents a chain of certificates, normally used to + * Represents a chain of certificates, normally used to * validate the trust in a certificate. An X.509 certificate chain has one * endpoint certificate (the one for which trust is being verified) and then * in turn the certificate that issued each previous certificate in the chain. @@ -49,32 +47,25 @@ * The order of certificates in the chain should be first the endpoint * certificates and then the signing certificates. * - * Create a new certificate chain with gcr_certificate_chain_new() and then - * add the certificates with gcr_certificate_chain_add(). + * Create a new certificate chain with [ctor@CertificateChain.new] and then + * add the certificates with [method@CertificateChain.add]. * - * You can then use gcr_certificate_chain_build() to build the remainder of - * the chain. This will lookup missing certificates in PKCS\#11 modules and + * You can then use [method@CertificateChain.build] to build the remainder of + * the chain. This will lookup missing certificates in PKCS#11 modules and * also check that each certificate in the chain is the signer of the previous * one. If a trust anchor, pinned certificate, or self-signed certificate is * found, then the chain is considered built. Any extra certificates are * removed from the chain. * * Once the certificate chain has been built, you can access its status - * through gcr_certificate_chain_get_status(). The status signifies whether + * through [method@CertificateChain.get_status]. The status signifies whether * the chain is anchored on a trust root, self-signed, incomplete etc. See - * #GcrCertificateChainStatus for information on the various statuses. + * [enum@CertificateChainStatus] for information on the various statuses. * * It's important to understand that the building of a certificate chain is * merely the first step towards verifying trust in a certificate. */ - -/** - * GcrCertificateChain: - * - * A chain of certificates. - */ - /** * GcrCertificateChainClass: * @parent_class: The parent class @@ -518,7 +509,7 @@ gcr_certificate_chain_class_init (GcrCertificateChainClass *klass) * @GCR_CERTIFICATE_CHAIN_NO_LOOKUPS: If this flag is specified then no * lookups for anchors or pinned certificates are done, and the resulting chain * will be neither anchored or pinned. Additionally no missing certificate - * authorities are looked up in PKCS\#11. + * authorities are looked up in PKCS#11. * * Flags to be used with the gcr_certificate_chain_build() operation. */ @@ -677,7 +668,7 @@ gcr_certificate_chain_get_certificate (GcrCertificateChain *self, guint index) * Complete a certificate chain. Once a certificate chain has been built * its status can be examined. * - * This operation will lookup missing certificates in PKCS\#11 + * This operation will lookup missing certificates in PKCS#11 * modules and also that each certificate in the chain is the signer of the * previous one. If a trust anchor, pinned certificate, or self-signed certificate * is found, then the chain is considered built. Any extra certificates are @@ -699,7 +690,7 @@ gcr_certificate_chain_get_certificate (GcrCertificateChain *self, guint index) * If the %GCR_CERTIFICATE_CHAIN_NO_LOOKUPS flag is specified then no * lookups for anchors or pinned certificates are done, and the resulting chain * will be neither anchored or pinned. Additionally no missing certificate - * authorities are looked up in PKCS\#11 + * authorities are looked up in PKCS#11 * * This call will block, see gcr_certificate_chain_build_async() for the * asynchronous version. @@ -749,7 +740,7 @@ gcr_certificate_chain_build (GcrCertificateChain *self, * Complete a certificate chain. Once a certificate chain has been built * its status can be examined. * - * This will lookup missing certificates in PKCS\#11 + * This will lookup missing certificates in PKCS#11 * modules and also that each certificate in the chain is the signer of the * previous one. If a trust anchor, pinned certificate, or self-signed certificate * is found, then the chain is considered built. Any extra certificates are @@ -771,7 +762,7 @@ gcr_certificate_chain_build (GcrCertificateChain *self, * If the %GCR_CERTIFICATE_CHAIN_NO_LOOKUPS flag is specified then no * lookups for anchors or pinned certificates are done, and the resulting chain * will be neither anchored or pinned. Additionally no missing certificate - * authorities are looked up in PKCS\#11 + * authorities are looked up in PKCS#11 * * When the operation is finished, @callback will be called. You can then call * gcr_certificate_chain_build_finish() to get the result of the operation. diff --git a/gcr/gcr-certificate-request.c b/gcr/gcr-certificate-request.c index 9736ce8..dc3e936 100644 --- a/gcr/gcr-certificate-request.c +++ b/gcr/gcr-certificate-request.c @@ -34,31 +34,22 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gcr-certificate-request - * @title: GcrCertificateRequest - * @short_description: Represents a certificate request + * GcrCertificateRequest: * - * This is an object that allows creation of certificate requests. A - * certificate request is sent to a certificate authority to request an - * X.509 certificate. + * An object that allows creation of certificate requests. A certificate + * request is sent to a certificate authority to request an X.509 certificate. * - * Use gcr_certificate_request_prepare() to create a blank certificate + * Use [ctor@CertificateRequest.prepare] to create a blank certificate * request for a given private key. Set the common name on the certificate - * request with gcr_certificate_request_set_cn(), and then sign the request - * with gcr_certificate_request_complete_async(). - */ - -/** - * GcrCertificateRequest: - * - * Represents a certificate request. + * request with [method@CertificateRequest.set_cn], and then sign the request + * with [method@CertificateRequest.complete_async]. */ /** * GcrCertificateRequestFormat: - * @GCR_CERTIFICATE_REQUEST_PKCS10: certificate request is in PKCS\#10 format + * @GCR_CERTIFICATE_REQUEST_PKCS10: certificate request is in PKCS#10 format * - * The format of a certificate request. Currently only PKCS\#10 is supported. + * The format of a certificate request. Currently only PKCS#10 is supported. */ struct _GcrCertificateRequest { @@ -211,7 +202,7 @@ gcr_certificate_request_class_init (GcrCertificateRequestClass *klass) } /** - * gcr_certificate_request_prepare: + * gcr_certificate_request_prepare: (constructor) * @format: the format for the certificate request * @private_key: the private key the the certificate is being requested for * @@ -693,12 +684,13 @@ gcr_certificate_request_complete_finish (GcrCertificateRequest *self, * @length: location to place length of returned data * * Encode the certificate request. It must have been completed with - * gcr_certificate_request_complete() or gcr_certificate_request_complete_async() + * [method@CertificateRequest.complete] or + * [method@CertificateRequest.complete_async]. * * If @textual is %FALSE, the output is a DER encoded certificate request. * - * If @textual is %TRUE, the output is encoded as text. For PKCS\#10 requests this - * is done using the OpenSSL style PEM encoding. + * If @textual is %TRUE, the output is encoded as text. For PKCS#10 requests + * this is done using the OpenSSL style PEM encoding. * * Returns: (transfer full) (array length=length): the encoded certificate request */ @@ -742,10 +734,10 @@ gcr_certificate_request_encode (GcrCertificateRequest *self, /** * gcr_certificate_request_capable: * @private_key: a private key - * @cancellable: cancellation object + * @cancellable: (nullable): cancellation object * @error: location to place an error * - * Check whether #GcrCertificateRequest is capable of creating a request + * Check whether [class@CertificateRequest] is capable of creating a request * for the given @private_key. * * Returns: whether a request can be created @@ -767,12 +759,12 @@ gcr_certificate_request_capable (GckObject *private_key, /** * gcr_certificate_request_capable_async: * @private_key: a private key - * @cancellable: cancellation object + * @cancellable: (nullable): cancellation object * @callback: will be called when the operation completes * @user_data: data to be passed to callback * - * Asynchronously check whether #GcrCertificateRequest is capable of creating - * a request for the given @private_key. + * Asynchronously check whether [class@CertificateRequest] is capable of + * creating a request for the given @private_key. */ void gcr_certificate_request_capable_async (GckObject *private_key, @@ -794,7 +786,7 @@ gcr_certificate_request_capable_async (GckObject *private_key, * @result: asynchronous result * @error: location to place an error * - * Get the result for asynchronously check whether #GcrCertificateRequest is + * Get the result for asynchronously check whether [class@CertificateRequest] is * capable of creating a request for the given @private_key. * * Returns: whether a request can be created diff --git a/gcr/gcr-certificate.c b/gcr/gcr-certificate.c index 22bfabb..dd2b666 100644 --- a/gcr/gcr-certificate.c +++ b/gcr/gcr-certificate.c @@ -37,19 +37,18 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gcr-certificate - * @title: GcrCertificate - * @short_description: Represents an X.509 certificate + * GcrCertificate: * - * This is an interface that represents an X.509 certificate. Objects can - * implement this interface to make a certificate usable with the GCR - * library. + * An interface that represents an X.509 certificate. + * + * Objects can implement this interface to make a certificate usable with the + * GCR library. * * Various methods are available to parse out relevant bits of the certificate. * However no verification of the validity of a certificate is done here. Use * your favorite crypto library to do this. * - * You can use #GcrSimpleCertificate to simply load a certificate for which + * You can use [class@SimpleCertificate] to simply load a certificate for which * you already have the raw certificate data. * * The #GcrCertificate interface has several properties that must be implemented. @@ -63,12 +62,6 @@ */ /** - * GcrCertificate: - * - * An object which holds a certificate. - */ - -/** * GcrCertificateIface: * @parent: the parent interface type * @get_der_data: a method which returns the RAW der data of the certificate @@ -80,7 +73,7 @@ * GCR_CERTIFICATE_COLUMNS: * * The columns that are valid for a certificate. This is to be used with - * the #GcrTreeSelector or #GcrCollectionModel. + * the [class@TreeSelector] or [class@CollectionModel]. * * This is an array of #GcrColumn, owned by the gcr library. */ diff --git a/gcr/gcr-collection.c b/gcr/gcr-collection.c index 5d9ff69..c4c05e5 100644 --- a/gcr/gcr-collection.c +++ b/gcr/gcr-collection.c @@ -22,22 +22,15 @@ #include "gcr-collection.h" /** - * SECTION:gcr-collection - * @title: GcrCollection - * @short_description: A collection of objects. - * - * A #GcrCollection is used to group a set of objects. This is an abstract - * interface which can be used to determine which objects show up in a selector - * or other user interface element. - * - * Use gcr_simple_collection_new() to create a concrete implementation of this - * interface which you can add objects to. - */ - -/** * GcrCollection: * * A #GcrCollection is used to group a set of objects. + * + * This is an abstract interface which can be used to determine which objects + * show up in a selector or other user interface element. + * + * Use [ctor@SimpleCollection.new] to create a concrete implementation of this + * interface which you can add objects to. */ enum { diff --git a/gcr/gcr-column.c b/gcr/gcr-column.c index e7e1b6e..099e78e 100644 --- a/gcr/gcr-column.c +++ b/gcr/gcr-column.c @@ -24,21 +24,12 @@ #include "gcr-column.h" /** - * SECTION:gcr-column - * @title: GcrColumn - * @short_description: Column information for selector or model. - * - * A #GcrColumn is used with #GcrTreeSelector or #GcrCollectionModel to define - * the columns to display. - */ - -/** * GcrColumnFlags: * @GCR_COLUMN_NONE: No column flags * @GCR_COLUMN_HIDDEN: Don't display this column. * @GCR_COLUMN_SORTABLE: This column is sortable. * - * Flags to be used with #GcrColumn + * Flags to be used with a [struct@Column]. */ /** @@ -53,12 +44,13 @@ * are the same. * @user_data: User data associated with the column * - * Represents a column to display in a #GcrCollectionModel or #GcrTreeSelector. + * Represents a column to display in a `GcrCollectionModel` or + * `GcrTreeSelector`. * * The label should be set as a translatable string with a context of - * <code>"column"</code>. This should be done with with this macro: + * `"column"`. This should be done with with this macro: * - * <informalexample><programlisting> + * ``` * NC_("column", "My Column Name") - * </programlisting></informalexample> + * ``` */ diff --git a/gcr/gcr-comparable.c b/gcr/gcr-comparable.c index e2de7e0..91d54e9 100644 --- a/gcr/gcr-comparable.c +++ b/gcr/gcr-comparable.c @@ -24,18 +24,9 @@ #include <string.h> /** - * SECTION:gcr-comparable - * @title: GcrComparable - * @short_description: Interface for comparing objects - * - * The #GcrComparable interface is implemented by objects when they should be - * comparable against one another. - */ - -/** * GcrComparable: * - * The #GcrComparable interface is implemented by comparable objects. + * An interface for comparing objects */ /** @@ -43,7 +34,7 @@ * @parent: type interface * @compare: Compare whether tow objects represent the same thing. * - * The interface to implement for #GcrComparable + * The interface to implement for [iface@Comparable] */ typedef GcrComparableIface GcrComparableInterface; diff --git a/gcr/gcr-filter-collection.c b/gcr/gcr-filter-collection.c index c82ec83..c62abae 100644 --- a/gcr/gcr-filter-collection.c +++ b/gcr/gcr-filter-collection.c @@ -25,12 +25,12 @@ #include <string.h> /** - * SECTION:gcr-filter-collection - * @title: GcrFilterCollection - * @short_description: A collection which filters a GcrCollection + * GcrFilterCollection: + * + * A collection which filters a [iface@Collection]. * - * An implementation of #GcrCollection which filters objects from another - * underlying collection. Use gcr_filter_collection_new_with_callback() + * An implementation of [iface@Collection] which filters objects from another + * underlying collection. Use [ctor@FilterCollection.new_with_callback] * to create a new filter collection. * * The callback will determine the criteria for whether an object shows through @@ -38,16 +38,10 @@ */ /** - * GcrFilterCollection: - * - * A filter implementation of #GcrCollection. - */ - -/** * GcrFilterCollectionClass: * @parent_class: the parent class * - * The class for #GcrFilterCollection. + * The class struct for [class@FilterCollection]. */ /** @@ -55,7 +49,7 @@ * @object: object to filter * @user_data: user data passed to the callback * - * A function which is called by #GcrFilterCollection in order to determine + * A function which is called by [class@FilterCollection] in order to determine * whether an object should show through the filter or not. * * Returns: %TRUE if an object should be included in the filtered collection diff --git a/gcr/gcr-fingerprint.c b/gcr/gcr-fingerprint.c index 235cdf7..c2d314f 100644 --- a/gcr/gcr-fingerprint.c +++ b/gcr/gcr-fingerprint.c @@ -32,29 +32,19 @@ #include <glib.h> /** - * SECTION:gcr-fingerprint - * @title: Key Fingerprints - * @short_description: Fingerprints for public and private keys - * - * These functions generate key fingerprints for public keys, certificates and - * key data. The fingerprints are created so that they they will be identical - * for a key and its corresponding certificate. - * - * Note that in the case of certificates these are not fingerprints of the - * actual certificate data, but rather of the public key contained in a - * certificate. - * - * These fingerprints are created using the subjectPublicKeyInfo ASN.1 structure. - */ - -/** * gcr_fingerprint_from_subject_public_key_info: * @key_info: (array length=n_key_info): DER encoded subjectPublicKeyInfo structure * @n_key_info: length of DER encoded structure * @checksum_type: the type of fingerprint to create * @n_fingerprint: (out): the length of fingerprint returned * - * Create a key fingerprint for a DER encoded subjectPublicKeyInfo. + * Create a key fingerprint for a DER encoded subjectPublicKeyInfo. The + * fingerprint is created so that it will be identical for a key and its + * corresponding certificate. + * + * Note that in the case of certificates this is not a fingerprint of the + * actual certificate data, but rather of the public key contained in a + * certificate. * * Returns: (transfer full) (nullable) (array length=n_fingerprint): the * fingerprint or %NULL if the input was invalid. diff --git a/gcr/gcr-import-interaction.c b/gcr/gcr-import-interaction.c index 5fafa4c..b8da073 100644 --- a/gcr/gcr-import-interaction.c +++ b/gcr/gcr-import-interaction.c @@ -24,20 +24,12 @@ #include "gcr-import-interaction.h" /** - * SECTION:gcr-import-interaction - * @title: GcrImportInteraction - * @short_description: User interaction during importing + * GcrImportInteraction: * * This is an interface implemented by a caller performing an import. It allows * the importer to ask the caller for further information about the import. * - * It must be implemented on a derived class of #GTlsInteraction - */ - -/** - * GcrImportInteraction: - * - * Interface implemented by the caller performing an import. + * It must be implemented on a derived class of [class@Gio.TlsInteraction] */ /** @@ -48,7 +40,7 @@ * @supplement_async: method which asynchronously supplements attributes before import * @supplement_finish: method which completes @supplement_async * - * Interface implemented by implementations of #GcrImportInteraction. + * Interface implemented by implementations of [iface@ImportInteraction]. */ typedef GcrImportInteractionIface GcrImportInteractionInterface; diff --git a/gcr/gcr-importer.c b/gcr/gcr-importer.c index 0a119e8..802ded0 100644 --- a/gcr/gcr-importer.c +++ b/gcr/gcr-importer.c @@ -33,30 +33,23 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gcr-importer - * @title: GcrImporter - * @short_description: Import certificates and keys + * GcrImporter: * - * An interface which allows importing of certificates and keys. Each - * #GcrImporter is registered with a set of PKCS\#11 attributes to match - * stuff that it can import. + * An interface which allows importing of certificates and keys. Each importer + * is registered with a set of PKCS#11 attributes to match stuff that it can + * import. * - * An importer gets passed a #GcrParser and accesses the currently parsed + * An importer gets passed a [class@Parser] and accesses the currently parsed * item. To create a set of importers that can import the currently parsed - * item in a #GcrParser, use gcr_importer_create_for_parsed(). The list of + * item in a parser, use [func@Importer.create_for_parsed]. The list of * importers returned has the parsed item queued for import. * - * To queue additional items with a importer use gcr_importer_queue_for_parsed(). - * In addition you can try and queue an additional item with a set of importers - * using the gcr_importer_queue_and_filter_for_parsed(). - * - * To start the import use gcr_importer_import() or the async variants. - */ - -/** - * GcrImporter: + * To queue additional items with a importer use + * [method@Importer.queue_for_parsed]. In addition you can try and queue an + * additional item with a set of importers using the + * [func@Importer.queue_and_filter_for_parsed]. * - * Imports certificates and keys + * To start the import, use [method@Importer.import] or its async variants. */ /** @@ -64,9 +57,9 @@ * @parent: parent interface * @create_for_parsed: implementation of gcr_importer_create_for_parsed(), required * @queue_for_parsed: implementation of gcr_importer_queue_for_parsed(), required - * @import_sync: optional implemantionon of gcr_importer_import() - * @import_async: implementation of gcr_importer_import_async(), required - * @import_finish: implementation of gcr_importer_import_finish() + * @import_sync: optional implementation of [method@Importer.import] + * @import_async: implementation of [method@Importer.import_async], required + * @import_finish: implementation of [method@Importer.import_finish] * * Interface implemented for a #GcrImporter. */ @@ -282,7 +275,7 @@ gcr_importer_create_for_parsed (GcrParsed *parsed) * @parsed: a parsed item to import * * Queues an additional item to be imported. The parsed item is represented - * by the state of the #GcrParser at the time of calling this method. + * by the state of the [class@Parser] at the time of calling this method. * * If the parsed item is incompatible with the importer, then this will * fail and the item will not be queued. @@ -545,7 +538,7 @@ gcr_importer_set_interaction (GcrImporter *importer, /** * gcr_importer_register_well_known: * - * Register built-in PKCS\#11 and GnuPG importers. + * Register built-in PKCS#11 and GnuPG importers. */ void gcr_importer_register_well_known (void) diff --git a/gcr/gcr-library.c b/gcr/gcr-library.c index 399c7e2..44460ee 100644 --- a/gcr/gcr-library.c +++ b/gcr/gcr-library.c @@ -37,30 +37,19 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gcr-library - * @title: Library Utilities - * @short_description: Library utilities such as version checks - * - * Basic library utilities such as version checks. - */ - -/** * GCR_CHECK_VERSION: * @major: the major version to check for * @minor: the minor version to check for * @micro: the micro version to check for * - * Checks the version of the Gcr libarry that is being compiled + * Checks the version of the Gcr library that is being compiled * against. * - * <example> - * <title>Checking the version of the Gcr library</title> - * <programlisting> + * ``` * #if !GCR_CHECK_VERSION (3, 0, 0) * #warning Old Gcr version, disabling functionality * #endif - * </programlisting> - * </example> + * ``` * * Returns: %TRUE if the version of the Gcr header files * is the same as or newer than the passed-in version. @@ -84,35 +73,6 @@ * The micro version number of the Gcr library. */ -/** - * SECTION:gcr-pkcs11 - * @title: Library PKCS#11 - * @short_description: functions for manipulating GCR library global settings. - * - * Manage or lookup various global aspesct and settings of the library. - * - * The GCR library maintains a global list of PKCS\#11 modules to use for - * its various lookups and storage operations. Each module is represented by - * a GckModule object. You can examine this list by using - * gcr_pkcs11_get_modules(). - * - * The list is configured automatically by looking for system installed - * PKCS\#11 modules. It's not not normally necessary to modify this list. But - * if you have special needs, you can use the gcr_pkcs11_set_modules() and - * gcr_pkcs11_add_module() to do so. - * - * Trust assertions are stored and looked up in specific PKCS\#11 slots. - * You can examine this list with gcr_pkcs11_get_trust_lookup_slots() - */ - -/** - * SECTION:gcr-private - * @title: Private declarations - * @short_description: private declarations to supress warnings. - * - * This section is only here to supress warnings, and should not be displayed. - */ - G_LOCK_DEFINE_STATIC (modules); static GList *all_modules = NULL; static gboolean initialized_modules = FALSE; @@ -272,7 +232,7 @@ on_initialize_registered (GObject *object, * @callback: callback which will be called when the operation completes * @user_data: data passed to the callback * - * Asynchronously initialize the registered PKCS\#11 modules. + * Asynchronously initialize the registered PKCS#11 modules. */ void gcr_pkcs11_initialize_async (GCancellable *cancellable, @@ -304,7 +264,7 @@ gcr_pkcs11_initialize_async (GCancellable *cancellable, * @result: the asynchronous result * @error: location to place an error on failure * - * Complete the asynchronous operation to initialize the registered PKCS\#11 + * Complete the asynchronous operation to initialize the registered PKCS#11 * modules. * * Returns: whether the operation was successful or not. @@ -323,11 +283,10 @@ gcr_pkcs11_initialize_finish (GAsyncResult *result, * @cancellable: optional cancellable used to cancel the operation * @error: location to place an error on failure * - * Asynchronously initialize the registered PKCS\#11 modules. + * Asynchronously initialize the registered PKCS#11 modules. * * Returns: whether the operation was successful or not. */ - gboolean gcr_pkcs11_initialize (GCancellable *cancellable, GError **error) @@ -366,11 +325,11 @@ gcr_pkcs11_initialize (GCancellable *cancellable, /** * gcr_pkcs11_get_modules: * - * List all the PKCS\#11 modules that are used by the GCR library. - * Each module is a #GckModule object. + * List all the PKCS#11 modules that are used by the GCR library. + * Each module is a [class@Gck.Module] object. * - * An empty list of modules will be returned if gcr_pkcs11_set_modules(), - * or gcr_pkcs11_initialize() has not yet run. + * An empty list of modules will be returned if [func@pkcs11_set_modules], + * or [func@pkcs11_initialize] has not yet run. * * When done with the list, free it with gck_list_unref_free(). * @@ -389,13 +348,13 @@ gcr_pkcs11_get_modules (void) /** * gcr_pkcs11_set_modules: - * @modules: (element-type Gck.Module): a list of #GckModule + * @modules: (element-type Gck.Module): a list of PKCS#11 modules * - * Set the list of PKCS\#11 modules that are used by the GCR library. - * Each module in the list is a #GckModule object. + * Set the list of PKCS#11 modules that are used by the GCR library. + * Each module in the list is a [class@Gck.Module] object. * * It is not normally necessary to call this function. The available - * PKCS\#11 modules installed on the system are automatically loaded + * PKCS#11 modules installed on the system are automatically loaded * by the GCR library. */ void @@ -416,11 +375,11 @@ gcr_pkcs11_set_modules (GList *modules) * gcr_pkcs11_add_module: * @module: a #GckModule * - * Add a #GckModule to the list of PKCS\#11 modules that are used by the + * Add a #GckModule to the list of PKCS#11 modules that are used by the * GCR library. * * It is not normally necessary to call this function. The available - * PKCS\#11 modules installed on the system are automatically loaded + * PKCS#11 modules installed on the system are automatically loaded * by the GCR library. */ void @@ -432,16 +391,16 @@ gcr_pkcs11_add_module (GckModule *module) /** * gcr_pkcs11_add_module_from_file: - * @module_path: the full file path of the PKCS\#11 module + * @module_path: the full file path of the PKCS#11 module * @unused: unused * @error: a #GError or %NULL * - * Initialize a PKCS\#11 module and add it to the modules that are + * Initialize a PKCS#11 module and add it to the modules that are * used by the GCR library. Note that is an error to initialize the same - * PKCS\#11 module twice. + * PKCS#11 module twice. * * It is not normally necessary to call this function. The available - * PKCS\#11 modules installed on the system are automatically loaded + * PKCS#11 modules installed on the system are automatically loaded * by the GCR library. * * Returns: whether the module was sucessfully added. @@ -474,10 +433,10 @@ gcr_pkcs11_add_module_from_file (const gchar *module_path, gpointer unused, /** * gcr_pkcs11_get_trust_store_slot: * - * Selects an appropriate PKCS\#11 slot to store trust assertions. The slot + * Selects an appropriate PKCS#11 slot to store trust assertions. The slot * to use is normally configured automatically by the system. * - * This will only return a valid result after the gcr_pkcs11_initialize() + * This will only return a valid result after the [func@pkcs11_initialize] * method has been called. * * When done with the #GckSlot, use g_object_unref() to release it. @@ -518,14 +477,12 @@ gcr_pkcs11_get_trust_store_slot (void) /** * gcr_pkcs11_get_trust_lookup_slots: * - * List all the PKCS\#11 slots that are used by the GCR library for lookup - * of trust assertions. Each slot is a #GckSlot object. + * List all the PKCS#11 slots that are used by the GCR library for lookup + * of trust assertions. Each slot is a [class@Gck.Slot] object. * - * This will return an empty list if the gcr_pkcs11_initialize() function has + * This will return an empty list if the [func@pkcs11_initialize] function has * not yet been called. * - * When done with the list, free it with gck_list_unref_free(). - * * Returns: (transfer full) (element-type Gck.Slot): a list of #GckSlot * objects to use for lookup of trust, or the empty list if not * initialized or no appropriate trust stores could be found. @@ -564,7 +521,7 @@ gcr_pkcs11_get_trust_lookup_slots (void) /** * gcr_pkcs11_get_trust_store_uri: * - * Get the PKCS\#11 URI that is used to identify which slot to use for + * Get the PKCS#11 URI that is used to identify which slot to use for * storing trust storage. * * Returns: (nullable): the uri which identifies trust storage slot @@ -580,11 +537,11 @@ gcr_pkcs11_get_trust_store_uri (void) * gcr_pkcs11_set_trust_store_uri: * @pkcs11_uri: (nullable): the uri which identifies trust storage slot * - * Set the PKCS\#11 URI that is used to identify which slot to use for + * Set the PKCS#11 URI that is used to identify which slot to use for * storing trust assertions. * * It is not normally necessary to call this function. The relevant - * PKCS\#11 slot is automatically configured by the GCR library. + * PKCS#11 slot is automatically configured by the GCR library. */ void gcr_pkcs11_set_trust_store_uri (const gchar *pkcs11_uri) @@ -602,7 +559,7 @@ gcr_pkcs11_set_trust_store_uri (const gchar *pkcs11_uri) /** * gcr_pkcs11_get_trust_lookup_uris: * - * Get the PKCS\#11 URIs that are used to identify which slots to use for + * Get the PKCS#11 URIs that are used to identify which slots to use for * lookup trust assertions. * * Returns: (nullable) (transfer none): the uri which identifies trust storage slot @@ -618,11 +575,11 @@ gcr_pkcs11_get_trust_lookup_uris (void) * gcr_pkcs11_set_trust_lookup_uris: * @pkcs11_uris: (nullable): the uris which identifies trust lookup slots * - * Set the PKCS\#11 URIs that are used to identify which slots to use for + * Set the PKCS#11 URIs that are used to identify which slots to use for * lookup of trust assertions. * * It is not normally necessary to call this function. The relevant - * PKCS\#11 slots are automatically configured by the GCR library. + * PKCS#11 slots are automatically configured by the GCR library. */ void gcr_pkcs11_set_trust_lookup_uris (const gchar **pkcs11_uris) diff --git a/gcr/gcr-mock-prompter.c b/gcr/gcr-mock-prompter.c index 60c5dc0..1ca4589 100644 --- a/gcr/gcr-mock-prompter.c +++ b/gcr/gcr-mock-prompter.c @@ -31,17 +31,15 @@ #include <string.h> /** - * SECTION:gcr-mock-prompter - * @title: GcrMockPrompter - * @short_description: a mock GcrSystemPrompter for testing + * GcrMockPrompter: * - * A mock GcrSystemPrompter used for testing against. + * A mock [class@SystemPrompter] used for testing against. * - * Use gcr_mock_prompter_start() to start the mock prompter in another + * Use [func@MockPrompter.start] to start the mock prompter in another * thread. The returned string is the dbus address of the mock prompter. - * You can pass this to gcr_system_prompt_open() as the prompter bus name. + * You can pass this to [func@SystemPrompt.open] as the prompter bus name. * - * Use the gcr_mock_prompter_expect_confirm_ok() function and friends before + * Use the [func@MockPrompter.expect_confirm_ok] function and friends before * prompting to verify that the prompts are displayed as expected, and to * provide a response. */ diff --git a/gcr/gcr-parser.c b/gcr/gcr-parser.c index 812ed94..ba3927e 100644 --- a/gcr/gcr-parser.c +++ b/gcr/gcr-parser.c @@ -45,28 +45,22 @@ #include <gcrypt.h> /** - * SECTION:gcr-parser - * @title: GcrParser - * @short_description: Parser for certificate and key files + * GcrParser: * - * A #GcrParser can parse various certificate and key files such as OpenSSL - * PEM files, DER encoded certifictes, PKCS\#8 keys and so on. Each various - * format is identified by a value in the #GcrDataFormat enumeration. + * A parser for parsing various types of files or data. * - * In order to parse data, a new parser is created with gcr_parser_new() and - * then the #GcrParser::authenticate and #GcrParser::parsed signals should be - * connected to. Data is then fed to the parser via gcr_parser_parse_data() - * or gcr_parser_parse_stream(). + * A `GcrParser` can parse various certificate and key files such as OpenSSL + * PEM files, DER encoded certifictes, PKCS#8 keys and so on. Each various + * format is identified by a value in the [enum@DataFormat] enumeration. * - * During the #GcrParser::parsed signal the attributes that make up the currently - * parsed item can be retrieved using the gcr_parser_get_parsed_attributes() - * function. - */ - -/** - * GcrParser: + * In order to parse data, a new parser is created with gcr_parser_new() and + * then the [signal@Parser::authenticate] and [signal@Parser::parsed] signals + * should be connected to. Data is then fed to the parser via + * [method@Parser.parse_data] or [method@Parser.parse_stream]. * - * A parser for parsing various types of files or data. + * During the [signal@Parser::parsed] signal the attributes that make up the + * currently parsed item can be retrieved using the + * [method@Parser.get_parsed_attributes] function. */ /** @@ -2192,12 +2186,12 @@ parse_openssh_public (GcrParser *self, * @GCR_FORMAT_DER_PRIVATE_KEY_EC: DER encoded EC private key * @GCR_FORMAT_DER_SUBJECT_PUBLIC_KEY: DER encoded SubjectPublicKeyInfo * @GCR_FORMAT_DER_CERTIFICATE_X509: DER encoded X.509 certificate - * @GCR_FORMAT_DER_PKCS7: DER encoded PKCS\#7 container file which can contain certificates - * @GCR_FORMAT_DER_PKCS8: DER encoded PKCS\#8 file which can contain a key - * @GCR_FORMAT_DER_PKCS8_PLAIN: Unencrypted DER encoded PKCS\#8 file which can contain a key - * @GCR_FORMAT_DER_PKCS8_ENCRYPTED: Encrypted DER encoded PKCS\#8 file which can contain a key - * @GCR_FORMAT_DER_PKCS10: DER encoded PKCS\#10 certificate request file - * @GCR_FORMAT_DER_PKCS12: DER encoded PKCS\#12 file which can contain certificates and/or keys + * @GCR_FORMAT_DER_PKCS7: DER encoded PKCS#7 container file which can contain certificates + * @GCR_FORMAT_DER_PKCS8: DER encoded PKCS#8 file which can contain a key + * @GCR_FORMAT_DER_PKCS8_PLAIN: Unencrypted DER encoded PKCS#8 file which can contain a key + * @GCR_FORMAT_DER_PKCS8_ENCRYPTED: Encrypted DER encoded PKCS#8 file which can contain a key + * @GCR_FORMAT_DER_PKCS10: DER encoded PKCS#10 certificate request file + * @GCR_FORMAT_DER_PKCS12: DER encoded PKCS#12 file which can contain certificates and/or keys * @GCR_FORMAT_OPENSSH_PUBLIC: OpenSSH v1 or v2 public key * @GCR_FORMAT_OPENPGP_PACKET: OpenPGP key packet(s) * @GCR_FORMAT_OPENPGP_ARMOR: OpenPGP public or private key armor encoded data @@ -2207,11 +2201,11 @@ parse_openssh_public (GcrParser *self, * @GCR_FORMAT_PEM_PRIVATE_KEY_DSA: An OpenSSL style PEM file with a private DSA key * @GCR_FORMAT_PEM_PRIVATE_KEY_EC: An OpenSSL style PEM file with a private EC key * @GCR_FORMAT_PEM_CERTIFICATE_X509: An OpenSSL style PEM file with an X.509 certificate - * @GCR_FORMAT_PEM_PKCS7: An OpenSSL style PEM file containing PKCS\#7 - * @GCR_FORMAT_PEM_PKCS8_PLAIN: Unencrypted OpenSSL style PEM file containing PKCS\#8 - * @GCR_FORMAT_PEM_PKCS8_ENCRYPTED: Encrypted OpenSSL style PEM file containing PKCS\#8 - * @GCR_FORMAT_PEM_PKCS10: An OpenSSL style PEM file containing PKCS\#10 - * @GCR_FORMAT_PEM_PKCS12: An OpenSSL style PEM file containing PKCS\#12 + * @GCR_FORMAT_PEM_PKCS7: An OpenSSL style PEM file containing PKCS#7 + * @GCR_FORMAT_PEM_PKCS8_PLAIN: Unencrypted OpenSSL style PEM file containing PKCS#8 + * @GCR_FORMAT_PEM_PKCS8_ENCRYPTED: Encrypted OpenSSL style PEM file containing PKCS#8 + * @GCR_FORMAT_PEM_PKCS10: An OpenSSL style PEM file containing PKCS#10 + * @GCR_FORMAT_PEM_PKCS12: An OpenSSL style PEM file containing PKCS#12 * @GCR_FORMAT_PEM_PUBLIC_KEY: An OpenSSL style PEM file containing a SubjectPublicKeyInfo * @GCR_FORMAT_DER_SPKAC: DER encoded SPKAC as generated by HTML5 keygen element * @GCR_FORMAT_BASE64_SPKAC: OpenSSL style SPKAC data diff --git a/gcr/gcr-pkcs11-certificate.c b/gcr/gcr-pkcs11-certificate.c index ea87961..e3c3b55 100644 --- a/gcr/gcr-pkcs11-certificate.c +++ b/gcr/gcr-pkcs11-certificate.c @@ -32,32 +32,18 @@ #include <string.h> /** - * SECTION:gcr-pkcs11-certificate - * @title: GcrPkcs11Certificate - * @short_description: A certificate loaded from PKCS\#11 storage + * GcrPkcs11Certificate: * - * A #GcrPkcs11Certificate is a certificate loaded from a PKCS\#11 storage. - * It is also a valid #GckObject and can be used as such. + * A certificate loaded from a PKCS#11 storage. + * It is also a valid [class@Gck.Object] and can be used as such. * * Use gcr_pkcs11_certificate_lookup_issuer() to lookup the issuer of a given - * certificate in the PKCS\#11 store. + * certificate in the PKCS#11 store. * - * Various common PKCS\#11 certificate attributes are automatically loaded and + * Various common PKCS#11 certificate attributes are automatically loaded and * are available via gcr_pkcs11_certificate_get_attributes(). */ -/** - * GcrPkcs11Certificate: - * - * A certificate loaded from PKCS\#11 storage. - */ - -/** - * GcrPkcs11CertificateClass: - * - * The class for #GcrPkcs11Certificate. - */ - enum { PROP_0, PROP_ATTRIBUTES @@ -330,7 +316,7 @@ gcr_pkcs11_certificate_get_attributes (GcrPkcs11Certificate *self) * @cancellable: a #GCancellable * @error: a #GError, or %NULL * - * Lookup a the issuer of a @certificate in the PKCS\#11 storage. The + * Lookup a the issuer of a @certificate in the PKCS#11 storage. The * lookup is done using the issuer DN of the certificate. No certificate chain * verification is done. Use a crypto library to make trust decisions. * @@ -370,7 +356,7 @@ gcr_pkcs11_certificate_lookup_issuer (GcrCertificate *certificate, GCancellable * @callback: a #GAsyncReadyCallback to call when the operation completes * @user_data: the data to pass to callback function * - * Lookup a the issuer of a @certificate in the PKCS\#11 storage. The + * Lookup a the issuer of a @certificate in the PKCS#11 storage. The * lookup is done using the issuer DN of the certificate. No certificate chain * verification is done. Use a crypto library to make trust decisions. * diff --git a/gcr/gcr-prompt.c b/gcr/gcr-prompt.c index 403f796..3c8ed2a 100644 --- a/gcr/gcr-prompt.c +++ b/gcr/gcr-prompt.c @@ -26,33 +26,26 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gcr-prompt - * @title: GcrPrompt - * @short_description: a user prompt + * GcrPrompt: * - * A #GcrPrompt represents a prompt displayed to the user. It is an interface - * with various implementations. + * A prompt displayed to the user. It is an interface with various + * implementations. * * Various properties are set on the prompt, and then the prompt is displayed - * the various prompt methods like gcr_prompt_password_run(). + * the various prompt methods like [method@Prompt.password_run]. * - * A #GcrPrompt may be used to display multiple related prompts. Most - * implemantions do not hide the window between display of multiple related + * A `GcrPrompt` may be used to display multiple related prompts. Most + * implementions do not hide the window between display of multiple related * prompts, and the #GcrPrompt must be closed or destroyed in order to make * it go away. This allows the user to see that the prompts are related. * - * Use #GcrPromptDialog to create an in-process GTK+ dialog prompt. Use - * #GcrSystemPrompt to create a system prompt in a prompter process. + * Use `GcrPromptDialog` (part of gcr-ui) to create an in-process GTK+ dialog + * prompt. Use [class@SystemPrompt] to create a system prompt in a prompter + * process. * - * The prompt implementation will always display the GcrPrompt:message property, - * but may choose not to display the GcrPrompt:description or GcrPrompt:title - * properties. - */ - -/** - * GcrPrompt: - * - * Represents a #GcrPrompt displayed to the user. + * The prompt implementation will always display the [property@Prompt:message] + * property, but may choose not to display the [property@Prompt:description] or + * [property@Prompt:title] properties. */ /** @@ -64,7 +57,7 @@ * @prompt_confirm_finish: complete a confirm prompt * @prompt_close: close a prompt * - * The interface for implementing #GcrPrompt. + * The interface for implementing [class@Prompt]. */ /** @@ -72,7 +65,7 @@ * @GCR_PROMPT_REPLY_CONTINUE: the user replied with 'ok' * @GCR_PROMPT_REPLY_CANCEL: the prompt was cancelled * - * Various replies returned by gcr_prompt_confirm() and friends. + * Various replies returned by [method@Prompt.confirm] and friends. */ enum { @@ -244,7 +237,7 @@ gcr_prompt_default_init (GcrPromptIface *iface) * handler has run, the prompt is closed. The various prompting methods * will return results as if the user dismissed the prompt. * - * You can use the gcr_prompt_close() method to emit this signal. + * You can use the [method@Prompt.close] method to emit this signal. */ signals[PROMPT_CLOSE] = g_signal_new ("prompt-close", GCR_TYPE_PROMPT, G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GcrPromptIface, prompt_close), @@ -760,7 +753,7 @@ gcr_prompt_set_cancel_label (GcrPrompt *prompt, } /** - * gcr_prompt_password_async: + * gcr_prompt_password_async: (virtual prompt_password_async) * @prompt: a prompt * @cancellable: optional cancellation object * @callback: called when the operation completes @@ -789,7 +782,7 @@ gcr_prompt_password_async (GcrPrompt *prompt, } /** - * gcr_prompt_password_finish: + * gcr_prompt_password_finish: (virtual prompt_password_finish) * @prompt: a prompt * @result: asynchronous result passed to callback * @error: location to place error on failure @@ -913,7 +906,7 @@ gcr_prompt_password_run (GcrPrompt *prompt, } /** - * gcr_prompt_confirm_async: + * gcr_prompt_confirm_async: (virtual prompt_confirm_async) * @prompt: a prompt * @cancellable: optional cancellation object * @callback: called when the operation completes @@ -943,7 +936,7 @@ gcr_prompt_confirm_async (GcrPrompt *prompt, } /** - * gcr_prompt_confirm_finish: + * gcr_prompt_confirm_finish: (virtual prompt_confirm_finish) * @prompt: a prompt * @result: asynchronous result passed to callback * @error: location to place error on failure @@ -1026,7 +1019,7 @@ gcr_prompt_confirm (GcrPrompt *prompt, * represent the question correctly. * * This method will block until the a response is returned from the prompter - * and will run a main loop similar to a gtk_dialog_run(). The application + * and will run a main loop similar to a `gtk_dialog_run()`. The application * will remain responsive but care must be taken to handle reentrancy issues. * * %GCR_PROMPT_REPLY_CONTINUE will be returned if the user confirms the prompt. The @@ -1066,9 +1059,9 @@ gcr_prompt_confirm_run (GcrPrompt *prompt, * Closes the prompt so that in can no longer be used to prompt. The various * prompt methods will return results as if the user dismissed the prompt. * - * The prompt may also be closed by the implementor of the #GcrPrompt object. + * The prompt may also be closed by the implementor of the prompt object. * - * This emits the GcrPrompt::prompt-close signal on the prompt object. + * This emits the [signal@Prompt::prompt-close] signal on the prompt object. */ void gcr_prompt_close (GcrPrompt *prompt) diff --git a/gcr/gcr-secret-exchange.c b/gcr/gcr-secret-exchange.c index 8140d50..cadca83 100644 --- a/gcr/gcr-secret-exchange.c +++ b/gcr/gcr-secret-exchange.c @@ -33,43 +33,30 @@ EGG_SECURE_DECLARE (secret_exchange); /** - * SECTION:gcr-secret-exchange - * @title: GcrSecretExchange - * @short_description: Exchange secrets between processes in an unexposed way. + * GcrSecretExchange: * * Allows exchange of secrets between two processes on the same system without * exposing those secrets to things like loggers, non-pageable memory etc. * * This does not protect against active attacks like MITM attacks. * - * Each side creates a #GcrSecretExchange object, and one of the sides calls - * gcr_secret_exchange_begin(). This creates a string, which should be passed + * Each side creates a secret exchange object, and one of the sides calls + * [method@SecretExchange.begin]. This creates a string, which should be passed * to the other side. Each side passes the strings it receives into - * gcr_secret_exchange_receive(). + * [method@SecretExchange.receive]. * * In order to send a reply (either with or without a secret) use - * gcr_secret_exchange_send(). A side must have had gcr_secret_exchange_receive() - * successfully called before it can use gcr_secret_exchange_send(). + * [method@SecretExchange.send]. A side must have successfully called + * [method@SecretExchange.receive] before it can use + * [method@SecretExchange.send]. * - * The #GcrSecretExchange objects can be used for multiple iterations of the + * The secret exchange objects can be used for multiple iterations of the * conversation, or for just one request/reply. The only limitation being that * the initial request cannot contain a secret. * * Caveat: Information about the approximate length (rounded up to the nearest * 16 bytes) may be leaked. If this is considered inacceptable, do not use - * #GcrSecretExchange. - */ - -/** - * GcrSecretExchange: - * - * An object representing one side of a secret exchange. - */ - -/** - * GcrSecretExchangeClass: - * - * The class for #GcrSecretExchange + * [class@SecretExchange]. */ /** @@ -224,7 +211,7 @@ gcr_secret_exchange_finalize (GObject *obj) * * Specify a protocol of %NULL to allow any protocol. This is especially * relevant on the side of the exchange that does not call - * gcr_secret_exchange_begin(), that is the originator. Currently the only + * [method@SecretExchange.begin], that is the originator. Currently the only * protocol supported is %GCR_SECRET_EXCHANGE_PROTOCOL_1. * * Returns: (transfer full): A new #GcrSecretExchange object @@ -243,8 +230,8 @@ gcr_secret_exchange_new (const gchar *protocol) * Get the secret exchange protocol. * * Will return %NULL if no protocol was specified, and either - * gcr_secret_exchange_begin() or gcr_secret_exchange_receive() have not been - * called successfully. + * [method@SecretExchange.begin] or [method@SecretExchange.receive] have not + * been called successfully. * * Returns: the protocol or %NULL */ @@ -262,7 +249,7 @@ gcr_secret_exchange_get_protocol (GcrSecretExchange *self) * @self: a #GcrSecretExchange object * * Begin the secret exchange. The resulting string should be sent to the other - * side of the exchange. The other side should use gcr_secret_exchange_receive() + * side of the exchange. The other side should use [method@SecretExchange.receive] * to process the string. * * Returns: (transfer full): A newly allocated string to be sent to the other @@ -387,7 +374,8 @@ perform_decrypt (GcrSecretExchange *self, * @exchange: the string received * * Receive a string from the other side of secret exchange. This string will - * have been created by gcr_secret_exchange_begin() or gcr_secret_exchange_send(). + * have been created by [method@SecretExchange.begin] or + * [method@SecretExchange.send]. * * After this call completes successfully the value returned from * gcr_secret_exchange_get_secret() will have changed. @@ -514,7 +502,7 @@ perform_encrypt (GcrSecretExchange *self, * Send a reply to the other side of the secret exchange, optionally sending a * secret. * - * gcr_secret_exchange_receive() must have been successfully called at least + * [method@SecretExchange.receive] must have been successfully called at least * once on this object. In other words this object must have received data * from the other side of the secret exchange, before we can send a secret. * @@ -864,7 +852,7 @@ gcr_secret_exchange_class_init (GcrSecretExchangeClass *klass) * The protocol being used for the exchange. * * Will be %NULL if no protocol was specified when creating this object, - * and either gcr_secret_exchange_begin() or gcr_secret_exchange_receive() + * and either [method@SecretExchange.begin] or [method@SecretExchange.receive] * have not been called successfully. */ g_object_class_install_property (gobject_class, PROP_PROTOCOL, diff --git a/gcr/gcr-secure-memory.c b/gcr/gcr-secure-memory.c index 201861a..1ff94e0 100644 --- a/gcr/gcr-secure-memory.c +++ b/gcr/gcr-secure-memory.c @@ -32,22 +32,6 @@ #include <string.h> /** - * SECTION:gcr-secure-memory - * @title: Non-pageable Memory - * @short_description: Secure non-pageable memory - * - * Normal allocated memory can be paged to disk at the whim of the operating - * system. This can be a problem for sensitive information like passwords, keys - * and secrets. - * - * The Gcr library holds passwords and keys in non-pageable, or locked memory. - * This is only possible if the OS contains support for it. - * - * These functions allow applications to use secure memory to hold passwords - * and other sensitive information. - */ - -/** * gcr_secure_memory_new: (skip) * @type: C type of the objects to allocate * @n_objects: number of objects to allocate diff --git a/gcr/gcr-simple-certificate.c b/gcr/gcr-simple-certificate.c index 3daba64..0331a3b 100644 --- a/gcr/gcr-simple-certificate.c +++ b/gcr/gcr-simple-certificate.c @@ -27,29 +27,13 @@ #include <string.h> /** - * SECTION:gcr-simple-certificate - * @title: GcrSimpleCertificate - * @short_description: A certificate loaded from a memory buffer - * - * An implementation of #GcrCertificate which loads a certificate from DER - * data already located in memory. - * - * To create a #GcrSimpleCertificate object use the - * gcr_simple_certificate_new() or gcr_simple_certificate_new_static() - * functions. - */ - -/** * GcrSimpleCertificate: * - * A #GcrCertificate which represents a certificate already in memory. - */ - -/** - * GcrSimpleCertificateClass: - * @parent_class: The parent class + * An implementation of [iface@Certificate] which loads a certificate from DER + * data already located in memory. * - * The class for #GcrSimpleCertificate. + * To create an object, use the [ctor@SimpleCertificate.new] or + * [ctor@SimpleCertificate.new_static] functions. */ struct _GcrSimpleCertificatePrivate { diff --git a/gcr/gcr-simple-collection.c b/gcr/gcr-simple-collection.c index c90149b..d0c5a30 100644 --- a/gcr/gcr-simple-collection.c +++ b/gcr/gcr-simple-collection.c @@ -27,26 +27,13 @@ #include <string.h> /** - * SECTION:gcr-simple-collection - * @title: GcrSimpleCollection - * @short_description: A simple implementation of GcrCollection - * - * A simple implementation of #GcrCollection, which you can add and remove - * objects from. Use gcr_simple_collection_add() to do this - * gcr_simple_collection_remove(). - */ - -/** * GcrSimpleCollection: * - * A simple implementation of #GcrCollection. - */ - -/** - * GcrSimpleCollectionClass: - * @parent_class: The parent class + * A simple implementation of [iface@Collection], which you can add and remove + * objects from. * - * The class for #GcrSimpleCollection. + * You can use [method@SimpleCollection.add] to add objects, and + * [method@SimpleCollection.remove] to remove them again. */ struct _GcrSimpleCollectionPrivate { diff --git a/gcr/gcr-ssh-askpass.c b/gcr/gcr-ssh-askpass.c index fd9e20b..1a18589 100644 --- a/gcr/gcr-ssh-askpass.c +++ b/gcr/gcr-ssh-askpass.c @@ -35,26 +35,12 @@ const char *gcr_ssh_askpass_executable = LIBEXECDIR "/gcr-ssh-askpass"; /** - * SECTION:gcr-ssh-askpass - * @title: GcrSshAskpass - * @short_description: Allows an ssh command to callback for a password + * GcrSshAskpass: * * When used as the setup function while spawning an ssh command like ssh-add * or ssh, this allows callbacks for passwords on the provided interaction. */ -/** - * GcrSshAskpass: - * - * An object containing the password prompting state. - */ - -/** - * GcrSshAskpassClass: - * - * The class for #GcrSshAskpass - */ - enum { PROP_0, PROP_INTERACTION diff --git a/gcr/gcr-system-prompt.c b/gcr/gcr-system-prompt.c index 530faf6..ceba221 100644 --- a/gcr/gcr-system-prompt.c +++ b/gcr/gcr-system-prompt.c @@ -35,35 +35,19 @@ #include <glib/gi18n.h> /** - * SECTION:gcr-system-prompt - * @title: GcrSystemPrompt - * @short_description: a system modal prompt + * GcrSystemPrompt: * - * A #GcrPrompt implementation which calls to the system prompter to + * A [iface@Prompt] implementation which calls to the system prompter to * display prompts in a system modal fashion. * * Since the system prompter usually only displays one prompt at a time, you - * may have to wait for the prompt to be displayed. Use gcr_system_prompt_open() + * may have to wait for the prompt to be displayed. Use [func@SystemPrompt.open] * or a related function to open a prompt. Since this can take a long time, you * should always check that the prompt is still needed after it is opened. A * previous prompt may have already provided the information needed and you * may no longer need to prompt. * - * Use gcr_system_prompt_close() to close the prompt when you're done with it. - */ - -/** - * GcrSystemPrompt: - * - * A #GcrPrompt which shows a system prompt. This is usually a system modal - * dialog. - */ - -/** - * GcrSystemPromptClass: - * @parent_class: parent class - * - * The class for #GcrSystemPrompt. + * Use [method@SystemPrompt.close] to close the prompt when you're done with it. */ /** @@ -603,7 +587,7 @@ gcr_system_prompt_class_init (GcrSystemPromptClass *klass) * gcr_system_prompt_get_secret_exchange: * @self: a prompter * - * Get the current #GcrSecretExchange used to transfer secrets in this prompt. + * Get the current [class@SecretExchange] used to transfer secrets in this prompt. * * Returns: (transfer none): the secret exchange */ @@ -1379,9 +1363,9 @@ gcr_system_prompt_open_async (gint timeout_seconds, /** * gcr_system_prompt_open_for_prompter_async: - * @prompter_name: (nullable): the prompter dbus name + * @prompter_name: (nullable): the prompter D-Bus name * @timeout_seconds: the number of seconds to wait to access the prompt, or -1 - * @cancellable: optional cancellation object + * @cancellable: (nullable): optional cancellation object * @callback: called when the operation completes * @user_data: data to pass the callback * @@ -1456,7 +1440,7 @@ gcr_system_prompt_open_finish (GAsyncResult *result, /** * gcr_system_prompt_open: * @timeout_seconds: the number of seconds to wait to access the prompt, or -1 - * @cancellable: optional cancellation object + * @cancellable: (nullable): optional cancellation object * @error: location to place error on failure * * Opens a system prompt with the default prompter. diff --git a/gcr/gcr-system-prompter.c b/gcr/gcr-system-prompter.c index 10948cf..dbb51b0 100644 --- a/gcr/gcr-system-prompter.c +++ b/gcr/gcr-system-prompter.c @@ -38,23 +38,18 @@ #include <string.h> /** - * SECTION:gcr-system-prompter - * @title: GcrSystemPrompter - * @short_description: a prompter which displays system prompts + * GcrSystemPrompter: + * + * A prompter used by implementations of system prompts. * - * This is a DBus service which is rarely implemented. Use #GcrSystemPrompt + * This is a D-Bus service which is rarely implemented. Use [class@SystemPrompt] * to display system prompts. * - * The GcrSystemPrompter service responds to dbus requests to create system + * The system prompter service responds to D-Bus requests to create system * prompts and creates #GcrPrompt type objects to display those prompts. * - * Pass the GType of the implementation of #GcrPrompt to gcr_system_prompter_new(). - */ - -/** - * GcrSystemPrompter: - * - * A prompter used by implementations of system prompts. + * Pass the GType of the implementation of [iface@Prompt] to + * [ctor@SystemPrompter.new]. */ /** diff --git a/gcr/gcr-trust.c b/gcr/gcr-trust.c index af41d02..786ab4f 100644 --- a/gcr/gcr-trust.c +++ b/gcr/gcr-trust.c @@ -34,40 +34,6 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gcr-trust - * @title: Trust Storage and Lookups - * @short_description: Store and lookup bits of information used for - * verifying certificates. - * - * These functions provide access to stored information about which - * certificates the system and user trusts as certificate authority trust - * anchors, or overrides to the normal verification of certificates. - * - * Trust anchors are used to verify the certificate authority in a certificate - * chain. Trust anchors are always valid for a given purpose. The most common - * purpose is the #GCR_PURPOSE_SERVER_AUTH and is used for a client application - * to verify that the certificate at the server side of a TLS connection is - * authorized to act as such. To check if a certificate is a trust anchor use - * gcr_trust_is_certificate_anchored(). - * - * Pinned certificates are used when a user overrides the default trust - * decision for a given certificate. They're often used with self-signed - * certificates. Pinned certificates are always only valid for a single peer - * such as the remote host with which TLS is being performed. To lookup - * pinned certificates use gcr_trust_is_certificate_pinned(). - * - * After the user has requested to override the trust decision - * about a given certificate then a pinned certificates can be added by using - * the gcr_trust_add_pinned_certificate() function. - * - * These functions do not constitute a viable method for verifying certificates - * used in TLS or other locations. Instead they support such verification - * by providing some of the needed data for a trust decision. - * - * The storage is provided by pluggable PKCS\#11 modules. - */ - -/** * GCR_PURPOSE_SERVER_AUTH: * * The purpose used to verify the server certificate in a TLS connection. This @@ -225,7 +191,7 @@ thread_is_certificate_pinned (GTask *task, gpointer object, * pinned certificate overrides all other certificate verification. * * When the operation is finished, callback will be called. You can then call - * gcr_trust_is_certificate_pinned_finish() to get the result of the + * [func@Gcr.trust_is_certificate_pinned_finish] to get the result of the * operation. */ void @@ -435,7 +401,7 @@ thread_add_pinned_certificate (GTask *task, gpointer object, * does not add another, and succeeds without error. * * When the operation is finished, callback will be called. You can then call - * gcr_trust_add_pinned_certificate_finish() to get the result of the + * [func@Gcr.trust_add_pinned_certificate_finish] to get the result of the * operation. */ void @@ -714,8 +680,8 @@ perform_is_certificate_anchored (GckAttributes *attrs, * anchor is used to verify the signatures on other certificates when verifying * a certificate chain. Also known as a trusted certificate authority. * - * This call may block, see gcr_trust_is_certificate_anchored_async() for the - * non-blocking version. + * This call may block, see [func@Gcr.trust_is_certificate_anchored_async] for + * the non-blocking version. * * In the case of an error, %FALSE is also returned. Check @error to detect * if an error occurred. diff --git a/gcr/gcr-union-collection.c b/gcr/gcr-union-collection.c index b66b7c8..846b226 100644 --- a/gcr/gcr-union-collection.c +++ b/gcr/gcr-union-collection.c @@ -28,26 +28,11 @@ #include <string.h> /** - * SECTION:gcr-union-collection - * @title: GcrUnionCollection - * @short_description: A GcrCollection which combines other collections - * - * An implementation of #GcrCollection, which combines the objects in - * other #GcrCollections. Use gcr_union_collection_add() to add and - * gcr_union_collection_remove() to remove them. - */ - -/** * GcrUnionCollection: * - * A union implementation of #GcrCollection. - */ - -/** - * GcrUnionCollectionClass: - * @parent_class: The parent class - * - * The class for #GcrUnionCollection. + * An implementation of #GcrCollection, which combines the objects in + * other [iface@Collection]s. Use [method@UnionCollection.add] to add and + * [method@UnionCollection.remove] to remove them. */ struct _GcrUnionCollectionPrivate { diff --git a/meson.build b/meson.build index 6fa0ff4..dea1b69 100644 --- a/meson.build +++ b/meson.build @@ -1,6 +1,6 @@ project('gcr', 'c', version: '3.41.0', - meson_version: '>= 0.49', + meson_version: '>= 0.52', license: 'GPL2+', ) @@ -101,6 +101,10 @@ if get_option('gtk') subdir('ui') endif if get_option('gtk_doc') + if not get_option('introspection') + error('Can\'t generate docs without introspection enabled!') + endif + subdir('docs') endif diff --git a/ui/gcr-certificate-renderer.c b/ui/gcr-certificate-renderer.c index 513cf01..70bfb5d 100644 --- a/ui/gcr-certificate-renderer.c +++ b/ui/gcr-certificate-renderer.c @@ -748,7 +748,7 @@ gcr_certificate_renderer_set_certificate (GcrCertificateRenderer *self, GcrCerti * gcr_certificate_renderer_get_attributes: * @self: The renderer * - * Get the PKCS\#11 attributes, if any, set for this renderer to display. + * Get the PKCS#11 attributes, if any, set for this renderer to display. * * Returns: (nullable) (transfer none): the attributes, owned by the renderer * @@ -766,8 +766,8 @@ gcr_certificate_renderer_get_attributes (GcrCertificateRenderer *self) * @self: The renderer * @attrs: (nullable): attributes to set * - * Set the PKCS\#11 attributes for this renderer to display. One of the attributes - * should be a CKA_VALUE type attribute containing a DER encoded certificate. + * Set the PKCS#11 attributes for this renderer to display. One of the attributes + * should be a `CKA_VALUE` type attribute containing a DER encoded certificate. * * Deprecated: 3.6: Use gcr_renderer_set_attributes() instead */ diff --git a/ui/gcr-certificate-request-renderer.c b/ui/gcr-certificate-request-renderer.c index 2f3f44b..f239a9b 100644 --- a/ui/gcr-certificate-request-renderer.c +++ b/ui/gcr-certificate-request-renderer.c @@ -436,7 +436,7 @@ _gcr_certificate_request_renderer_iface (GcrRendererIface *iface) * * Create a new certificate request renderer to display the label and attributes. * One of the attributes should be a CKA_VALUE type attribute containing a DER - * encoded PKCS\#10 certificate request or an SPKAC request. + * encoded PKCS#10 certificate request or an SPKAC request. * * Returns: (transfer full): a newly allocated #GcrCertificateRequestRenderer, which * should be released with g_object_unref() @@ -455,7 +455,7 @@ _gcr_certificate_request_renderer_new_for_attributes (const gchar *label, * gcr_certificate_request_renderer_get_attributes: * @self: the renderer * - * Get the PKCS\#11 attributes, if any, set for this renderer to display. + * Get the PKCS#11 attributes, if any, set for this renderer to display. * * Returns: (nullable) (transfer none): the attributes, owned by the renderer */ @@ -471,8 +471,8 @@ _gcr_certificate_request_renderer_get_attributes (GcrCertificateRequestRenderer * @self: the renderer * @attrs: (nullable): attributes to set * - * Set the PKCS\#11 attributes for this renderer to display. One of the attributes - * should be a CKA_VALUE type attribute containing a DER encoded PKCS\#10 + * Set the PKCS#11 attributes for this renderer to display. One of the attributes + * should be a `CKA_VALUE` type attribute containing a DER encoded PKCS#10 * certificate request or an SPKAC request. */ void diff --git a/ui/gcr-certificate-widget.c b/ui/gcr-certificate-widget.c index 9a71490..731ccee 100644 --- a/ui/gcr-certificate-widget.c +++ b/ui/gcr-certificate-widget.c @@ -31,31 +31,20 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gcr-certificate-widget - * @title: GcrCertificateWidget - * @short_description: Certificate widget and renderer + * GcrCertificateWidget: * - * A #GcrCertificateWidget can be used to display a certificate. The widget - * is normally in a collapsed state showing only details, but can be expanded - * by the user. + * A widget that can be used to display a certificate. * - * Use gcr_certificate_widget_new() to create a new certificate widget. Only - * one certificate can be displayed. A #GcrCertificateWidget contains a - * #GcrViewer internally and #GcrCertificateRenderer is used to render the - * certificate to the viewer. To show more than one certificate in a view, - * create the viewer and add renderers to it. - */ - -/** - * GcrCertificateWidget: + * A certificate widget is normally in a collapsed state showing only + * details, but can be expanded by the user. * - * A widget that displays a certificate. - */ - -/** - * GcrCertificateWidgetClass: + * Use [ctor@CertificateWidget.new] to create a new certificate widget. Only + * one certificate can be displayed. It contains a [iface@Viewer] internally + * and [class@CertificateRenderer] is used to render the certificate to the + * viewer. * - * The class for #GcrCertificateWidget + * To show more than one certificate in a view, create the viewer and + * add renderers to it. */ enum { @@ -186,8 +175,7 @@ gcr_certificate_widget_class_init (GcrCertificateWidgetClass *klass) * * Create a new certificate widget which displays a given certificate. * - * Returns: (transfer full): a newly allocated #GcrCertificateWidget, which - * should be freed with g_object_unref() + * Returns: (transfer full): a new certificate widget */ GcrCertificateWidget * gcr_certificate_widget_new (GcrCertificate *certificate) diff --git a/ui/gcr-collection-model.c b/ui/gcr-collection-model.c index dd70985..d3de1a4 100644 --- a/ui/gcr-collection-model.c +++ b/ui/gcr-collection-model.c @@ -32,34 +32,28 @@ #include <unistd.h> /** - * SECTION:gcr-collection-model - * @title: GcrCollectionModel - * @short_description: A GtkTreeModel that represents a collection + * GcrCollectionModel: + * + * Ain implementation of a [class@Gtk.TreeModel] which contains a row for each + * object in a [class@Gcr.Collection]. * - * This is an implementation of #GtkTreeModel which represents the objects in - * the a #GcrCollection. As objects are added or removed from the collection, - * rows are added and removed from this model. + * As objects are added or removed from the collection, rows are added and + * removed from this model. * * The row values come from the properties of the objects in the collection. Use - * gcr_collection_model_new() to create a new collection model. To have more - * control over the values use a set of #GcrColumn structures to define the - * columns. This can be done with gcr_collection_model_new_full() or - * gcr_collection_model_set_columns(). + * [ctor@CollectionModel.new] to create a new collection model. To have more + * control over the values use a set of [struct@Gcr.Column] structures to + * define the columns. This can be done with [ctor@CollectionModel.new_full] or + * [method@CollectionModel.set_columns]. * * Each row can have a selected state, which is represented by a boolean column. * The selected state can be toggled with gcr_collection_model_toggle_selected() * or set with gcr_collection_model_set_selected_objects() and retrieved with - * gcr_collection_model_get_selected_objects(). + * [method@CollectionModel.get_selected_objects]. * * To determine which object a row represents and vice versa, use the - * gcr_collection_model_iter_for_object() or gcr_collection_model_object_for_iter() - * functions. - */ - -/** - * GcrCollectionModel: - * - * A #GtkTreeModel which contains a row for each object in a #GcrCollection. + * [method@CollectionModel.iter_for_object] or + * [method@CollectionModel.object_for_iter] functions. */ /** @@ -74,8 +68,9 @@ * @GCR_COLLECTION_MODEL_LIST: only objects in the top collection, no child objects * @GCR_COLLECTION_MODEL_TREE: show objects in the collection, and child objects in a tree form * - * If set GcrCollectionModel is created with a mode of %GCR_COLLECTION_MODEL_TREE, - * then any included objects that are themselves a #GcrCollection, will have all child + * If a [class@CollectionModel] is created with a mode of + * %GCR_COLLECTION_MODEL_TREE, then any included objects that are themselves a + * [class@Gcr.Collection], will have all child * objects include as child rows in a tree form. */ diff --git a/ui/gcr-combo-selector.c b/ui/gcr-combo-selector.c index b08a80e..cac6419 100644 --- a/ui/gcr-combo-selector.c +++ b/ui/gcr-combo-selector.c @@ -29,24 +29,10 @@ #include <string.h> /** - * SECTION:gcr-combo-selector - * @title: GcrComboSelector - * @short_description: A selector widget to select a single certificate or key. - * - * The #GcrComboSelector can be used to select a certificate or key. It allows - * the user to select one object from the selector at a time. - */ - -/** * GcrComboSelector: * - * A combo selector widget. - */ - -/** - * GcrComboSelectorClass: - * - * The class for #GcrComboSelector. + * A widget that can be used to select a certificate or key. It allows + * the user to select one object from the selector at a time. */ enum { @@ -62,10 +48,6 @@ struct _GcrComboSelectorPrivate { G_DEFINE_TYPE_WITH_PRIVATE (GcrComboSelector, gcr_combo_selector, GTK_TYPE_COMBO_BOX); /* ----------------------------------------------------------------------------- - * INTERNAL - */ - -/* ----------------------------------------------------------------------------- * OBJECT */ diff --git a/ui/gcr-failure-renderer.c b/ui/gcr-failure-renderer.c index 37f8c90..46ad600 100644 --- a/ui/gcr-failure-renderer.c +++ b/ui/gcr-failure-renderer.c @@ -27,6 +27,12 @@ #include <gdk/gdk.h> #include <glib/gi18n-lib.h> +/** + * GcrFailureRenderer: + * + * A renderer that can be used for unsupported data. + */ + enum { PROP_0, PROP_LABEL, diff --git a/ui/gcr-import-button.c b/ui/gcr-import-button.c index 56de3e7..f3a6478 100644 --- a/ui/gcr-import-button.c +++ b/ui/gcr-import-button.c @@ -39,19 +39,13 @@ enum { }; /** - * SECTION:gcr-import-button - * @title: GcrImportButton - * @short_description: Button which imports parsed certificates and keys - * - * A button which imports keys and certificates. Shows a spinner when the - * button is activated. When more than one importer is available shows - * a drop down to select which to import to. - */ - -/** * GcrImportButton: * - * Button which imports parsed certificates and keys. + * A button which imports keys and certificates. + * + * The import button shows a spinner when the button is activated. When more + * than one importer is available, it shows a drop down to select which to + * import to. */ /** @@ -60,7 +54,7 @@ enum { * @importing: Emitted when the import begins. * @imported: Emitted when the import completes, or fails. * - * Class for #GcrImportButton. + * Class struct for [class@ImportButton]. */ struct _GcrImportButtonPrivate { diff --git a/ui/gcr-key-renderer.c b/ui/gcr-key-renderer.c index c2fedcc..850a2ca 100644 --- a/ui/gcr-key-renderer.c +++ b/ui/gcr-key-renderer.c @@ -448,7 +448,7 @@ gcr_key_renderer_new (const gchar *label, GckAttributes *attrs) * @attrs: (nullable): the attributes to display * * Get the attributes displayed in the renderer. The attributes should represent - * either an RSA, DSA, or EC key in PKCS\#11 style. + * either an RSA, DSA, or EC key in PKCS#11 style. */ void gcr_key_renderer_set_attributes (GcrKeyRenderer *self, GckAttributes *attrs) diff --git a/ui/gcr-key-widget.c b/ui/gcr-key-widget.c index 26737ff..708671c 100644 --- a/ui/gcr-key-widget.c +++ b/ui/gcr-key-widget.c @@ -28,32 +28,20 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gcr-key-widget - * @title: GcrKeyWidget - * @short_description: Key widget and renderer + * GcrKeyWidget: * - * A #GcrKeyWidget can be used to display a RSA, DSA or EC key. The widget - * is normally in a collapsed state showing only details, but can be expanded - * by the user. + * A key widget and renderer * - * Use gcr_key_widget_new() to create a new key widget. Only - * one key can be displayed. A #GcrKeyWidget contains a - * #GcrViewer internally and #GcrKeyRenderer is used to render the - * key to the viewer. To show more than one key in a view, - * create the viewer and add renderers to it. - */ - -/** - * GcrKeyWidget: + * A key widget can be used to display a RSA, DSA or EC key. The widget is + * normally in a collapsed state showing only details, but can be expanded by + * the user. * - * A widget that displays a key. + * Use [ctor@KeyWidget.new] to create a new key widget. Only one key can be + * displayed. A key widget contains a [iface@Viewer] internally and + * [class@KeyRenderer] is used to render the key to the viewer. To show more + * than one key in a view, create the viewer and add renderers to it. */ -/** - * GcrKeyWidgetClass: - * - * The class for #GcrKeyWidget - */ enum { PROP_0, PROP_ATTRIBUTES @@ -197,7 +185,7 @@ gcr_key_widget_new (GckAttributes *attrs) * @attrs: (nullable): the attributes to display * * Get the attributes displayed in the widget. The attributes should represent - * either an RSA, DSA or EC key in PKCS\#11 style. + * either an RSA, DSA or EC key in PKCS#11 style. */ void gcr_key_widget_set_attributes (GcrKeyWidget *self, GckAttributes *attrs) diff --git a/ui/gcr-list-selector.c b/ui/gcr-list-selector.c index 7271cf0..9445c6a 100644 --- a/ui/gcr-list-selector.c +++ b/ui/gcr-list-selector.c @@ -34,24 +34,11 @@ #include <string.h> /** - * SECTION:gcr-list-selector - * @title: GcrListSelector - * @short_description: A selector widget to one or more certificates from a list. - * - * The #GcrListSelector can be used to select one or more certificates or keys. - * Live search is available for quick filtering. - */ - -/** * GcrListSelector: * - * A list selector widget. - */ - -/** - * GcrListSelectorClass: + * A selector widget to select 1 or more certificates or keys from a list. * - * The class for #GcrListSelector. + * Live search is available for quick filtering. */ enum { diff --git a/ui/gcr-prompt-dialog.c b/ui/gcr-prompt-dialog.c index 5331b6e..80726ba 100644 --- a/ui/gcr-prompt-dialog.c +++ b/ui/gcr-prompt-dialog.c @@ -36,26 +36,11 @@ #include <glib/gi18n.h> /** - * SECTION:gcr-prompt-dialog - * @title: GcrPromptDialog - * @short_description: a GTK+ dialog prompt - * - * A #GcrPrompt implementation which shows a GTK+ dialog. The dialog will - * remain visible (but insensitive) between prompts. If the user cancels the - * dialog between prompts, then the dialog will be hidden. - */ - -/** * GcrPromptDialog: * - * A #GcrPrompt implementation which shows a GTK+ dialog. - */ - -/** - * GcrPromptDialogClass: - * @parent_class: parent class - * - * The class for #GcrPromptDialog. + * A [iface@Gcr.Prompt] implementation which shows a GTK dialog. The dialog + * will remain visible (but insensitive) between prompts. If the user cancels + * the dialog between prompts, then the dialog will be hidden. */ #ifdef GCR_DISABLE_GRABS diff --git a/ui/gcr-renderer.c b/ui/gcr-renderer.c index 4f76793..727bf57 100644 --- a/ui/gcr-renderer.c +++ b/ui/gcr-renderer.c @@ -32,15 +32,14 @@ #include <gtk/gtk.h> /** - * SECTION:gcr-renderer - * @title: GcrRenderer - * @short_description: An interface implemented by renderers. + * GcrRenderer: * - * A #GcrRenderer is an interface that's implemented by renderers which wish - * to render data to a #GcrViewer. + * An interface that's implemented by renderers which wish to render data to a + * [class@Viewer]. * - * The interaction between #GcrRenderer and #GcrViewer is not stable yet, and - * so new renderers cannot be implemented outside the Gcr library at this time. + * The interaction between [class@Renderer] and [class@Viewer] is not stable + * yet, and so new renderers cannot be implemented outside the Gcr library at + * this time. * * To lookup a renderer for a given set of attributes, use the gcr_renderer_create() * function. This will create and initialize a renderer that's capable of viewing @@ -48,12 +47,6 @@ */ /** - * GcrRenderer: - * - * A renderer. - */ - -/** * GcrRendererIface: * @parent: the parent interface type * @data_changed: signal emitted when data being rendered changes @@ -190,7 +183,7 @@ gcr_renderer_emit_data_changed (GcrRenderer *self) * gcr_renderer_get_attributes: * @self: The renderer * - * Get the PKCS\#11 attributes, if any, set for this renderer to display. + * Get the PKCS#11 attributes, if any, set for this renderer to display. * * Returns: (nullable) (transfer none): the attributes, owned by the renderer */ @@ -212,7 +205,7 @@ gcr_renderer_get_attributes (GcrRenderer *self) * @self: The renderer * @attrs: (nullable): attributes to set * - * Set the PKCS\#11 attributes for this renderer to display. + * Set the PKCS#11 attributes for this renderer to display. */ void gcr_renderer_set_attributes (GcrRenderer *self, diff --git a/ui/gcr-secure-entry-buffer.c b/ui/gcr-secure-entry-buffer.c index 6642061..a209a22 100644 --- a/ui/gcr-secure-entry-buffer.c +++ b/ui/gcr-secure-entry-buffer.c @@ -1,4 +1,3 @@ -/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */ /* gcr-secure-buffer.c - secure memory gtkentry buffer Copyright (C) 2009 Stefan Walter @@ -29,35 +28,23 @@ #include <string.h> /** - * SECTION:gcr-secure-entry-buffer - * @title: GcrSecureEntryBuffer - * @short_description: a GtkEntryBuffer that uses non-pageable memory + * GcrSecureEntryBuffer: + * + * A [class@Gtk.EntryBuffer] that uses non-pageable memory. * * It's good practice to try to keep passwords or sensitive secrets out of * pageable memory whenever possible, so that they don't get written to disk. * - * This is a #GtkEntryBuffer to be used with #GtkEntry which uses non-pageable - * memory to store a password placed in the entry. In order to make any sense - * at all, the entry must have it's visibility turned off, and just be displaying - * place holder characters for the text. That is, a password style entry. + * A [class@SecureEntryBuffer] is a [class@Gtk.EntryBuffer] to be used with + * [class@Gtk.Entry] which uses non-pageable memory to store a password placed + * in the entry. In order to make any sense at all, the entry must have it's + * visibility turned off, and just be displaying place holder characters for + * the text. That is, a password style entry. * - * Use gtk_entry_new_with_buffer() or gtk_entry_set_buffer() to set this buffer + * Use [ctor@Gtk.Entry.new_with_buffer] or [method@Gtk.Entry.set_buffer] to set this buffer * on an entry. */ -/** - * GcrSecureEntryBuffer: - * - * A #GtkEntryBuffer which uses non-pageable memory for passwords or secrets. - */ - -/** - * GcrSecureEntryBufferClass: - * @parent_class: parent class - * - * The class for #GcrSecureEntryBuffer. - */ - EGG_SECURE_DECLARE (secure_entry_buffer); /* Initial size of buffer, in bytes */ @@ -217,8 +204,7 @@ gcr_secure_entry_buffer_class_init (GcrSecureEntryBufferClass *klass) /** * gcr_secure_entry_buffer_new: * - * Create a new #GcrSecureEntryBuffer, a #GtkEntryBuffer which uses - * non-pageable memory for the text. + * Create a new secure entry buffer. * * Returns: (transfer full): the new entry buffer */ diff --git a/ui/gcr-tree-selector.c b/ui/gcr-tree-selector.c index 3c0bbd0..e4db6ea 100644 --- a/ui/gcr-tree-selector.c +++ b/ui/gcr-tree-selector.c @@ -29,24 +29,10 @@ #include <string.h> /** - * SECTION:gcr-tree-selector - * @title: GcrTreeSelector - * @short_description: A selector widget to select certificates or keys. - * - * The #GcrTreeSelector can be used to select certificates or keys. It allows - * the user to select multiple objects from a tree. - */ - -/** * GcrTreeSelector: * - * A tree selector widget. - */ - -/** - * GcrTreeSelectorClass: - * - * The class for #GcrTreeSelector. + * A tree selector can be used to select certificates or keys. It allows + * the user to select multiple objects from a tree. */ enum { diff --git a/ui/gcr-unlock-options-widget.c b/ui/gcr-unlock-options-widget.c index afcc473..7db3257 100644 --- a/ui/gcr-unlock-options-widget.c +++ b/ui/gcr-unlock-options-widget.c @@ -22,17 +22,16 @@ #include <glib/gi18n-lib.h> /** - * SECTION:gcr-unlock-options-widget - * @title: GcrUnlockOptionsWidget - * @short_description: A widget for unlock options + * GcrUnlockOptionsWidget: + * + * This widget displays a set of unlock options for the user to select. * - * This widget displays a set of unlock options for the user to select. The user - * can choose between keeping caching the unlock indefinitely, or for a given - * amount of time. + * The user can choose between keeping caching the unlock indefinitely, or for + * a given amount of time. * * Each option has a different name, for example #GCR_UNLOCK_OPTION_ALWAYS. These * names are used together with the various functions like - * gcr_unlock_options_widget_get_choice(). + * [method@UnlockOptionsWidget.get_choice]. */ /** @@ -59,18 +58,6 @@ * Option name for caching unlock for a certain amount of time. */ -/** - * GcrUnlockOptionsWidget: - * - * An unlock options widget. - */ - -/** - * GcrUnlockOptionsWidgetClass: - * - * Class for #GcrUnlockOptionsWidget. - */ - enum { PROP_0, PROP_CHOICE, diff --git a/ui/gcr-viewer-widget.c b/ui/gcr-viewer-widget.c index 0c95fa2..4a03d5c 100644 --- a/ui/gcr-viewer-widget.c +++ b/ui/gcr-viewer-widget.c @@ -1,4 +1,3 @@ -/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */ /* gcr-viewer-widget: Widget for viewer Copyright (C) 2011 Collabora Ltd. @@ -40,9 +39,7 @@ #include <string.h> /** - * SECTION:gcr-viewer-widget - * @title: GcrViewerWidget - * @short_description: A widget which shows certificates or keys + * GcrViewerWidget: * * A viewer widget which can display certificates and keys that are * located in files. @@ -54,18 +51,6 @@ enum { PROP_DISPLAY_NAME }; -/** - * GcrViewerWidget: - * - * A viewer widget object. - */ - -/** - * GcrViewerWidgetClass: - * - * Class for #GcrViewerWidget - */ - /* * Not yet figured out how to expose these without locking down our * implementation, the parent class we derive from. @@ -557,7 +542,7 @@ gcr_viewer_widget_load_bytes (GcrViewerWidget *self, * may contain multiple parseable items if the format can contain multiple * items. * - * This function will copy the data. Use gcr_viewer_widget_load_bytes() to avoid + * This function will copy the data. Use [method@ViewerWidget.load_bytes] to avoid * copying the data. */ void diff --git a/ui/gcr-viewer.c b/ui/gcr-viewer.c index afd98aa..2ae3771 100644 --- a/ui/gcr-viewer.c +++ b/ui/gcr-viewer.c @@ -23,27 +23,20 @@ #include "gcr-viewer.h" /** - * SECTION:gcr-viewer - * @title: GcrViewer - * @short_description: A viewer which can hold renderers + * GcrViewer: * - * A #GcrViewer is an abstract interface that represents a widget that can hold + * An abstract interface that represents a widget that can hold * various renderers and display their contents. * - * The interaction between #GcrRenderer and #GcrViewer is not stable yet, and - * so viewers cannot be implemented outside the Gcr library at this time. + * The interaction between [class@Renderer] and [class@Viewer] is not stable + * yet, and so viewers cannot be implemented outside the Gcr library at this + * time. * - * Use the gcr_viewer_new() and gcr_viewer_new_scrolled() to get default + * Use the [func@Viewer.new] and [func@Viewer.new_scrolled] to get default * implementations of viewers. */ /** - * GcrViewer: - * - * An abstract viewer which displays renderers contents. - */ - -/** * GcrViewerIface: * @parent: The parent interface * @add_renderer: Virtual method to add a renderer @@ -99,7 +92,7 @@ gcr_viewer_new_scrolled (void) } /** - * gcr_viewer_add_renderer: + * gcr_viewer_add_renderer: (virtual add_renderer) * @viewer: The viewer * @renderer: The renderer to add * @@ -116,7 +109,7 @@ gcr_viewer_add_renderer (GcrViewer *viewer, } /** - * gcr_viewer_insert_renderer: + * gcr_viewer_insert_renderer: (virtual insert_renderer) * @viewer: the viewer * @renderer: the renderer to insert * @before: (nullable): the renderer to insert before @@ -136,7 +129,7 @@ gcr_viewer_insert_renderer (GcrViewer *viewer, } /** - * gcr_viewer_remove_renderer: + * gcr_viewer_remove_renderer: (virtual remove_renderer) * @viewer: The viewer * @renderer: The renderer to remove * @@ -153,7 +146,7 @@ gcr_viewer_remove_renderer (GcrViewer *viewer, } /** - * gcr_viewer_count_renderers: + * gcr_viewer_count_renderers: (virtual count_renderers) * @viewer: The viewer * * Get the number of renderers present in the viewer. @@ -169,7 +162,7 @@ gcr_viewer_count_renderers (GcrViewer *viewer) } /** - * gcr_viewer_get_renderer: + * gcr_viewer_get_renderer: (virtual get_renderer) * @viewer: The viewer * @index_: The index of the renderer to get * |
