GNOME.org
 

[epiphany/wip/google-safe-browsing: 48/57] safe-browsing: Add documentation comments to public functions

commit 0bd232d7b68459bf5b03045cfb2701e9ac9a30c9
Author: Gabriel Ivascu <gabrielivascu gnome org>
Date:   Tue Sep 26 17:50:28 2017 +0300

    safe-browsing: Add documentation comments to public functions

 lib/safe-browsing/ephy-gsb-service.c |   10 +++
 lib/safe-browsing/ephy-gsb-service.h |   15 +++-
 lib/safe-browsing/ephy-gsb-storage.c |  145 ++++++++++++++++++++++++++++++++++
 lib/safe-browsing/ephy-gsb-utils.c   |   85 +++++++++++++++++++-
 4 files changed, 248 insertions(+), 7 deletions(-)
---
diff --git a/lib/safe-browsing/ephy-gsb-service.c b/lib/safe-browsing/ephy-gsb-service.c
index 953a8b3..ca86461 100644
--- a/lib/safe-browsing/ephy-gsb-service.c
+++ b/lib/safe-browsing/ephy-gsb-service.c
@@ -797,6 +797,16 @@ out:
   g_hash_table_unref (matching_hashes_set);
 }
 
+/**
+ * ephy_gsb_service_verify_url:
+ * @self: an #EphyGSBService
+ * @url: the URL to verify
+ * @callback: an #EphyGSBServiceVerifyURLCallback to be called when the
+              verification has completed
+ * @user_data: user data for the callback
+ *
+ * Verify whether @url is safe to browse according to Google Safe Browsing.
+ **/
 void
 ephy_gsb_service_verify_url (EphyGSBService                  *self,
                              const char                      *url,
diff --git a/lib/safe-browsing/ephy-gsb-service.h b/lib/safe-browsing/ephy-gsb-service.h
index eb7175e..d35b840 100644
--- a/lib/safe-browsing/ephy-gsb-service.h
+++ b/lib/safe-browsing/ephy-gsb-service.h
@@ -28,9 +28,18 @@ G_BEGIN_DECLS
 
 G_DECLARE_FINAL_TYPE (EphyGSBService, ephy_gsb_service, EPHY, GSB_SERVICE, GObject)
 
-/* @threats is a set of EphyGSBThreatList where the URL is considered unsafe.
- * The caller takes ownership of the GHashTable and needs to free it.
- */
+/**
+ * EphyGSBServiceVerifyURLCallback:
+ * @threats: the browsing lists where the URL is considered unsafe
+ * @user_data: user data for callback
+ *
+ * The callback to be called when ephy_gsb_service_verify_url() completes the
+ * verification of the URL. @threats is a hash table used a set (see
+ * g_hash_table_add()) of #EphyGSBThreatList that contains the threat lists
+ * where the URL is active. The hash table will never be %NULL (if the URL is
+ * safe, then the hash table will be empty). Use g_hash_table_unref() when done
+ * using it.
+ **/
 typedef void (*EphyGSBServiceVerifyURLCallback) (GHashTable *threats,
                                                  gpointer    user_data);
 
diff --git a/lib/safe-browsing/ephy-gsb-storage.c b/lib/safe-browsing/ephy-gsb-storage.c
index 7491472..e6c5ed5 100644
--- a/lib/safe-browsing/ephy-gsb-storage.c
+++ b/lib/safe-browsing/ephy-gsb-storage.c
@@ -540,6 +540,16 @@ ephy_gsb_storage_new (const char *db_path)
   return g_object_new (EPHY_TYPE_GSB_STORAGE, "db-path", db_path, NULL);
 }
 
+/**
+ * ephy_gsb_storage_is_operable:
+ * @self: an #EphyGSBStorage
+ *
+ * Verify whether the local database is operable, i.e. no error occurred during
+ * the opening and/or initialization of the database. No operations on @self are
+ * allowed if the local database is inoperable.
+ *
+ * Return value: %TRUE if the local database is operable
+ **/
 gboolean
 ephy_gsb_storage_is_operable (EphyGSBStorage *self)
 {
@@ -548,6 +558,16 @@ ephy_gsb_storage_is_operable (EphyGSBStorage *self)
   return self->is_operable;
 }
 
+/**
+ * ephy_gsb_storage_get_metadata:
+ * @self: an #EphyGSBStorage
+ * @key: the key whose value to retrieve
+ * @default_value: the value to return in case of error or if @key is missing
+ *
+ * Retrieve the value of a key from the metadata table of the local database.
+ *
+ * Return value: The metadata value associated with @key
+ **/
 gint64
 ephy_gsb_storage_get_metadata (EphyGSBStorage *self,
                                const char     *key,
@@ -592,6 +612,14 @@ ephy_gsb_storage_get_metadata (EphyGSBStorage *self,
   return value;
 }
 
+/**
+ * ephy_gsb_storage_set_metadata:
+ * @self: an #EphyGSBStorage
+ * @key: the key whose value to update
+ * @value: the updated value
+ *
+ * Update the value of a key in the metadata table of the local database.
+ **/
 void
 ephy_gsb_storage_set_metadata (EphyGSBStorage *self,
                                const char     *key,
@@ -638,6 +666,19 @@ ephy_gsb_storage_set_metadata (EphyGSBStorage *self,
   }
 }
 
+/**
+ * ephy_gsb_storage_get_threat_lists:
+ * @self: an #EphyGSBStorage
+ *
+ * Retrieve the list of supported threat lists from the threats table of the
+ * local database.
+ *
+ * Return value: (element-type #EphyGSBThreatList) (transfer full): a #GList
+ *               containing the threat lists. The caller takes ownership
+ *               of the list and its content. Use g_list_free_full() with
+ *               ephy_gsb_threat_list_free() as free_func when done using
+ *               the list.
+ **/
 GList *
 ephy_gsb_storage_get_threat_lists (EphyGSBStorage *self)
 {
@@ -677,6 +718,18 @@ ephy_gsb_storage_get_threat_lists (EphyGSBStorage *self)
   return g_list_reverse (threat_lists);
 }
 
+/**
+ * ephy_gsb_storage_compute_checksum:
+ * @self: an #EphyGSBSTorage
+ * @list: an #EphyGSBThreatList
+ *
+ * Compute the SHA256 checksum of the lexicographically sorted list of all the
+ * hash prefixes belonging to @list in the local database.
+ *
+ * https://developers.google.com/safe-browsing/v4/local-databases#validation-checks
+ *
+ * Return value: (transfer full): the base64 encoded checksum or %NULL if error
+ **/
 char *
 ephy_gsb_storage_compute_checksum (EphyGSBStorage    *self,
                                    EphyGSBThreatList *list)
@@ -733,6 +786,16 @@ out:
   return retval;
 }
 
+/**
+ * ephy_gsb_storage_update_client_state:
+ * @self: an #EphyGSBStorage
+ * @list: an #EphyGSBThreatList
+ * @clear: %TRUE if the client state should be set to %NULL
+ *
+ * Update the client state column of @list in the threats table of the local
+ * database. The new state is set according to the client_state field of @list.
+ * Set @clear to %TRUE if you wish to reset the state.
+ **/
 void
 ephy_gsb_storage_update_client_state (EphyGSBStorage    *self,
                                       EphyGSBThreatList *list,
@@ -775,6 +838,13 @@ ephy_gsb_storage_update_client_state (EphyGSBStorage    *self,
   g_object_unref (statement);
 }
 
+/**
+ * ephy_gsb_storage_clear_hash_prefixes:
+ * @self: an #EphyGSBStorage
+ * @list: an #EphyGSBThreatList
+ *
+ * Delete all hash prefixes belonging to @list from the local database.
+ **/
 void
 ephy_gsb_storage_clear_hash_prefixes (EphyGSBStorage    *self,
                                       EphyGSBThreatList *list)
@@ -1003,6 +1073,15 @@ ephy_gsb_storage_delete_hash_prefixes_internal (EphyGSBStorage    *self,
     g_object_unref (statement);
 }
 
+/**
+ * ephy_gsb_storage_delete_hash_prefixes:
+ * @self: an #EphyGSBStorage
+ * @list: an #EphyGSBThreatList
+ * @tes: a ThreatEntrySet object as a #JsonObject
+ *
+ * Delete hash prefixes belonging to @list from the local database. Use this
+ * when handling the response of a threatListUpdates:fetch request.
+ **/
 void
 ephy_gsb_storage_delete_hash_prefixes (EphyGSBStorage    *self,
                                        EphyGSBThreatList *list,
@@ -1165,6 +1244,15 @@ ephy_gsb_storage_insert_hash_prefixes_internal (EphyGSBStorage    *self,
     g_object_unref (statement);
 }
 
+/**
+ * ephy_gsb_storage_insert_hash_prefixes:
+ * @self: an #EphyGSBStorage
+ * @list: an #EphyGSBThreatList
+ * @tes: a ThreatEntrySet object as a #JsonObject
+ *
+ * Insert hash prefixes belonging to @list in the local database. Use this
+ * when handling the response of a threatListUpdates:fetch request.
+ **/
 void
 ephy_gsb_storage_insert_hash_prefixes (EphyGSBStorage    *self,
                                        EphyGSBThreatList *list,
@@ -1210,6 +1298,21 @@ ephy_gsb_storage_insert_hash_prefixes (EphyGSBStorage    *self,
   g_free (prefixes);
 }
 
+/**
+ * ephy_gsb_storage_lookup_hash_prefixes:
+ * @self: an #EphyGSBStorage
+ * @cues: a #GList of hash cues as #GBytes
+ *
+ * Retrieve the hash prefixes and their negative cache expiration time from the
+ * local database that begin with the hash cues in @cues. The hash cue length is
+ * specified by the GSB_HASH_CUE_LEN macro.
+ *
+ * Return value: (element-type #EphyGSBHashPrefixLookup) (transfer-full):
+ *               a #GList containing the lookup result.  The caller takes
+ *               ownership of the list and its content. Use g_list_free_full()
+ *               with ephy_gsb_hash_prefix_lookup_free() as free_func when done
+ *               using the list.
+ **/
 GList *
 ephy_gsb_storage_lookup_hash_prefixes (EphyGSBStorage *self,
                                        GList          *cues)
@@ -1271,6 +1374,21 @@ ephy_gsb_storage_lookup_hash_prefixes (EphyGSBStorage *self,
   return g_list_reverse (retval);
 }
 
+/**
+ * ephy_gsb_storage_lookup_full_hashes:
+ * @self: an #EphyGSBStorage
+ * @hashes: a #GList of full hashes as #GBytes
+ *
+ * Retrieve the full hashes together with their positive cache expiration time
+ * and threat parameters from the local database that match any of the hashes
+ * in @hashes.
+ *
+ * Return value: (element-type #EphyGSBHashFullLookup) (transfer-full):
+ *               a #GList containing the lookup result.  The caller takes
+ *               ownership of the list and its content. Use g_list_free_full()
+ *               with ephy_gsb_hash_full_lookup_free() as free_func when done
+ *               using the list.
+ **/
 GList *
 ephy_gsb_storage_lookup_full_hashes (EphyGSBStorage *self,
                                      GList          *hashes)
@@ -1340,6 +1458,18 @@ ephy_gsb_storage_lookup_full_hashes (EphyGSBStorage *self,
   return g_list_reverse (retval);
 }
 
+/**
+ * ephy_gsb_storage_insert_full_hash:
+ * @self: an #EphyGSBStorage
+ * @list: an #EphyGSBThreatList
+ * @hash: the full SHA256 hash
+ * @duration: the positive cache duration
+ *
+ * Insert a full hash belonging to @list in the local database. Use this
+ * when handling the response from a fullHashes:find request. If @hash
+ * already exists in the database and belongs to @list, then only the
+ * duration is updated. Otherwise, a new record is created.
+ **/
 void
 ephy_gsb_storage_insert_full_hash (EphyGSBStorage    *self,
                                    EphyGSBThreatList *list,
@@ -1415,6 +1545,13 @@ out:
     g_error_free (error);
 }
 
+/**
+ * ephy_gsb_storage_delete_old_full_hashes:
+ * @self: an #EphyGSBStorage
+ *
+ * Delete long expired full hashes from the local database. The expiration
+ * threshold is specified by the EXPIRATION_THRESHOLD macro.
+ **/
 void
 ephy_gsb_storage_delete_old_full_hashes (EphyGSBStorage *self)
 {
@@ -1453,6 +1590,14 @@ ephy_gsb_storage_delete_old_full_hashes (EphyGSBStorage *self)
   g_object_unref (statement);
 }
 
+/**
+ * ephy_gsb_storage_update_hash_prefix_expiration:
+ * @self: an #EphyGSBStorage
+ * @prefix: the hash prefix
+ * @duration: the negative cache duration
+ *
+ * Update the negative cache expiration time of a hash prefix in the local database.
+ **/
 void
 ephy_gsb_storage_update_hash_prefix_expiration (EphyGSBStorage *self,
                                                 GBytes         *prefix,
diff --git a/lib/safe-browsing/ephy-gsb-utils.c b/lib/safe-browsing/ephy-gsb-utils.c
index 5db5b30..a4e4ed1 100644
--- a/lib/safe-browsing/ephy-gsb-utils.c
+++ b/lib/safe-browsing/ephy-gsb-utils.c
@@ -293,6 +293,16 @@ ephy_gsb_utils_make_contraints (void)
   return constraints;
 }
 
+/**
+ * ephy_gsb_utils_make_list_updates_request:
+ * @threat_lists: a #GList of #EphyGSBThreatList
+ *
+ * Create the request body for a threatListUpdates:fetch request.
+ *
+ * https://developers.google.com/safe-browsing/v4/reference/rest/v4/threatListUpdates/fetch#request-body
+ *
+ * Return value: (transfer full): the string representation of the request body
+ **/
 char *
 ephy_gsb_utils_make_list_updates_request (GList *threat_lists)
 {
@@ -330,6 +340,17 @@ ephy_gsb_utils_make_list_updates_request (GList *threat_lists)
   return retval;
 }
 
+/**
+ * ephy_gsb_utils_make_full_hashes_request:
+ * @threat_lists: a #GList of #EphyGSBThreatList
+ * @hash_prefixes: a #GList of #GBytes
+ *
+ * Create the request body for a fullHashes:find request.
+ *
+ * https://developers.google.com/safe-browsing/v4/reference/rest/v4/fullHashes/find#request-body
+ *
+ * Return value: (transfer full): the string representation of the request body
+ **/
 char *
 ephy_gsb_utils_make_full_hashes_request (GList *threat_lists,
                                          GList *hash_prefixes)
@@ -426,9 +447,20 @@ ephy_gsb_utils_make_full_hashes_request (GList *threat_lists,
   return body;
 }
 
-/*
+/**
+ * ephy_gsb_utils_rice_delta_decode:
+ * @rde: a RiceDeltaEncoding object as a #JsonObject
+ * @num_items: out parameter for the length of the returned array. This will be
+ *             equal to 1 + RiceDeltaEncoding.numEntries
+ *
+ * Decompress the Rice-encoded data of a ThreatEntrySet received from a
+ * threatListUpdates:fetch response.
+ *
  * https://developers.google.com/safe-browsing/v4/compression#rice-compression
- */
+ * https://developers.google.com/safe-browsing/v4/reference/rest/v4/threatListUpdates/fetch#ricedeltaencoding
+ *
+ * Return value: (transfer full): the decompressed values as an array of guint32s
+ **/
 guint32 *
 ephy_gsb_utils_rice_delta_decode (JsonObject *rde,
                                   gsize      *num_items)
@@ -581,9 +613,20 @@ ephy_gsb_utils_canonicalize_host (const char *host)
   return retval;
 }
 
-/*
+/**
+ * ephy_gsb_utils_canonicalize:
+ * @url: the URL to canonicalize
+ * @host_out: out parameter for the host value of the canonicalized URL or %NULL
+ * @path_out: out parameter for the path value of the canonicalized URL or %NULL
+ * @query_out: out parameter for the query value of the canonicalized URL or %NULL
+ *
+ * Canonicalize @url according to Google Safe Browsing API v4 specification.
+ *
  * https://developers.google.com/safe-browsing/v4/urls-hashing#canonicalization
- */
+ *
+ * Return value: (transfer full): the canonical form of @url or %NULL if @url
+ *               is not a valid URL
+ **/
 char *
 ephy_gsb_utils_canonicalize (const char  *url,
                              char       **host_out,
@@ -747,6 +790,19 @@ ephy_gsb_utils_compute_path_prefixes (const char *path,
   return g_list_reverse (retval);
 }
 
+/**
+ * ephy_gsb_utils_compute_hashes:
+ * @url: the URL whose hashes to be computed
+ *
+ * Compute the SHA256 hashes of @url.
+ *
+ * https://developers.google.com/safe-browsing/v4/urls-hashing#hash-computations
+ *
+ * Return value: (element-type #GBytes) (transfer full): a #GList containing the
+ *               full hashes of @url. The caller takes ownership of the list and
+ *               its content. Use g_list_free_full() with g_bytes_unref() as
+ *               free_func when done using the list.
+ **/
 GList *
 ephy_gsb_utils_compute_hashes (const char *url)
 {
@@ -799,6 +855,18 @@ ephy_gsb_utils_compute_hashes (const char *url)
   return g_list_reverse (retval);
 }
 
+/**
+ * ephy_gsb_utils_get_hash_cues:
+ * @hashes: a #GList of #GBytes
+ *
+ * Get the hash cues from a list of full hashes. The hash cue length is
+ * specified by the GSB_HASH_CUE_LEN macro.
+ *
+ * Return value: (element-type #GBytes) (transfer full): a #GList containing
+ *               the cues of each hash in @hashes. The caller takes ownership
+ *               of the list and its content. Use g_list_free_full() with
+ *               g_bytes_unref() as free_func when done using the list.
+ **/
 GList *
 ephy_gsb_utils_get_hash_cues (GList *hashes)
 {
@@ -814,6 +882,15 @@ ephy_gsb_utils_get_hash_cues (GList *hashes)
   return g_list_reverse (retval);
 }
 
+/**
+ * ephy_gsb_utils_hash_has_prefix:
+ * @hash: the full hash to verify
+ * @prefix: the hash prefix to verify
+ *
+ * Verify whether @hash begins with the prefix @prefix.
+ *
+ * Return value: %TRUE if @hash begins with @prefix
+ **/
 gboolean
 ephy_gsb_utils_hash_has_prefix (GBytes *hash,
                                 GBytes *prefix)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]