gcr: Add more comments for new colons and collection code.

diff --git a/gcr/gcr-colons.c b/gcr/gcr-colons.c
index 4a54934..6a5d6be 100644 (file)
--- a/gcr/gcr-colons.c
+++ b/gcr/gcr-colons.c
@@ -100,6 +100,7 @@ _gcr_colons_get_string (GcrColons *colons, guint column)
        if (g_utf8_validate (text, -1, NULL))
                return text;
 
+       /* If it's not UTF-8, we guess that it's latin1 */
        converted = g_convert (text, -1, "UTF-8", "ISO-8859-1", NULL, NULL, NULL);
        g_free (text);
 

diff --git a/gcr/gcr-colons.h b/gcr/gcr-colons.h
index b8a055e..565df0a 100644 (file)
--- a/gcr/gcr-colons.h
+++ b/gcr/gcr-colons.h
@@ -30,19 +30,46 @@
 
 #include <glib.h>
 
+/*
+ * Gnupg's official format for listing keys is in the '--with-colons' format.
+ * This is documented in doc/DETAILS in the gnupg distribution. Looks like:
+ *
+ * pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
+ * fpr:::::::::ECAF7590EB3443B5C7CF3ACB6C7EE1B8621CC013:
+ * uid:f::::::::Werner Koch <wk@g10code.com>:
+ * uid:f::::::::Werner Koch <wk@gnupg.org>:
+ * sub:f:1536:16:06AD222CADF6A6E1:919537416:1036177416:::::e:
+ * fpr:::::::::CF8BCC4B18DE08FCD8A1615906AD222CADF6A6E1:
+ * sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc:
+ * fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4:
+ *
+ * Each row is colon delimeted, and has a certain 'schema'. The first item
+ * in the row tells us the schema. Then the various columns are numbered,
+ * (schema is zero).
+ */
+
 G_BEGIN_DECLS
 
 #define GCR_COLONS_SCHEMA_UID  _gcr_colons_get_schema_uid_quark ()
 #define GCR_COLONS_SCHEMA_PUB  _gcr_colons_get_schema_pub_quark ()
 
+/* Common columns for all schemas */
 typedef enum {
        GCR_COLONS_SCHEMA = 0
 } GcrColonColumns;
 
+/*
+ * Columns for pub schema, add them as they're used. eg:
+ * pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
+ */
 typedef enum {
        GCR_COLONS_PUB_KEYID = 4
 } GcrColonPubColumns;
 
+/*
+ * Columns for uid schema, add them as they're used. eg:
+ * pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
+ */
 typedef enum {
        GCR_COLONS_UID_NAME = 9
 } GcrColonUidColumns;

diff --git a/gcr/gcr-gnupg-collection.c b/gcr/gcr-gnupg-collection.c
index 812a35f..97f5840 100644 (file)
--- a/gcr/gcr-gnupg-collection.c
+++ b/gcr/gcr-gnupg-collection.c
@@ -256,12 +256,21 @@ on_line_parse_output (const gchar *line, gpointer user_data)
        }
 
        schema = _gcr_colons_get_schema (colons);
+
+       /*
+        * Each time we see a line with 'pub' schema we assume that it's
+        * a new key being listed.
+        */
        if (schema == GCR_COLONS_SCHEMA_PUB) {
                if (load->dataset->len)
                        process_dataset_as_key (load);
                g_assert (!load->dataset->len);
                g_ptr_array_add (load->dataset, colons);
                colons = NULL;
+
+       /*
+        * 'uid' schema lines get added to the key that came before.
+        */
        } else if (schema == GCR_COLONS_SCHEMA_UID) {
                if (load->dataset->len) {
                        g_ptr_array_add (load->dataset, colons);
@@ -435,6 +444,11 @@ _gcr_gnupg_collection_load_async (GcrGnupgCollection *self, GCancellable *cancel
        load->out_data = g_string_sized_new (1024);
        load->difference = g_hash_table_new (g_str_hash, g_str_equal);
        load->collection = g_object_ref (self);
+
+       /*
+        * Track all the keys we currently have, at end remove those that
+        * didn't get listed by the gpg process.
+        */
        g_hash_table_foreach (self->pv->items, on_each_item_add_keyid_to_difference,
                              load->difference);
 

diff --git a/gcr/gcr-util.c b/gcr/gcr-util.c
index 3929d5b..739d0c7 100644 (file)
--- a/gcr/gcr-util.c
+++ b/gcr/gcr-util.c
@@ -27,6 +27,12 @@
 
 #include <string.h>
 
+/*
+ * Calls callback for each line. If last_line, also sends the remainder
+ * data that comes after the last line break. \n and \r\n are line separators.
+ * Neither are sent.
+ */
+
 void
 _gcr_util_parse_lines (GString *string, gboolean last_line,
                        GcrLineCallback callback, gpointer user_data)