[gnome-keyring/gnome-3-0] gcr: Complete documentation
- From: Stefan Walter <stefw src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-keyring/gnome-3-0] gcr: Complete documentation
- Date: Fri, 8 Apr 2011 11:49:31 +0000 (UTC)
commit a6db3ef195bc38d6d655807aa4d5bc35b0669c90
Author: Stef Walter <stefw collabora co uk>
Date: Wed Apr 6 22:25:41 2011 +0200
gcr: Complete documentation
docs/reference/gcr/Makefile.am | 15 ++-
docs/reference/gcr/gcr-docs.sgml | 10 +-
docs/reference/gcr/gcr-sections.txt | 214 ++++++++++++++++++------
gcr/gcr-certificate-chain.c | 32 ++++
gcr/gcr-certificate-chain.h | 2 +
gcr/gcr-certificate-renderer.c | 65 +++++++-
gcr/gcr-certificate-renderer.h | 6 +-
gcr/gcr-certificate-widget.c | 74 ++++++++-
gcr/gcr-certificate-widget.h | 7 +-
gcr/gcr-certificate.c | 12 ++
gcr/gcr-certificate.h | 1 +
gcr/gcr-importer.c | 170 ++++++++++++++++++-
gcr/gcr-importer.h | 6 +-
gcr/gcr-initializer.h | 85 ----------
gcr/gcr-key-renderer.c | 40 +++++
gcr/gcr-key-renderer.h | 2 +
gcr/gcr-key-widget.c | 53 ++++++
gcr/gcr-key-widget.h | 3 +
gcr/gcr-library.c | 16 +-
gcr/gcr-parser.c | 312 ++++++++++++++++++++++++++++++-----
gcr/gcr-parser.h | 25 ++--
gcr/gcr-pkcs11-certificate.c | 12 ++
gcr/gcr-pkcs11-certificate.h | 3 +
gcr/gcr-renderer.c | 80 +++++++++
gcr/gcr-renderer.h | 1 +
gcr/gcr-simple-certificate.c | 13 ++
gcr/gcr-simple-certificate.h | 2 +
gcr/gcr-trust.c | 2 +-
gcr/gcr-types.h | 22 +--
gcr/gcr-unlock-options-widget.c | 132 +++++++++++++++
gcr/gcr-unlock-options-widget.h | 2 +
gcr/gcr-viewer.c | 81 +++++++++-
gcr/gcr-viewer.h | 3 +-
33 files changed, 1266 insertions(+), 237 deletions(-)
---
diff --git a/docs/reference/gcr/Makefile.am b/docs/reference/gcr/Makefile.am
index 1497371..2725a6d 100644
--- a/docs/reference/gcr/Makefile.am
+++ b/docs/reference/gcr/Makefile.am
@@ -28,7 +28,7 @@ SCANGOBJ_OPTIONS=
# Extra options to supply to gtkdoc-scan.
# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
-SCAN_OPTIONS=
+SCAN_OPTIONS=--deprecated-guards="GCR_DISABLE_DEPRECATED"
# Extra options to supply to gtkdoc-mkdb.
# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
@@ -57,7 +57,18 @@ EXTRA_HFILES=
# Header files to ignore when scanning. Use base file name, no paths
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
-IGNORE_HFILES= gcr-xxx.h
+IGNORE_HFILES= \
+ gcr-certificate-exporter.h \
+ gcr-certificate-basics-widget.h \
+ gcr-certificate-details-widget.h \
+ gcr-display-scrolled.h \
+ gcr-display-view.h \
+ gcr-icons.h \
+ gcr-import-dialog.h \
+ gcr-internal.h \
+ gcr-marshal.h \
+ gcr-xxx.h \
+ gcr-zzz.h
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
diff --git a/docs/reference/gcr/gcr-docs.sgml b/docs/reference/gcr/gcr-docs.sgml
index 568dadc..86c4980 100644
--- a/docs/reference/gcr/gcr-docs.sgml
+++ b/docs/reference/gcr/gcr-docs.sgml
@@ -21,10 +21,17 @@
<xi:include href="xml/gcr-certificate-chain.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-renderer.xml"/>
+ <xi:include href="xml/gcr-viewer.xml"/>
+ </part>
+
<part id="storage">
<title>Storage</title>
<xi:include href="xml/gcr-trust.xml"/>
- <xi:include href="xml/gcr-initializer.xml"/>
<xi:include href="xml/gcr-importer.xml"/>
<xi:include href="xml/gcr-parser.xml"/>
</part>
@@ -32,5 +39,6 @@
<part id="misc">
<title>Miscellaneous</title>
<xi:include href="xml/gcr-library.xml"/>
+ <xi:include href="xml/gcr-misc.xml"/>
</part>
</book>
diff --git a/docs/reference/gcr/gcr-sections.txt b/docs/reference/gcr/gcr-sections.txt
index 95ba401..3fe7059 100644
--- a/docs/reference/gcr/gcr-sections.txt
+++ b/docs/reference/gcr/gcr-sections.txt
@@ -1,33 +1,24 @@
<SECTION>
-<FILE>gcr-import-dialog</FILE>
-GcrImportDialogPrivate
-<TITLE>GcrImportDialog</TITLE>
-GcrImportDialog
-<SUBSECTION Standard>
-GCR_IMPORT_DIALOG
-GCR_IS_IMPORT_DIALOG
-GCR_TYPE_IMPORT_DIALOG
-GCR_IMPORT_DIALOG_CLASS
-GCR_IS_IMPORT_DIALOG_CLASS
-GCR_IMPORT_DIALOG_GET_CLASS
-</SECTION>
-
-<SECTION>
<FILE>gcr-parser</FILE>
-GcrParsedItem
-GcrParserPrivate
<TITLE>GcrParser</TITLE>
+GCR_DATA_ERROR
+GcrDataError
+GcrDataFormat
GcrParser
gcr_parser_new
+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_parse_data
gcr_parser_add_password
gcr_parser_get_parsed_label
gcr_parser_get_parsed_description
gcr_parser_get_parsed_attributes
<SUBSECTION Standard>
+GcrParserPrivate
GCR_PARSER
GCR_IS_PARSER
GCR_TYPE_PARSER
@@ -67,45 +58,24 @@ gcr_certificate_get_type
</SECTION>
<SECTION>
-<FILE>gcr-initializer</FILE>
-GcrTokenManagerPrivate
-<TITLE>GcrTokenManager</TITLE>
-GcrTokenManager
-gcr_token_manager_new
-gcr_token_manager_get_slot
-gcr_token_manager_initialize
-gcr_token_manager_initialize_async
-gcr_token_manager_initialize_finish
-gcr_token_manager_change_pin
-gcr_token_manager_change_pin_async
-gcr_token_manager_change_pin_finish
-<SUBSECTION Standard>
-GCR_TOKEN_MANAGER
-GCR_IS_TOKEN_MANAGER
-GCR_TYPE_TOKEN_MANAGER
-gcr_token_manager_get_type
-GCR_TOKEN_MANAGER_CLASS
-GCR_IS_TOKEN_MANAGER_CLASS
-GCR_TOKEN_MANAGER_GET_CLASS
-</SECTION>
-
-<SECTION>
<FILE>gcr-importer</FILE>
-GcrImporterPromptBehavior
-GcrImporterPrivate
-<TITLE>GcrImporter</TITLE>
GcrImporter
+GcrImporterClass
+GcrImporterPromptBehavior
gcr_importer_new
-gcr_importer_get_parser
-gcr_importer_set_parser
+gcr_importer_listen
+gcr_importer_queue
+gcr_importer_import
+gcr_importer_import_async
+gcr_importer_import_finish
gcr_importer_get_slot
gcr_importer_set_slot
gcr_importer_get_prompt_behavior
gcr_importer_set_prompt_behavior
-gcr_importer_import
-gcr_importer_import_async
-gcr_importer_import_finish
+gcr_importer_get_parser
+gcr_importer_set_parser
<SUBSECTION Standard>
+GcrImporterPrivate
GCR_IMPORTER
GCR_IS_IMPORTER
GCR_TYPE_IMPORTER
@@ -136,16 +106,20 @@ GCR_SIMPLE_CERTIFICATE_GET_CLASS
<FILE>gcr-pkcs11-certificate</FILE>
<TITLE>GcrPkcs11Certificate</TITLE>
GcrPkcs11Certificate
-gcr_pkcs11_certificate_get_attributes
+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
-GcrPkcs11CertificateClass
GcrPkcs11CertificatePrivate
+GCR_PKCS11_CERTIFICATE
+GCR_PKCS11_CERTIFICATE_CLASS
+GCR_PKCS11_CERTIFICATE_GET_CLASS
+GCR_TYPE_PKCS11_CERTIFICATE
</SECTION>
<SECTION>
@@ -185,6 +159,7 @@ gcr_pkcs11_set_trust_store_uri
<SECTION>
<FILE>gcr-certificate-chain</FILE>
GcrCertificateChain
+GcrCertificateChainClass
GcrCertificateChainStatus
gcr_certificate_chain_new
gcr_certificate_chain_add
@@ -197,7 +172,11 @@ 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
@@ -205,7 +184,140 @@ GCR_CERTIFICATE_CHAIN_CLASS
GCR_CERTIFICATE_CHAIN_GET_CLASS
GCR_IS_CERTIFICATE_CHAIN
GCR_IS_CERTIFICATE_CHAIN_CLASS
-GcrCertificateChainClass
GcrCertificateChainPrivate
+</SECTION>
+
+<SECTION>
+<FILE>gcr-renderer</FILE>
+GcrRenderer
+GcrRendererIface
+gcr_renderer_create
+gcr_renderer_register
+gcr_renderer_render
+gcr_renderer_emit_data_changed
+<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_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>
+GcrCertificateWidget
+GcrCertificateWidgetClass
+GcrCertificateRenderer
+GcrCertificateRendererClass
+gcr_certificate_widget_new
+gcr_certificate_widget_get_attributes
+gcr_certificate_widget_set_attributes
+gcr_certificate_widget_get_certificate
+gcr_certificate_widget_set_certificate
+gcr_certificate_renderer_new
+gcr_certificate_renderer_get_attributes
+gcr_certificate_renderer_set_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-misc</FILE>
+<SUBSECTION Standard>
+gcr_data_error_get_domain
+GCK_API_SUBJECT_TO_CHANGE
</SECTION>
\ No newline at end of file
diff --git a/gcr/gcr-certificate-chain.c b/gcr/gcr-certificate-chain.c
index 1d50867..047ac5f 100644
--- a/gcr/gcr-certificate-chain.c
+++ b/gcr/gcr-certificate-chain.c
@@ -67,6 +67,26 @@
* merely the first step towards verifying trust in a certificate.
*/
+
+/**
+ * GCR_TYPE_CERTIFICATE_CHAIN_STATUS:
+ *
+ * The flags #GType for #GcrCertificateChainFlags.
+ */
+
+/**
+ * GcrCertificateChain:
+ *
+ * A chain of certificates.
+ */
+
+/**
+ * GcrCertificateChainClass:
+ * @parent_class: The parent class
+ *
+ * The class for #GcrCertificateChain.
+ */
+
enum {
PROP_0,
PROP_STATUS,
@@ -428,6 +448,12 @@ gcr_certificate_chain_class_init (GcrCertificateChainClass *klass)
* built.
*/
+/**
+ * GCR_TYPE_CERTIFICATE_CHAIN_STATUS:
+ *
+ * The enum #GType for #GcrCertificateChainStatus.
+ */
+
GType
gcr_certificate_chain_status_get_type (void)
{
@@ -461,6 +487,12 @@ gcr_certificate_chain_status_get_type (void)
* Flags to be used with the gcr_certificate_chain_build() operation.
*/
+/**
+ * GCR_TYPE_CERTIFICATE_CHAIN_FLAGS:
+ *
+ * The flags #GType for #GcrCertificateChainFlags.
+ */
+
GType
gcr_certificate_chain_flags_get_type (void)
{
diff --git a/gcr/gcr-certificate-chain.h b/gcr/gcr-certificate-chain.h
index 0e186b1..2f91542 100644
--- a/gcr/gcr-certificate-chain.h
+++ b/gcr/gcr-certificate-chain.h
@@ -78,6 +78,8 @@ typedef struct _GcrCertificateChainPrivate GcrCertificateChainPrivate;
struct _GcrCertificateChain {
GObject parent;
+
+ /*< private >*/
GcrCertificateChainPrivate *pv;
};
diff --git a/gcr/gcr-certificate-renderer.c b/gcr/gcr-certificate-renderer.c
index 073d944..83685fe 100644
--- a/gcr/gcr-certificate-renderer.c
+++ b/gcr/gcr-certificate-renderer.c
@@ -37,6 +37,20 @@
#include <gdk/gdk.h>
#include <glib/gi18n-lib.h>
+/**
+ * GcrCertificateRenderer:
+ * @parent: The parent object
+ *
+ * An implementation of #GcrRenderer which renders certificates.
+ */
+
+/**
+ * GcrCertificateRendererClass:
+ * @parent_class: The parent class.
+ *
+ * The class for #GcrCertificateRenderer.
+ */
+
enum {
PROP_0,
PROP_CERTIFICATE,
@@ -274,6 +288,11 @@ gcr_certificate_renderer_class_init (GcrCertificateRendererClass *klass)
gobject_class->set_property = gcr_certificate_renderer_set_property;
gobject_class->get_property = gcr_certificate_renderer_get_property;
+ /**
+ * GcrCertificateRenderer:certificate:
+ *
+ * The certificate to display. May be %NULL.
+ */
g_object_class_install_property (gobject_class, PROP_CERTIFICATE,
g_param_spec_object("certificate", "Certificate", "Certificate to display.",
GCR_TYPE_CERTIFICATE, G_PARAM_READWRITE));
@@ -470,12 +489,31 @@ gcr_renderer_iface_init (GcrRendererIface *iface)
* PUBLIC
*/
+/**
+ * gcr_certificate_renderer_new:
+ * @certificate: The certificate to display
+ *
+ * Create a new certificate renderer to display the certificate.
+ *
+ * Returns: A newly allocated #GcrCertificateRenderer, which should be released
+ * with g_object_unref().
+ */
GcrCertificateRenderer*
gcr_certificate_renderer_new (GcrCertificate *certificate)
{
return g_object_new (GCR_TYPE_CERTIFICATE_RENDERER, "certificate", certificate, NULL);
}
+/**
+ * gcr_certificate_renderer_get_certificate:
+ * @self: The renderer
+ *
+ * Get the certificate displayed in the renderer. If no certificate was
+ * explicitly set, then the renderer will return itself since it acts as
+ * a valid certificate.
+ *
+ * Returns: The certificate, owned by the renderer.
+ */
GcrCertificate*
gcr_certificate_renderer_get_certificate (GcrCertificateRenderer *self)
{
@@ -483,14 +521,21 @@ gcr_certificate_renderer_get_certificate (GcrCertificateRenderer *self)
return self->pv->certificate;
}
+/**
+ * gcr_certificate_renderer_set_certificate:
+ * @self: The renderer
+ * @certificate: The certificate to display
+ *
+ * Set a certificate to display in the renderer.
+ */
void
-gcr_certificate_renderer_set_certificate (GcrCertificateRenderer *self, GcrCertificate *cert)
+gcr_certificate_renderer_set_certificate (GcrCertificateRenderer *self, GcrCertificate *certificate)
{
g_return_if_fail (GCR_IS_CERTIFICATE_RENDERER (self));
if (self->pv->certificate)
g_object_unref (self->pv->certificate);
- self->pv->certificate = cert;
+ self->pv->certificate = certificate;
if (self->pv->certificate)
g_object_ref (self->pv->certificate);
@@ -498,6 +543,14 @@ gcr_certificate_renderer_set_certificate (GcrCertificateRenderer *self, GcrCerti
g_object_notify (G_OBJECT (self), "certificate");
}
+/**
+ * gcr_certificate_renderer_get_attributes:
+ * @self: The renderer
+ *
+ * Get the PKCS\#11 attributes, if any, set for this renderer to display.
+ *
+ * Returns: The attributes, owned by the renderer.
+ */
GckAttributes*
gcr_certificate_renderer_get_attributes (GcrCertificateRenderer *self)
{
@@ -505,6 +558,14 @@ gcr_certificate_renderer_get_attributes (GcrCertificateRenderer *self)
return self->pv->attributes;
}
+/**
+ * gcr_certificate_renderer_set_attributes:
+ * @self: The renderer
+ * @attrs: 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.
+ */
void
gcr_certificate_renderer_set_attributes (GcrCertificateRenderer *self, GckAttributes *attrs)
{
diff --git a/gcr/gcr-certificate-renderer.h b/gcr/gcr-certificate-renderer.h
index 9ab6157..079402a 100644
--- a/gcr/gcr-certificate-renderer.h
+++ b/gcr/gcr-certificate-renderer.h
@@ -45,6 +45,8 @@ typedef struct _GcrCertificateRendererPrivate GcrCertificateRendererPrivate;
struct _GcrCertificateRenderer {
GObject parent;
+
+ /*< private >*/
GcrCertificateRendererPrivate *pv;
};
@@ -54,12 +56,12 @@ struct _GcrCertificateRendererClass {
GType gcr_certificate_renderer_get_type (void);
-GcrCertificateRenderer* gcr_certificate_renderer_new (GcrCertificate *cert);
+GcrCertificateRenderer* gcr_certificate_renderer_new (GcrCertificate *certificate);
GcrCertificate* gcr_certificate_renderer_get_certificate (GcrCertificateRenderer *self);
void gcr_certificate_renderer_set_certificate (GcrCertificateRenderer *self,
- GcrCertificate *cert);
+ GcrCertificate *certificate);
GckAttributes* gcr_certificate_renderer_get_attributes (GcrCertificateRenderer *self);
diff --git a/gcr/gcr-certificate-widget.c b/gcr/gcr-certificate-widget.c
index 7bb4b8a..e749259 100644
--- a/gcr/gcr-certificate-widget.c
+++ b/gcr/gcr-certificate-widget.c
@@ -30,6 +30,35 @@
#include <gdk/gdk.h>
#include <glib/gi18n-lib.h>
+/**
+ * SECTION:gcr-certificate-widget
+ * @title: GcrCertificateWidget
+ * @short_description: Certificate widget and renderer
+ *
+ * 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.
+ *
+ * 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:
+ * @parent: The parent object
+ *
+ * A widget that displays a certificate.
+ */
+
+/**
+ * GcrCertificateWidgetClass:
+ *
+ * The class for #GcrCertificateWidget
+ */
+
enum {
PROP_0,
PROP_CERTIFICATE,
@@ -158,12 +187,29 @@ gcr_certificate_widget_class_init (GcrCertificateWidgetClass *klass)
* PUBLIC
*/
+/**
+ * gcr_certificate_widget_new:
+ * @certificate: Certificate to display, or %NULL
+ *
+ * Create a new certificate widget which displays a given certificate.
+ *
+ * Returns: A newly allocated #GcrCertificateWidget, which should be freed
+ * with g_object_unref().
+ */
GcrCertificateWidget*
gcr_certificate_widget_new (GcrCertificate *certificate)
{
return g_object_new (GCR_TYPE_CERTIFICATE_WIDGET, "certificate", certificate, NULL);
}
+/**
+ * gcr_certificate_widget_get_certificate:
+ * @self: The certificate widget
+ *
+ * Get the certificate displayed in the widget.
+ *
+ * Returns: The certificate.
+ */
GcrCertificate*
gcr_certificate_widget_get_certificate (GcrCertificateWidget *self)
{
@@ -171,13 +217,29 @@ gcr_certificate_widget_get_certificate (GcrCertificateWidget *self)
return gcr_certificate_renderer_get_certificate (self->pv->renderer);
}
+/**
+ * gcr_certificate_widget_set_certificate:
+ * @self: The certificate widget
+ * @certificate: The certificate to display
+ *
+ * Set the certificate displayed in the widget
+ */
void
-gcr_certificate_widget_set_certificate (GcrCertificateWidget *self, GcrCertificate *cert)
+gcr_certificate_widget_set_certificate (GcrCertificateWidget *self, GcrCertificate *certificate)
{
g_return_if_fail (GCR_IS_CERTIFICATE_WIDGET (self));
- gcr_certificate_renderer_set_certificate (self->pv->renderer, cert);
+ gcr_certificate_renderer_set_certificate (self->pv->renderer, certificate);
}
+/**
+ * gcr_certificate_widget_get_attributes:
+ * @self: The certificate widget
+ *
+ * Get the attributes displayed in the widget. The attributes should contain
+ * a certificate.
+ *
+ * Returns: The attributes, owned by the widget.
+ */
GckAttributes*
gcr_certificate_widget_get_attributes (GcrCertificateWidget *self)
{
@@ -185,6 +247,14 @@ gcr_certificate_widget_get_attributes (GcrCertificateWidget *self)
return gcr_certificate_renderer_get_attributes (self->pv->renderer);
}
+/**
+ * gcr_certificate_widget_set_attributes:
+ * @self: The certificate widget
+ * @attrs: The attributes to display
+ *
+ * Set the attributes displayed in the widget. The attributes should contain
+ * a certificate.
+ */
void
gcr_certificate_widget_set_attributes (GcrCertificateWidget *self, GckAttributes* attrs)
{
diff --git a/gcr/gcr-certificate-widget.h b/gcr/gcr-certificate-widget.h
index cf62f27..946e9ab 100644
--- a/gcr/gcr-certificate-widget.h
+++ b/gcr/gcr-certificate-widget.h
@@ -45,21 +45,24 @@ typedef struct _GcrCertificateWidgetPrivate GcrCertificateWidgetPrivate;
struct _GcrCertificateWidget {
GtkAlignment parent;
+
+ /*< private >*/
GcrCertificateWidgetPrivate *pv;
};
struct _GcrCertificateWidgetClass {
+ /*< private >*/
GtkAlignmentClass parent_class;
};
GType gcr_certificate_widget_get_type (void);
-GcrCertificateWidget* gcr_certificate_widget_new (GcrCertificate *cert);
+GcrCertificateWidget* gcr_certificate_widget_new (GcrCertificate *certificate);
GcrCertificate* gcr_certificate_widget_get_certificate (GcrCertificateWidget *self);
void gcr_certificate_widget_set_certificate (GcrCertificateWidget *self,
- GcrCertificate *cert);
+ GcrCertificate *certificate);
GckAttributes* gcr_certificate_widget_get_attributes (GcrCertificateWidget *self);
diff --git a/gcr/gcr-certificate.c b/gcr/gcr-certificate.c
index 6b17d28..4f6e7fa 100644
--- a/gcr/gcr-certificate.c
+++ b/gcr/gcr-certificate.c
@@ -48,6 +48,18 @@
* you already have the raw certificate data.
*/
+/**
+ * GcrCertificate:
+ *
+ * An object which holds a certificate.
+ */
+
+/**
+ * GcrCertificateIface:
+ *
+ * The interface that implementors of #GcrCertificate must implement.
+ */
+
/*
* The DER data in this structure is owned by the derived class.
* It is only valid for the duration of the current call stack
diff --git a/gcr/gcr-certificate.h b/gcr/gcr-certificate.h
index 1232500..57ab9e1 100644
--- a/gcr/gcr-certificate.h
+++ b/gcr/gcr-certificate.h
@@ -45,6 +45,7 @@ struct _GcrCertificateIface {
gconstpointer (*get_der_data) (GcrCertificate *self, gsize *n_data);
+ /*< private >*/
gpointer dummy1;
gpointer dummy2;
gpointer dummy3;
diff --git a/gcr/gcr-importer.c b/gcr/gcr-importer.c
index aa3e9fe..407833c 100644
--- a/gcr/gcr-importer.c
+++ b/gcr/gcr-importer.c
@@ -29,6 +29,43 @@
#include <glib/gi18n-lib.h>
+/**
+ * SECTION:gcr-importer
+ * @title: GcrImporter
+ * @short_description: Import objects into PKCS\#11 slots.
+ *
+ * A #GcrImporter can be used to import items into PKCS\#11 slots. It's most
+ * often used to parse the objects parsed with a #GcrParser. Use
+ * gcr_importer_listen() to hook up the importer to the parser.
+ *
+ * Items are queued, and then imported with gcr_importer_import() or
+ * gcr_importer_import_async().
+ */
+
+/**
+ * GcrImporter:
+ *
+ * Imports items into PKCS\#11
+ */
+
+/**
+ * GcrImporterClass:
+ * @parent_class: The parent class
+ * @queued: Signal which is fired when an item is queued
+ * @imported: Signal which is fired when an item is imported
+ *
+ * The class for #GcrImporter.
+ */
+
+/**
+ * GcrImporterPromptBehavior:
+ * @GCR_IMPORTER_PROMPT_NEEDED: Prompt when needed.
+ * @GCR_IMPORTER_PROMPT_ALWAYS: Always prompt.
+ * @GCR_IMPORTER_PROMPT_NEVER: Never prompt.
+ *
+ * Flags for the prompting behavior of #GcrImporter.
+ */
+
enum {
PROP_0,
PROP_SLOT,
@@ -626,11 +663,24 @@ gcr_importer_class_init (GcrImporterClass *klass)
g_param_spec_int ("prompt-behavior", "Prompt Behavior", "Import Prompt Behavior",
0, G_MAXINT, GCR_IMPORTER_PROMPT_NEEDED, G_PARAM_READWRITE));
+ /**
+ * GcrImporter::queued:
+ * @label: The label of the queued item.
+ * @attrs: The attributes of the queued item.
+ *
+ * This signal is emitted when an item is queued for import.
+ */
signals[QUEUED] = g_signal_new ("queued", GCR_TYPE_IMPORTER,
G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GcrImporterClass, queued),
NULL, NULL, _gcr_marshal_VOID__STRING_BOXED,
G_TYPE_NONE, 1, G_TYPE_STRING, GCK_TYPE_ATTRIBUTES);
+ /**
+ * GcrImporter::imported:
+ * @object: The object which was imported.
+ *
+ * This signal is emitted when an item has been imported.
+ */
signals[IMPORTED] = g_signal_new ("imported", GCR_TYPE_IMPORTER,
G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GcrImporterClass, imported),
NULL, NULL, g_cclosure_marshal_VOID__OBJECT,
@@ -664,12 +714,29 @@ gcr_importer_async_result (GAsyncResultIface *iface)
* PUBLIC
*/
+/**
+ * gcr_importer_new:
+ *
+ * Create a new #GcrImporter.
+ *
+ * Returns: A newly allocated importer, which should be released with
+ * g_object_unref().
+ */
GcrImporter*
gcr_importer_new (void)
{
return g_object_new (GCR_TYPE_IMPORTER, NULL);
}
+/**
+ * gcr_importer_get_slot:
+ * @self: The importer
+ *
+ * Get the PKCS\#11 slot the items will be imported to, or after
+ * an import operation, which slot they have been imported to.
+ *
+ * Returns: The slot.
+ */
GckSlot*
gcr_importer_get_slot (GcrImporter *self)
{
@@ -677,6 +744,13 @@ gcr_importer_get_slot (GcrImporter *self)
return self->pv->slot;
}
+/**
+ * gcr_importer_set_slot:
+ * @self: The importer
+ * @slot: The slot to import to
+ *
+ * Set the PKCS\#11 slot to import the items to.
+ */
void
gcr_importer_set_slot (GcrImporter *self, GckSlot *slot)
{
@@ -690,6 +764,14 @@ gcr_importer_set_slot (GcrImporter *self, GckSlot *slot)
g_object_notify (G_OBJECT (self), "slot");
}
+/**
+ * gcr_importer_get_prompt_behavior:
+ * @self: The importer
+ *
+ * Get the type of prompting configured for this importer.
+ *
+ * Returns: The prompting flags.
+ */
GcrImporterPromptBehavior
gcr_importer_get_prompt_behavior (GcrImporter *self)
{
@@ -697,6 +779,13 @@ gcr_importer_get_prompt_behavior (GcrImporter *self)
return self->pv->behavior;
}
+/**
+ * gcr_importer_set_prompt_behavior:
+ * @self: The importer
+ * @behavior: The prompt behavior flag
+ *
+ * Set the type of prompting desired during import.
+ */
void
gcr_importer_set_prompt_behavior (GcrImporter *self, GcrImporterPromptBehavior behavior)
{
@@ -705,8 +794,18 @@ gcr_importer_set_prompt_behavior (GcrImporter *self, GcrImporterPromptBehavior b
g_object_notify (G_OBJECT (self), "prompt-behavior");
}
+/**
+ * gcr_importer_import_async:
+ * @self: The importer
+ * @cancellable: An optional cancellation object
+ * @error: A location to raise an error on failure
+ *
+ * Start an synchronous import operation of the items that have been queued.
+ *
+ * Returns: Whether the import was successful or not.
+ */
gboolean
-gcr_importer_import (GcrImporter *self, GCancellable *cancel, GError **error)
+gcr_importer_import (GcrImporter *self, GCancellable *cancellable, GError **error)
{
g_return_val_if_fail (GCR_IS_IMPORTER (self), FALSE);
g_return_val_if_fail (!error || !*error, FALSE);
@@ -714,8 +813,8 @@ gcr_importer_import (GcrImporter *self, GCancellable *cancel, GError **error)
cleanup_import_data (self);
- if (cancel)
- self->pv->cancel = g_object_ref (cancel);
+ if (cancellable)
+ self->pv->cancel = g_object_ref (cancellable);
self->pv->processing = TRUE;
self->pv->async = FALSE;
@@ -733,8 +832,17 @@ gcr_importer_import (GcrImporter *self, GCancellable *cancel, GError **error)
return TRUE;
}
+/**
+ * gcr_importer_import_async:
+ * @self: The importer
+ * @cancellable: An optional cancellation object
+ * @callback: Call when the operation result is ready
+ * @user_data: Data to pass to the callback
+ *
+ * Start an asynchronous import operation of the items that have been queued.
+ */
void
-gcr_importer_import_async (GcrImporter *self, GCancellable *cancel,
+gcr_importer_import_async (GcrImporter *self, GCancellable *cancellable,
GAsyncReadyCallback callback, gpointer user_data)
{
g_return_if_fail (GCR_IS_IMPORTER (self));
@@ -742,8 +850,8 @@ gcr_importer_import_async (GcrImporter *self, GCancellable *cancel,
cleanup_import_data (self);
- if (cancel)
- self->pv->cancel = g_object_ref (cancel);
+ if (cancellable)
+ self->pv->cancel = g_object_ref (cancellable);
self->pv->processing = TRUE;
self->pv->async = TRUE;
self->pv->callback = callback;
@@ -753,11 +861,21 @@ gcr_importer_import_async (GcrImporter *self, GCancellable *cancel,
g_assert (self->pv->processing);
}
+/**
+ * gcr_importer_import_finish:
+ * @self: The importer
+ * @result: The operation result
+ * @error: A location to raise an error on failure.
+ *
+ * Complete an asynchronous import operation.
+ *
+ * Returns: Whether the operation was successful or not.
+ */
gboolean
-gcr_importer_import_finish (GcrImporter *self, GAsyncResult *res, GError **error)
+gcr_importer_import_finish (GcrImporter *self, GAsyncResult *result, GError **error)
{
g_return_val_if_fail (GCR_IS_IMPORTER (self), FALSE);
- g_return_val_if_fail (GCR_IMPORTER (res) == self, FALSE);
+ g_return_val_if_fail (GCR_IMPORTER (result) == self, FALSE);
g_return_val_if_fail (!error || !*error, FALSE);
g_return_val_if_fail (!self->pv->processing, FALSE);
@@ -772,7 +890,14 @@ gcr_importer_import_finish (GcrImporter *self, GAsyncResult *res, GError **error
return TRUE;
}
-
+/**
+ * gcr_importer_listen:
+ * @self: The importer
+ * @parser: The parser to listen to
+ *
+ * Listen for parse events from the #GcrParser, and queue parsed items for
+ * importing.
+ */
void
gcr_importer_listen (GcrImporter *self, GcrParser *parser)
{
@@ -784,6 +909,15 @@ gcr_importer_listen (GcrImporter *self, GcrParser *parser)
g_signal_connect_object (parser, "authenticate", G_CALLBACK (on_parser_authenticate), self, 0);
}
+/**
+ * gcr_importer_queue:
+ * @self: The importer
+ * @label: Label of item to import
+ * @attrs: Attributes of item to import
+ *
+ * Queue the importing of an item. Use gcr_importer_listen() to automatically
+ * queue items parsed by a #GcrParser.
+ */
void
gcr_importer_queue (GcrImporter *self, const gchar *label, GckAttributes *attrs)
{
@@ -796,6 +930,15 @@ gcr_importer_queue (GcrImporter *self, const gchar *label, GckAttributes *attrs)
#ifndef GCR_DISABLE_DEPRECATED
+/**
+ * gcr_importer_get_parser:
+ * @self: An importer
+ *
+ * Has no effect. Use gcr_importer_listen() instead.
+ *
+ * Returns: %NULL is always returned.
+ * Deprecated: Since 3.0.0
+ */
GcrParser*
gcr_importer_get_parser (GcrImporter *self)
{
@@ -804,6 +947,15 @@ gcr_importer_get_parser (GcrImporter *self)
return NULL;
}
+/**
+ * gcr_importer_set_parser:
+ * @self: An importer
+ * @parser: A parser
+ *
+ * Has no effect. Use gcr_importer_listen() instead.
+ *
+ * Deprecated: Since 3.0.0
+ */
void
gcr_importer_set_parser (GcrImporter *self, GcrParser *parser)
{
diff --git a/gcr/gcr-importer.h b/gcr/gcr-importer.h
index 3f68a53..574052a 100644
--- a/gcr/gcr-importer.h
+++ b/gcr/gcr-importer.h
@@ -52,6 +52,8 @@ typedef struct _GcrImporterPrivate GcrImporterPrivate;
struct _GcrImporter {
GObject parent;
+
+ /*< private >*/
GcrImporterPrivate *pv;
};
@@ -89,12 +91,12 @@ gboolean gcr_importer_import (GcrImporter *self
GError **error);
void gcr_importer_import_async (GcrImporter *self,
- GCancellable *cancel,
+ GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean gcr_importer_import_finish (GcrImporter *self,
- GAsyncResult *res,
+ GAsyncResult *result,
GError **error);
#ifndef GCR_DISABLE_DEPRECATED
diff --git a/gcr/gcr-key-renderer.c b/gcr/gcr-key-renderer.c
index 7f2fb4c..eb3a6ab 100644
--- a/gcr/gcr-key-renderer.c
+++ b/gcr/gcr-key-renderer.c
@@ -32,6 +32,20 @@
#include <gdk/gdk.h>
#include <glib/gi18n-lib.h>
+/**
+ * GcrKeyRenderer:
+ * @parent: The parent object
+ *
+ * An implementation of #GcrRenderer which renders keys.
+ */
+
+/**
+ * GcrKeyRendererClass:
+ * @parent_class: The parent class.
+ *
+ * The class for #GcrKeyRenderer.
+ */
+
enum {
PROP_0,
PROP_LABEL,
@@ -313,12 +327,30 @@ gcr_key_renderer_renderer_iface (GcrRendererIface *iface)
* PUBLIC
*/
+/**
+ * gcr_key_renderer_new:
+ * @label: Label describing the key
+ * @attrs: Key to display, or %NULL
+ *
+ * Create a new key renderer which renders a given key in the attributes.
+ *
+ * Returns: A newly allocated #GcrKeyRenderer, which should be freed
+ * with g_object_unref().
+ */
GcrKeyRenderer*
gcr_key_renderer_new (const gchar *label, GckAttributes *attrs)
{
return g_object_new (GCR_TYPE_KEY_RENDERER, "label", label, "attributes", attrs, NULL);
}
+/**
+ * gcr_key_renderer_set_attributes:
+ * @self: The key renderer
+ * @attrs: The attributes to display
+ *
+ * Get the attributes displayed in the renderer. The attributes should represent
+ * either an RSA or DSA key in PKCS\#11 style.
+ */
void
gcr_key_renderer_set_attributes (GcrKeyRenderer *self, GckAttributes *attrs)
{
@@ -334,6 +366,14 @@ gcr_key_renderer_set_attributes (GcrKeyRenderer *self, GckAttributes *attrs)
gcr_renderer_emit_data_changed (GCR_RENDERER (self));
}
+/**
+ * gcr_key_renderer_get_attributes:
+ * @self: The key renderer
+ *
+ * Get the attributes displayed in the renderer.
+ *
+ * Returns: The attributes, owned by the renderer.
+ */
GckAttributes*
gcr_key_renderer_get_attributes (GcrKeyRenderer *self)
{
diff --git a/gcr/gcr-key-renderer.h b/gcr/gcr-key-renderer.h
index a03780e..5d09aeb 100644
--- a/gcr/gcr-key-renderer.h
+++ b/gcr/gcr-key-renderer.h
@@ -44,6 +44,8 @@ typedef struct _GcrKeyRendererPrivate GcrKeyRendererPrivate;
struct _GcrKeyRenderer {
GObject parent;
+
+ /*< private >*/
GcrKeyRendererPrivate *pv;
};
diff --git a/gcr/gcr-key-widget.c b/gcr/gcr-key-widget.c
index 53fdde9..b2f4cca 100644
--- a/gcr/gcr-key-widget.c
+++ b/gcr/gcr-key-widget.c
@@ -29,6 +29,34 @@
#include <gdk/gdk.h>
#include <glib/gi18n-lib.h>
+/**
+ * SECTION:gcr-key-widget
+ * @title: GcrKeyWidget
+ * @short_description: Key widget and renderer
+ *
+ * A #GcrKeyWidget can be used to display a RSA or DSA key. The widget
+ * is normally in a collapsed state showing only details, but can be expanded
+ * by the user.
+ *
+ * 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:
+ * @parent: The parent object
+ *
+ * A widget that displays a key.
+ */
+
+/**
+ * GcrKeyWidgetClass:
+ *
+ * The class for #GcrKeyWidget
+ */
enum {
PROP_0,
PROP_ATTRIBUTES
@@ -153,12 +181,29 @@ gcr_key_widget_class_init (GcrKeyWidgetClass *klass)
* PUBLIC
*/
+/**
+ * gcr_key_widget_new:
+ * @attrs: Key to display, or %NULL
+ *
+ * Create a new key widget which displays a given key in the attributes.
+ *
+ * Returns: A newly allocated #GcrKeyWidget, which should be freed
+ * with g_object_unref().
+ */
GcrKeyWidget*
gcr_key_widget_new (GckAttributes *attrs)
{
return g_object_new (GCR_TYPE_KEY_WIDGET, "attributes", attrs, NULL);
}
+/**
+ * gcr_key_widget_set_attributes:
+ * @self: The key widget
+ * @attrs: The attributes to display
+ *
+ * Get the attributes displayed in the widget. The attributes should represent
+ * either an RSA or DSA key in PKCS\#11 style.
+ */
void
gcr_key_widget_set_attributes (GcrKeyWidget *self, GckAttributes *attrs)
{
@@ -166,6 +211,14 @@ gcr_key_widget_set_attributes (GcrKeyWidget *self, GckAttributes *attrs)
gcr_key_renderer_set_attributes (self->pv->renderer, attrs);
}
+/**
+ * gcr_key_widget_get_attributes:
+ * @self: The key widget
+ *
+ * Get the attributes displayed in the widget.
+ *
+ * Returns: The attributes, owned by the widget.
+ */
GckAttributes*
gcr_key_widget_get_attributes (GcrKeyWidget *self)
{
diff --git a/gcr/gcr-key-widget.h b/gcr/gcr-key-widget.h
index e943d43..7803aff 100644
--- a/gcr/gcr-key-widget.h
+++ b/gcr/gcr-key-widget.h
@@ -44,10 +44,13 @@ typedef struct _GcrKeyWidgetPrivate GcrKeyWidgetPrivate;
struct _GcrKeyWidget {
GtkAlignment parent;
+
+ /*< private >*/
GcrKeyWidgetPrivate *pv;
};
struct _GcrKeyWidgetClass {
+ /*< private >*/
GtkAlignmentClass parent_class;
};
diff --git a/gcr/gcr-library.c b/gcr/gcr-library.c
index d7e5f4c..5991a2a 100644
--- a/gcr/gcr-library.c
+++ b/gcr/gcr-library.c
@@ -55,6 +55,13 @@
* Trust assertions are stored and looked up in specific PKCS\#11 slots.
* You can examine this list with gcr_pkcs11_get_trust_lookup_slots()
*/
+
+/**
+ * GCR_DATA_ERROR:
+ *
+ * The #GError domain for data parsing errors.
+ */
+
static GList *all_modules = NULL;
static gchar *trust_store_uri = NULL;
@@ -73,15 +80,6 @@ gcr_data_error_get_domain (void)
return domain;
}
-GQuark
-gcr_error_get_domain (void)
-{
- static GQuark domain = 0;
- if (domain == 0)
- domain = g_quark_from_static_string ("gcr-error");
- return domain;
-}
-
/* -----------------------------------------------------------------------------
* MEMORY
*/
diff --git a/gcr/gcr-parser.c b/gcr/gcr-parser.c
index bc00f31..ed31f08 100644
--- a/gcr/gcr-parser.c
+++ b/gcr/gcr-parser.c
@@ -41,6 +41,80 @@
#include <stdlib.h>
#include <gcrypt.h>
+/**
+ * SECTION:gcr-parser
+ * @title: GcrParser
+ * @short_description: Parser for certificate and key files
+ *
+ * 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.
+ *
+ * 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().
+ *
+ * During the GcrParsed::parsed signal the attributes that make up the currently
+ * parsed item can be retrieved using the gcr_parser_get_parsed_attributes()
+ * function.
+ */
+
+/**
+ * GcrParser:
+ *
+ * A parser for parsing various types of files or data.
+ */
+
+/**
+ * GcrParserClass:
+ * @parent_class: The parent class
+ * @authenticate: The default handler for the authenticate signal.
+ * @parsed: The default handler for the parsed signal.
+ *
+ * The class for #GcrParser
+ */
+
+/**
+ * GcrDataFormat:
+ * @GCR_FORMAT_INVALID: Not a valid format
+ * @GCR_FORMAT_DER_PRIVATE_KEY: DER encoded private key
+ * @GCR_FORMAT_DER_PRIVATE_KEY_RSA: DER encoded RSA private key
+ * @GCR_FORMAT_DER_PRIVATE_KEY_DSA: DER encoded DSA private key
+ * @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_PKCS12: DER encoded PKCS\#12 file which can contain certificates and/or keys
+ * @GCR_FORMAT_PEM: An OpenSSL style PEM file with unspecified contents
+ * @GCR_FORMAT_PEM_PRIVATE_KEY_RSA: An OpenSSL style PEM file with a private RSA key
+ * @GCR_FORMAT_PEM_PRIVATE_KEY_DSA: An OpenSSL style PEM file with a private DSA 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_PKCS12: An OpenSSL style PEM file containing PKCS\#12
+ *
+ * The various format identifiers.
+ */
+
+/**
+ * GCR_DATA_ERROR:
+ *
+ * A domain for data errors with codes from #GcrDataError
+ */
+
+/**
+ * GcrDataError
+ * @GCR_ERROR_FAILURE: Failed to parse or serialize the data
+ * @GCR_ERROR_UNRECOGNIZED: The data was unrecognized or unsupported
+ * @GCR_ERROR_CANCELLED: The operation was cancelled
+ * @GCR_ERROR_LOCKED: The data was encrypted or locked and could not be unlocked.
+ *
+ * Values responding to error codes for parsing and serializing data.
+ */
+
enum {
PROP_0,
PROP_PARSED_LABEL,
@@ -1441,9 +1515,6 @@ static void
gcr_parser_set_property (GObject *obj, guint prop_id, const GValue *value,
GParamSpec *pspec)
{
-#if 0
- GcrParser *self = GCR_PARSER (obj);
-#endif
switch (prop_id) {
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (obj, prop_id, pspec);
@@ -1484,26 +1555,70 @@ gcr_parser_class_init (GcrParserClass *klass)
gobject_class->finalize = gcr_parser_finalize;
gobject_class->set_property = gcr_parser_set_property;
gobject_class->get_property = gcr_parser_get_property;
-
+
+ /**
+ * GcrParser:parsed-attributes:
+ *
+ * Get the attributes that make up the currently parsed item. This is
+ * generally only valid during a #GcrParser::parsed signal.
+ */
g_type_class_add_private (gobject_class, sizeof (GcrParserPrivate));
g_object_class_install_property (gobject_class, PROP_PARSED_ATTRIBUTES,
g_param_spec_boxed ("parsed-attributes", "Parsed Attributes", "Parsed PKCS#11 attributes",
GCK_TYPE_ATTRIBUTES, G_PARAM_READABLE));
+ /**
+ * GcrParser:parsed-label:
+ *
+ * The label of the currently parsed item. This is generally
+ * only valid during a #GcrParser::parsed signal.
+ */
g_object_class_install_property (gobject_class, PROP_PARSED_LABEL,
g_param_spec_string ("parsed-label", "Parsed Label", "Parsed item label",
"", G_PARAM_READABLE));
+ /**
+ * GcrParser:parsed-description:
+ *
+ * The description of the type of the currently parsed item. This is generally
+ * only valid during a #GcrParser::parsed signal.
+ */
g_object_class_install_property (gobject_class, PROP_PARSED_DESCRIPTION,
g_param_spec_string ("parsed-description", "Parsed Description", "Parsed item description",
"", G_PARAM_READABLE));
-
+
+ /**
+ * GcrParser::authenticate:
+ * @count: The number of times this item has been authenticated.
+ *
+ * This signal is emitted when an item needs to be unlocked or decrypted before
+ * it can be parsed. The @count argument specifies the number of times
+ * the signal has been emitted for a given item. This can be used to
+ * display a message saying the previous password was incorrect.
+ *
+ * Typically the gcr_parser_add_password() function is called in
+ * response to this signal.
+ *
+ * If %FALSE is returned, then the authentication was not handled. If
+ * no handlers return %TRUE then the item is not parsed and an error
+ * with the code %GCR_ERROR_CANCELLED will be raised.
+ *
+ * Returns: Whether the authentication was handled.
+ */
signals[AUTHENTICATE] = g_signal_new ("authenticate", GCR_TYPE_PARSER,
G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GcrParserClass, authenticate),
g_signal_accumulator_true_handled, NULL, _gcr_marshal_BOOLEAN__INT,
G_TYPE_BOOLEAN, 1, G_TYPE_POINTER);
+ /**
+ * GcrParser::parsed:
+ *
+ * This signal is emitted when an item is sucessfully parsed. To access
+ * the information about the item use the gcr_parser_get_parsed_label(),
+ * gcr_parser_get_parsed_attributes() and gcr_parser_get_parsed_description()
+ * functions.
+ */
signals[PARSED] = g_signal_new ("parsed", GCR_TYPE_PARSER,
G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GcrParserClass, parsed),
NULL, NULL, g_cclosure_marshal_VOID__VOID,
@@ -1521,12 +1636,27 @@ gcr_parser_class_init (GcrParserClass *klass)
* PUBLIC
*/
+/**
+ * gcr_parser_new:
+ *
+ * Create a new #GcrParser
+ *
+ * Returns: A newly allocated #GcrParser
+ */
GcrParser*
gcr_parser_new (void)
{
return g_object_new (GCR_TYPE_PARSER, NULL);
}
+/**
+ * gcr_parser_add_password:
+ * @self: The parser
+ * @password: A password to try
+ *
+ * Add a password to the set of passwords to try when parsing locked or encrypted
+ * items. This is usually called from the GcrParser::authenticate signal.
+ */
void
gcr_parser_add_password (GcrParser *self, const gchar *password)
{
@@ -1534,9 +1664,21 @@ gcr_parser_add_password (GcrParser *self, const gchar *password)
g_ptr_array_add (self->pv->passwords, egg_secure_strdup (password));
}
+/**
+ * gcr_parser_parse_data:
+ * @self: The parser
+ * @data: The data to parse
+ * @n_data: The length of the data
+ * @error: A location to raise an error on failure.
+ *
+ * Parse the data. The GcrParser::parsed and GcrParser::authenticate signals
+ * may fire during the parsing.
+ *
+ * Returns: Whether the data was parsed successfully or not.
+ */
gboolean
gcr_parser_parse_data (GcrParser *self, gconstpointer data,
- gsize n_data, GError **err)
+ gsize n_data, GError **error)
{
ForeachArgs args = { self, data, n_data, GCR_ERROR_UNRECOGNIZED };
const gchar *message;
@@ -1544,7 +1686,7 @@ gcr_parser_parse_data (GcrParser *self, gconstpointer data,
g_return_val_if_fail (GCR_IS_PARSER (self), FALSE);
g_return_val_if_fail (data || !n_data, FALSE);
- g_return_val_if_fail (!err || !*err, FALSE);
+ g_return_val_if_fail (!error || !*error, FALSE);
/* Just the specific formats requested */
if (self->pv->specific_formats) {
@@ -1578,66 +1720,84 @@ gcr_parser_parse_data (GcrParser *self, gconstpointer data,
g_assert_not_reached ();
break;
};
-
- g_set_error_literal (err, GCR_DATA_ERROR, args.result, message);
+
+ g_set_error_literal (error, GCR_DATA_ERROR, args.result, message);
return FALSE;
}
-gboolean
+/**
+ * gcr_parser_format_disable:
+ * @self: The parser
+ * @format_id: The format identifier
+ *
+ * Enable parsing of the given format. Use -1 to enable all the formats.
+ */
+void
gcr_parser_format_enable (GcrParser *self, gint format_id)
{
ParserFormat *format;
-
- g_return_val_if_fail (GCR_IS_PARSER (self), FALSE);
-
+
+ g_return_if_fail (GCR_IS_PARSER (self));
+
if (format_id == -1) {
if (self->pv->specific_formats)
g_tree_destroy (self->pv->specific_formats);
self->pv->specific_formats = NULL;
self->pv->normal_formats = TRUE;
- return TRUE;
+ return;
}
-
+
format = parser_format_lookup (format_id);
- if (format == NULL)
- return FALSE;
-
+ g_return_if_fail (format);
+
if (!self->pv->specific_formats) {
if (self->pv->normal_formats)
- return TRUE;
+ return;
self->pv->specific_formats = g_tree_new (compare_pointers);
}
-
+
g_tree_insert (self->pv->specific_formats, format, format);
- return TRUE;
}
-gboolean
+/**
+ * gcr_parser_format_disable:
+ * @self: The parser
+ * @format_id: The format identifier
+ *
+ * Disable parsing of the given format. Use -1 to disable all the formats.
+ */
+void
gcr_parser_format_disable (GcrParser *self, gint format_id)
{
ParserFormat *format;
-
- g_return_val_if_fail (GCR_IS_PARSER (self), FALSE);
-
+
+ g_return_if_fail (GCR_IS_PARSER (self));
+
if (format_id == -1) {
if (self->pv->specific_formats)
g_tree_destroy (self->pv->specific_formats);
self->pv->specific_formats = NULL;
self->pv->normal_formats = FALSE;
- return TRUE;
}
-
+
if (!self->pv->specific_formats)
- return TRUE;
-
+ return;
+
format = parser_format_lookup (format_id);
- if (format == NULL)
- return FALSE;
-
+ g_return_if_fail (format);
+
g_tree_remove (self->pv->specific_formats, format);
- return TRUE;
}
+/**
+ * gcr_parser_format_supported:
+ * @self: The parser
+ * @format_id: The format identifier
+ *
+ * Check whether the given format is supported by the parser.
+ *
+ * Returns: Whether the format is supported.
+ */
gboolean
gcr_parser_format_supported (GcrParser *self, gint format_id)
{
@@ -1646,6 +1806,16 @@ gcr_parser_format_supported (GcrParser *self, gint format_id)
return parser_format_lookup (format_id) ? TRUE : FALSE;
}
+/**
+ * gcr_parser_get_parsed_description:
+ * @self: The parser
+ *
+ * Get a description for the type of the currently parsed item. This is generally
+ * only valid during the GcrParser::parsed signal.
+ *
+ * Returns: The description for the current item. This is owned by the parser
+ * and should not be freed.
+ */
const gchar*
gcr_parser_get_parsed_description (GcrParser *self)
{
@@ -1653,6 +1823,16 @@ gcr_parser_get_parsed_description (GcrParser *self)
return self->pv->parsed_desc;
}
+/**
+ * gcr_parser_get_parsed_attributes:
+ * @self: The parser
+ *
+ * Get the attributes which make up the currently parsed item. This is generally
+ * only valid during the GcrParser::parsed signal.
+ *
+ * Returns: The attributes for the current item. These are owned by the parser
+ * and should not be freed.
+ */
GckAttributes*
gcr_parser_get_parsed_attributes (GcrParser *self)
{
@@ -1660,11 +1840,21 @@ gcr_parser_get_parsed_attributes (GcrParser *self)
return self->pv->parsed_attrs;
}
+/**
+ * gcr_parser_get_parsed_label:
+ * @self: The parser
+ *
+ * Get the label of the currently parsed item. This is generally only valid
+ * during the GcrParser::parsed signal.
+ *
+ * Returns: The label of the currently parsed item. The value is owned by
+ * the parser and should not be freed.
+ */
const gchar*
gcr_parser_get_parsed_label (GcrParser *self)
{
g_return_val_if_fail (GCR_IS_PARSER (self), NULL);
- return self->pv->parsed_label;
+ return self->pv->parsed_label;
}
/* ---------------------------------------------------------------------------------
@@ -1914,8 +2104,24 @@ gcr_parsing_new (GcrParser *parser, GInputStream *input, GCancellable *cancel)
return self;
}
+/**
+ * gcr_parser_parse_stream:
+ * @self: The parser
+ * @input: The input stream
+ * @cancellable: An optional cancellation object
+ * @error: A location to raise an error on failure
+ *
+ * Parse items from the data in a #GInputStream. This function may block while
+ * reading from the input stream. Use gcr_parser_parse_stream_async() for
+ * a non-blocking variant.
+ *
+ * The GcrParser::parsed and GcrParser::authenticate signals
+ * may fire during the parsing.
+ *
+ * Returns: Whether the parsing completed successfully or not.
+ */
gboolean
-gcr_parser_parse_stream (GcrParser *self, GInputStream *input, GCancellable *cancel,
+gcr_parser_parse_stream (GcrParser *self, GInputStream *input, GCancellable *cancellable,
GError **error)
{
GcrParsing *parsing;
@@ -1924,7 +2130,7 @@ gcr_parser_parse_stream (GcrParser *self, GInputStream *input, GCancellable *can
g_return_val_if_fail (G_IS_INPUT_STREAM (self), FALSE);
g_return_val_if_fail (!error || !*error, FALSE);
- parsing = gcr_parsing_new (self, input, cancel);
+ parsing = gcr_parsing_new (self, input, cancellable);
parsing->async = FALSE;
next_state (parsing, state_read_buffer);
@@ -1933,8 +2139,22 @@ gcr_parser_parse_stream (GcrParser *self, GInputStream *input, GCancellable *can
return gcr_parser_parse_stream_finish (self, G_ASYNC_RESULT (parsing), error);
}
+/**
+ * gcr_parser_parse_stream_async:
+ * @self: The parser
+ * @input: The input stream
+ * @cancellable: An optional cancellation object
+ * @callback: Called when the operation result is ready.
+ * @user_data: Data to pass to callback
+ *
+ * Parse items from the data in a #GInputStream. This function completes
+ * asyncronously and doesn't block.
+ *
+ * The GcrParser::parsed and GcrParser::authenticate signals
+ * may fire during the parsing.
+ */
void
-gcr_parser_parse_stream_async (GcrParser *self, GInputStream *input, GCancellable *cancel,
+gcr_parser_parse_stream_async (GcrParser *self, GInputStream *input, GCancellable *cancellable,
GAsyncReadyCallback callback, gpointer user_data)
{
GcrParsing *parsing;
@@ -1942,7 +2162,7 @@ gcr_parser_parse_stream_async (GcrParser *self, GInputStream *input, GCancellabl
g_return_if_fail (GCR_IS_PARSER (self));
g_return_if_fail (G_IS_INPUT_STREAM (input));
- parsing = gcr_parsing_new (self, input, cancel);
+ parsing = gcr_parsing_new (self, input, cancellable);
parsing->async = TRUE;
parsing->callback = callback;
parsing->user_data = user_data;
@@ -1950,15 +2170,25 @@ gcr_parser_parse_stream_async (GcrParser *self, GInputStream *input, GCancellabl
next_state (parsing, state_read_buffer);
}
+/**
+ * gcr_parser_parse_stream_finish:
+ * @self: The parser
+ * @result:The operation result
+ * @error: A location to raise an error on failure
+ *
+ * Complete an operation to parse a stream.
+ *
+ * Returns: Whether the parsing completed successfully or not.
+ */
gboolean
-gcr_parser_parse_stream_finish (GcrParser *self, GAsyncResult *res, GError **error)
+gcr_parser_parse_stream_finish (GcrParser *self, GAsyncResult *result, GError **error)
{
GcrParsing *parsing;
- g_return_val_if_fail (GCR_IS_PARSING (res), FALSE);
+ g_return_val_if_fail (GCR_IS_PARSING (result), FALSE);
g_return_val_if_fail (!error || !*error, FALSE);
- parsing = GCR_PARSING (res);
+ parsing = GCR_PARSING (result);
g_return_val_if_fail (parsing->complete, FALSE);
if (parsing->error) {
diff --git a/gcr/gcr-parser.h b/gcr/gcr-parser.h
index 4d9bc10..f52972a 100644
--- a/gcr/gcr-parser.h
+++ b/gcr/gcr-parser.h
@@ -41,20 +41,21 @@ G_BEGIN_DECLS
#define GCR_PARSER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GCR_TYPE_PARSER, GcrParserClass))
typedef struct _GcrParser GcrParser;
-typedef struct _GcrParsedItem GcrParsedItem;
typedef struct _GcrParserClass GcrParserClass;
typedef struct _GcrParserPrivate GcrParserPrivate;
struct _GcrParser {
GObject parent;
+
+ /*< private >*/
GcrParserPrivate *pv;
};
struct _GcrParserClass {
GObjectClass parent_class;
-
+
/* signals --------------------------------------------------------- */
-
+
/* A callback for each password needed */
gboolean (*authenticate) (GcrParser *self, gint count);
@@ -65,33 +66,33 @@ GType gcr_parser_get_type (void);
GcrParser* gcr_parser_new (void);
-gboolean gcr_parser_format_enable (GcrParser *self,
- gint format);
+void gcr_parser_format_enable (GcrParser *self,
+ gint format_id);
-gboolean gcr_parser_format_disable (GcrParser *self,
- gint format);
+void gcr_parser_format_disable (GcrParser *self,
+ gint format_id);
gboolean gcr_parser_format_supported (GcrParser *self,
- gint format);
+ gint format_id);
gboolean gcr_parser_parse_data (GcrParser *self,
gconstpointer data,
gsize n_data,
- GError **err);
+ GError **error);
gboolean gcr_parser_parse_stream (GcrParser *self,
GInputStream *input,
- GCancellable *cancel,
+ GCancellable *cancellable,
GError **error);
void gcr_parser_parse_stream_async (GcrParser *self,
GInputStream *input,
- GCancellable *cancel,
+ GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean gcr_parser_parse_stream_finish (GcrParser *self,
- GAsyncResult *res,
+ GAsyncResult *result,
GError **error);
void gcr_parser_add_password (GcrParser *self,
diff --git a/gcr/gcr-pkcs11-certificate.c b/gcr/gcr-pkcs11-certificate.c
index e8dbd31..facef9d 100644
--- a/gcr/gcr-pkcs11-certificate.c
+++ b/gcr/gcr-pkcs11-certificate.c
@@ -49,6 +49,18 @@
* 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
diff --git a/gcr/gcr-pkcs11-certificate.h b/gcr/gcr-pkcs11-certificate.h
index bc25b4c..e7ed464 100644
--- a/gcr/gcr-pkcs11-certificate.h
+++ b/gcr/gcr-pkcs11-certificate.h
@@ -48,10 +48,13 @@ typedef struct _GcrPkcs11CertificatePrivate GcrPkcs11CertificatePrivate;
struct _GcrPkcs11Certificate {
GckObject parent;
+
+ /*< private >*/
GcrPkcs11CertificatePrivate *pv;
};
struct _GcrPkcs11CertificateClass {
+ /*< private >*/
GckObjectClass parent_class;
};
diff --git a/gcr/gcr-renderer.c b/gcr/gcr-renderer.c
index 59ca30a..6524b63 100644
--- a/gcr/gcr-renderer.c
+++ b/gcr/gcr-renderer.c
@@ -27,6 +27,37 @@
#include <gtk/gtk.h>
+/**
+ * SECTION:gcr-renderer
+ * @title: GcrRenderer
+ * @short_description: An interface implemented by renderers.
+ *
+ * A #GcrRenderer is an interface that's implemented by renderers which wish
+ * to render data to a #GcrViewer.
+ *
+ * The interaction between #GcrRenderer and #GcrViewer 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
+ * the data in those attributes.
+ */
+
+/**
+ * GcrRenderer:
+ *
+ * A renderer.
+ */
+
+/**
+ * GcrRendererIface:
+ * @parent: The parent interface
+ * @data_changed: The GcrRenderer::data-changed signal
+ * @render: A virtual method to render the contents.
+ *
+ * The interface for #GcrRenderer
+ */
+
enum {
DATA_CHANGED,
LAST_SIGNAL
@@ -48,14 +79,30 @@ gcr_renderer_base_init (gpointer gobject_iface)
static gboolean initialized = FALSE;
if (!initialized) {
+ /**
+ * GcrRenderer:label:
+ *
+ * The label to display.
+ */
g_object_interface_install_property (gobject_iface,
g_param_spec_string ("label", "Label", "The label for the renderer",
"", G_PARAM_READWRITE));
+ /**
+ * GcrRenderer:attributes:
+ *
+ * The attributes to display.
+ */
g_object_interface_install_property (gobject_iface,
g_param_spec_boxed ("attributes", "Attributes", "The data displayed in the renderer",
GCK_TYPE_ATTRIBUTES, G_PARAM_READWRITE));
+ /**
+ * GcrRenderer::data-changed:
+ *
+ * A signal that is emitted by the renderer when it's data
+ * changed and should be rerendered.
+ */
signals[DATA_CHANGED] = g_signal_new ("data-changed", GCR_TYPE_RENDERER, G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GcrRendererIface, data_changed),
NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
@@ -80,6 +127,13 @@ gcr_renderer_get_type (void)
return type;
}
+/**
+ * gcr_renderer_render:
+ * @self: The renderer
+ * @viewer: The viewer to render to.
+ *
+ * Render the contents of the renderer to the given viewer.
+ */
void
gcr_renderer_render (GcrRenderer *self, GcrViewer *viewer)
{
@@ -88,6 +142,13 @@ gcr_renderer_render (GcrRenderer *self, GcrViewer *viewer)
GCR_RENDERER_GET_INTERFACE (self)->render (self, viewer);
}
+/**
+ * gcr_renderer_emit_data_changed:
+ * @self: The renderer
+ *
+ * Emit the GcrRenderer::data-changed signal on the renderer. This is used by
+ * renderer implementations.
+ */
void
gcr_renderer_emit_data_changed (GcrRenderer *self)
{
@@ -114,6 +175,17 @@ sort_registered_by_n_attrs (gconstpointer a, gconstpointer b)
return (na == nb) ? 0 : -1;
}
+/**
+ * gcr_renderer_create:
+ * @label: The label for the renderer
+ * @attrs: The attributes to render
+ *
+ * Create and initialize a renderer for the given attributes and label. These
+ * renderers should have been preregistered via gcr_renderer_register().
+ *
+ * Returns: A new renderer, or %NULL if no renderer matched the attributes.
+ * The render should be released with g_object-unref().
+ */
GcrRenderer*
gcr_renderer_create (const gchar *label, GckAttributes *attrs)
{
@@ -154,6 +226,14 @@ gcr_renderer_create (const gchar *label, GckAttributes *attrs)
return NULL;
}
+/**
+ * gcr_renderer_register:
+ * @renderer_type: The renderer class type
+ * @attrs: The attributes to match
+ *
+ * Register a renderer to be created when matching attributes are passed to
+ * gcr_renderer_create().
+ */
void
gcr_renderer_register (GType renderer_type, GckAttributes *attrs)
{
diff --git a/gcr/gcr-renderer.h b/gcr/gcr-renderer.h
index a9bde34..b18bbe3 100644
--- a/gcr/gcr-renderer.h
+++ b/gcr/gcr-renderer.h
@@ -45,6 +45,7 @@ struct _GcrRendererIface {
/* virtual */
void (*render) (GcrRenderer *self, GcrViewer *viewer);
+ /*< private >*/
gpointer dummy1;
gpointer dummy2;
gpointer dummy3;
diff --git a/gcr/gcr-simple-certificate.c b/gcr/gcr-simple-certificate.c
index 5ec7ff2..84401fd 100644
--- a/gcr/gcr-simple-certificate.c
+++ b/gcr/gcr-simple-certificate.c
@@ -40,6 +40,19 @@
* functions.
*/
+/**
+ * GcrSimpleCertificate:
+ *
+ * A #GcrCertificate which represents a certificate already in memory.
+ */
+
+/**
+ * GcrSimpleCertificateClass:
+ * @parent_class: The parent class
+ *
+ * The class for #GcrSimpleCertificate.
+ */
+
struct _GcrSimpleCertificatePrivate {
const guchar *data;
gsize n_data;
diff --git a/gcr/gcr-simple-certificate.h b/gcr/gcr-simple-certificate.h
index d32c0e2..59bd541 100644
--- a/gcr/gcr-simple-certificate.h
+++ b/gcr/gcr-simple-certificate.h
@@ -45,6 +45,8 @@ typedef struct _GcrSimpleCertificatePrivate GcrSimpleCertificatePrivate;
struct _GcrSimpleCertificate {
GObject parent;
+
+ /*< private >*/
GcrSimpleCertificatePrivate *pv;
};
diff --git a/gcr/gcr-trust.c b/gcr/gcr-trust.c
index c252c33..d255d97 100644
--- a/gcr/gcr-trust.c
+++ b/gcr/gcr-trust.c
@@ -91,7 +91,7 @@
*/
/**
- * GCR_PURPOSE_CODE_SIGNING:
+ * GCR_PURPOSE_EMAIL:
*
* The purpose used to verify certificates that are used in email communication
* such as S/MIME.
diff --git a/gcr/gcr-types.h b/gcr/gcr-types.h
index 0f38967..ba6d85c 100644
--- a/gcr/gcr-types.h
+++ b/gcr/gcr-types.h
@@ -47,34 +47,30 @@ G_BEGIN_DECLS
GQuark gcr_data_error_get_domain (void) G_GNUC_CONST;
-enum {
+typedef enum {
GCR_ERROR_FAILURE = -1,
GCR_ERROR_UNRECOGNIZED = 1,
GCR_ERROR_CANCELLED = 2,
GCR_ERROR_LOCKED = 3
-};
+} GcrDataError;
-#define GCR_ERROR (gcr_error_get_domain ())
-
-GQuark gcr_error_get_domain (void) G_GNUC_CONST;
-
-enum {
+typedef enum {
GCR_FORMAT_INVALID = 0,
-
+
GCR_FORMAT_DER_PRIVATE_KEY = 100,
GCR_FORMAT_DER_PRIVATE_KEY_RSA,
GCR_FORMAT_DER_PRIVATE_KEY_DSA,
-
+
GCR_FORMAT_DER_CERTIFICATE_X509 = 200,
GCR_FORMAT_DER_PKCS7 = 300,
-
+
GCR_FORMAT_DER_PKCS8 = 400,
GCR_FORMAT_DER_PKCS8_PLAIN,
GCR_FORMAT_DER_PKCS8_ENCRYPTED,
-
+
GCR_FORMAT_DER_PKCS12 = 500,
-
+
GCR_FORMAT_PEM = 1000,
GCR_FORMAT_PEM_PRIVATE_KEY_RSA,
GCR_FORMAT_PEM_PRIVATE_KEY_DSA,
@@ -83,7 +79,7 @@ enum {
GCR_FORMAT_PEM_PKCS8_PLAIN,
GCR_FORMAT_PEM_PKCS8_ENCRYPTED,
GCR_FORMAT_PEM_PKCS12
-};
+} GcrDataFormat;
G_END_DECLS
diff --git a/gcr/gcr-unlock-options-widget.c b/gcr/gcr-unlock-options-widget.c
index 6939c46..cce15eb 100644
--- a/gcr/gcr-unlock-options-widget.c
+++ b/gcr/gcr-unlock-options-widget.c
@@ -23,6 +23,58 @@
#include <glib/gi18n-lib.h>
+/**
+ * SECTION:gcr-unlock-options-widget
+ * @title: GcrUnlockOptionsWidget
+ * @short_description: A widget for unlock options
+ *
+ * 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.
+ *
+ * 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().
+ */
+
+/**
+ * GCR_UNLOCK_OPTION_ALWAYS:
+ *
+ * Option name for caching unlock indefinitely.
+ */
+
+/**
+ * GCR_UNLOCK_OPTION_IDLE:
+ *
+ * Option name for caching unlock for a certain amount of idle time.
+ */
+
+/**
+ * GCR_UNLOCK_OPTION_SESSION:
+ *
+ * Option name for caching unlock for the current session.
+ */
+
+/**
+ * GCR_UNLOCK_OPTION_TIMEOUT:
+ *
+ * Option name for caching unlock for a certain amount of time.
+ */
+
+/**
+ * GcrUnlockOptionsWidget:
+ * @parent: The parent object
+ *
+ * An unlock options widget.
+ */
+
+/**
+ * GcrUnlockOptionsWidgetClass:
+ * @parent_class: The parent class
+ *
+ * Class for #GcrUnlockOptionsWidget.
+ */
+
enum {
PROP_0,
PROP_CHOICE,
@@ -249,12 +301,27 @@ gcr_unlock_options_widget_class_init (GcrUnlockOptionsWidgetClass *klass)
* PUBLIC
*/
+/**
+ * gcr_unlock_options_widget_new:
+ *
+ * Create a new #GcrUnlockOptionsWidget.
+ *
+ * Returns: A new #GcrUnlockOptionsWidget.
+ */
GtkWidget*
gcr_unlock_options_widget_new (void)
{
return g_object_new (GCR_TYPE_UNLOCK_OPTIONS_WIDGET, NULL);
}
+/**
+ * gcr_unlock_options_widget_get_choice:
+ * @self: The unlock options widget
+ *
+ * Get the currently selected option, like %GCR_UNLOCK_OPTION_ALWAYS.
+ *
+ * Returns: The currently selected option name.
+ */
const gchar*
gcr_unlock_options_widget_get_choice (GcrUnlockOptionsWidget *self)
{
@@ -262,6 +329,14 @@ gcr_unlock_options_widget_get_choice (GcrUnlockOptionsWidget *self)
return self->pv->choice;
}
+/**
+ * gcr_unlock_options_widget_set_choice:
+ * @self: The unlock options widget
+ * @option: The option name
+ *
+ * Set the currently selected option. Use an option name like
+ * %GCR_UNLOCK_OPTION_ALWAYS.
+ */
void
gcr_unlock_options_widget_set_choice (GcrUnlockOptionsWidget *self, const gchar *option)
{
@@ -274,6 +349,16 @@ gcr_unlock_options_widget_set_choice (GcrUnlockOptionsWidget *self, const gchar
gtk_toggle_button_set_active (button, TRUE);
}
+/**
+ * gcr_unlock_options_widget_get_ttl:
+ * @self: The unlock options widget
+ *
+ * Get the timeout setting set for unlock options that have a timeout.
+ * This will also return a valid value if the currently selected option
+ * does not have a timeout.
+ *
+ * Returns: The unlock timeout in seconds.
+ */
guint
gcr_unlock_options_widget_get_ttl (GcrUnlockOptionsWidget *self)
{
@@ -287,6 +372,14 @@ gcr_unlock_options_widget_get_ttl (GcrUnlockOptionsWidget *self)
return amount * 60;
}
+/**
+ * gcr_unlock_options_widget_set_ttl:
+ * @self: The unlock options widget
+ * @ttl: The timeout to set, in seconds
+ *
+ * Set the current setting for the timeout. This can be set even when the
+ * currently selected option does not have a timeout.
+ */
void
gcr_unlock_options_widget_set_ttl (GcrUnlockOptionsWidget *self, guint ttl)
{
@@ -303,6 +396,16 @@ gcr_unlock_options_widget_set_ttl (GcrUnlockOptionsWidget *self, guint ttl)
gtk_spin_button_set_value (spin, amount);
}
+/**
+ * gcr_unlock_options_widget_get_label:
+ * @self: The unlock options widget
+ * @option: The option name
+ *
+ * Get the label for one of the options. Use an option name like
+ * %GCR_UNLOCK_OPTION_ALWAYS.
+ *
+ * Returns: The current label for the option.
+ */
const gchar*
gcr_unlock_options_widget_get_label (GcrUnlockOptionsWidget *self, const gchar *option)
{
@@ -321,6 +424,15 @@ gcr_unlock_options_widget_get_label (GcrUnlockOptionsWidget *self, const gchar *
return gtk_button_get_label (GTK_BUTTON (button));
}
+/**
+ * gcr_unlock_options_widget_set_label:
+ * @self: The unlock options widget
+ * @option: The option name
+ * @text: The new label
+ *
+ * Set the label for one of the options. Use an option name like
+ * %GCR_UNLOCK_OPTION_ALWAYS.
+ */
void
gcr_unlock_options_widget_set_label (GcrUnlockOptionsWidget *self, const gchar *option,
const gchar *text)
@@ -341,6 +453,16 @@ gcr_unlock_options_widget_set_label (GcrUnlockOptionsWidget *self, const gchar *
gtk_button_set_label (GTK_BUTTON (button), text);
}
+/**
+ * gcr_unlock_options_widget_get_sensitive:
+ * @self: The unlock options widget
+ * @option: The option name
+ *
+ * Get the sensitivity state for one of the options. Use an option name like
+ * %GCR_UNLOCK_OPTION_ALWAYS.
+ *
+ * Returns: Whether the option is sensitive or not.
+ */
gboolean
gcr_unlock_options_widget_get_sensitive (GcrUnlockOptionsWidget *self, const gchar *option)
{
@@ -355,6 +477,16 @@ gcr_unlock_options_widget_get_sensitive (GcrUnlockOptionsWidget *self, const gch
return (state & GTK_STATE_INSENSITIVE) != GTK_STATE_INSENSITIVE;
}
+/**
+ * gcr_unlock_options_widget_set_sensitive:
+ * @self: The unlock options widget
+ * @option: The option name
+ * @sensitive: The sensitivity state.
+ * @reason: A user displayable string which contains the reason for the sensitivity.
+ *
+ * Set the sensitivity state for one of the options. Use an option name like
+ * %GCR_UNLOCK_OPTION_ALWAYS. The reason will be displayed as a tooltip.
+ */
void
gcr_unlock_options_widget_set_sensitive (GcrUnlockOptionsWidget *self, const gchar *option,
gboolean sensitive, const gchar *reason)
diff --git a/gcr/gcr-unlock-options-widget.h b/gcr/gcr-unlock-options-widget.h
index 1e1ade6..e48bc28 100644
--- a/gcr/gcr-unlock-options-widget.h
+++ b/gcr/gcr-unlock-options-widget.h
@@ -45,6 +45,8 @@ typedef struct _GcrUnlockOptionsWidgetPrivate GcrUnlockOptionsWidgetPrivate;
struct _GcrUnlockOptionsWidget {
GtkAlignment parent;
+
+ /*< private >*/
GcrUnlockOptionsWidgetPrivate *pv;
};
diff --git a/gcr/gcr-viewer.c b/gcr/gcr-viewer.c
index 498f5b5..36f0bae 100644
--- a/gcr/gcr-viewer.c
+++ b/gcr/gcr-viewer.c
@@ -24,10 +24,37 @@
#include "gcr-renderer.h"
#include "gcr-viewer.h"
-/* -----------------------------------------------------------------------------
- * INTERFACE
+/**
+ * SECTION:gcr-viewer
+ * @title: GcrViewer
+ * @short_description: A viewer which can hold renderers
+ *
+ * A #GcrViewer is 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.
+ *
+ * Use the gcr_viewer_new() and gcr_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
+ * @remove_renderer: Virtual method to remove a renderer
+ * @count_renderers: Virtual method to count renderers
+ * @get_renderer: Virtual method to get a renderer
+ *
+ * The interface for #GcrViewer
+ */
static void
gcr_viewer_base_init (gpointer gobject_iface)
{
@@ -59,18 +86,43 @@ gcr_viewer_get_type (void)
* PUBLIC
*/
+/**
+ * gcr_viewer_new:
+ *
+ * Get an implementation of #GcrViewer that supports a view
+ * of multiple renderers.
+ *
+ * Returns: A newly allocated #GcrViewer, which should be released with
+ * g_object_unref()
+ */
GcrViewer*
gcr_viewer_new (void)
{
return GCR_VIEWER (_gcr_display_view_new ());
}
+/**
+ * gcr_viewer_new_scrolled:
+ *
+ * Get an implementation of #GcrViewer that supports a scrolled view
+ * of multiple renderers.
+ *
+ * Returns: A newly allocated #GcrViewer, which should be released with
+ * g_object_unref()
+ */
GcrViewer*
gcr_viewer_new_scrolled (void)
{
return GCR_VIEWER (_gcr_display_scrolled_new ());
}
+/**
+ * gcr_viewer_add_renderer:
+ * @self: The viewer
+ * @renderer: The renderer to add
+ *
+ * Add a renderer to this viewer.
+ */
void
gcr_viewer_add_renderer (GcrViewer *self, GcrRenderer *renderer)
{
@@ -80,6 +132,13 @@ gcr_viewer_add_renderer (GcrViewer *self, GcrRenderer *renderer)
GCR_VIEWER_GET_INTERFACE (self)->add_renderer (self, renderer);
}
+/**
+ * gcr_viewer_remove_renderer:
+ * @self: The viewer
+ * @renderer: The renderer to remove
+ *
+ * Remove a renderer from this viewer.
+ */
void
gcr_viewer_remove_renderer (GcrViewer *self, GcrRenderer *renderer)
{
@@ -89,6 +148,14 @@ gcr_viewer_remove_renderer (GcrViewer *self, GcrRenderer *renderer)
GCR_VIEWER_GET_INTERFACE (self)->remove_renderer (self, renderer);
}
+/**
+ * gcr_viewer_count_renderers:
+ * @self: The viewer
+ *
+ * Get the number of renderers present in the viewer.
+ *
+ * Returns: The number of renderers.
+ */
guint
gcr_viewer_count_renderers (GcrViewer *self)
{
@@ -97,6 +164,16 @@ gcr_viewer_count_renderers (GcrViewer *self)
return GCR_VIEWER_GET_INTERFACE (self)->count_renderers (self);
}
+/**
+ * gcr_viewer_get_renderer:
+ * @self: The viewer
+ * @index_: The index of the renderer to get
+ *
+ * Get a pointer to the renderer at the given index. It is an error to request
+ * an index that is out of bounds.
+ *
+ * Returns: The render, owned by the viewer.
+ */
GcrRenderer*
gcr_viewer_get_renderer (GcrViewer *self, guint index_)
{
diff --git a/gcr/gcr-viewer.h b/gcr/gcr-viewer.h
index c4d2040..20956ee 100644
--- a/gcr/gcr-viewer.h
+++ b/gcr/gcr-viewer.h
@@ -47,6 +47,7 @@ struct _GcrViewerIface {
GcrRenderer* (*get_renderer) (GcrViewer *self, guint index_);
+ /*< private >*/
gpointer dummy1;
gpointer dummy2;
gpointer dummy3;
@@ -68,7 +69,7 @@ void gcr_viewer_remove_renderer (GcrViewer *self,
guint gcr_viewer_count_renderers (GcrViewer *self);
GcrRenderer* gcr_viewer_get_renderer (GcrViewer *self,
- guint at);
+ guint index_);
G_END_DECLS
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
