[hipl-commit] [trunk] Rev 3974: Doxygen for cookie.c

  • From: Miika Komu <miika@xxxxxx>
  • To: hipl-commit@xxxxxxxxxxxxx
  • Date: Wed, 17 Mar 2010 00:31:38 +0200

Committer: Miika Komu <miika@xxxxxx>
Date: 17/03/2010 at 00:31:38
Revision: 3974
Revision-id: miika@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Branch nick: trunk

Log:
  Doxygen for cookie.c

Modified:
  D  hipd/cookie.c.doxyme
  M  hipd/cookie.c

=== modified file 'hipd/cookie.c'
--- hipd/cookie.c       2010-03-10 10:30:36 +0000
+++ hipd/cookie.c       2010-03-16 22:31:36 +0000
@@ -1,12 +1,12 @@
 /**
  * @file
- * HIP cookie handling. Licence: GNU/GPL
+ * HIP cookie handling
+ *
+ * Distributed under <a href="http://www.gnu.org/licenses/gpl2.txt";>GNU/GPL</a>
  *
  * @author Kristian Slavov <ksl#iki.fi>
  * @author Miika Komu <miika#iki.fi>
  *
- * TODO: Doxygen documentation incomplete. Please fix this.
- *
  */
 
 /* required for s6_addr32 */
@@ -21,7 +21,14 @@
 
 int hip_cookie_difficulty = HIP_DEFAULT_COOKIE_K;
 
-//get the puzzle difficulty and return result to hipconf
+/**
+ * get the puzzle difficulty and return result (for hipconf)
+ *
+ * @param msg A message containing a HIT for which to query for
+ *            the difficulty. The difficulty will be written
+ *            into the message as a HIP_PARAM_INT parameter.
+ * @return zero on success and negative on error
+ */
 int hip_get_puzzle_difficulty_msg(struct hip_common *msg)
 {
     int err            = 0, diff = 0;
@@ -41,29 +48,50 @@
 }
 
 
-/* TODO: This function has no error handling at all! Check if this is right-*/
-//set the puzzle difficulty acc to msg sent by hipconf
+/**
+ * set the puzzle difficulty according to the msg sent by hipconf
+ *
+ * @param msg An input/output message. Should contain the target
+ *            HIT and the required puzzle difficulty.
+ * @return zero on success and negative on error
+ */
 int hip_set_puzzle_difficulty_msg(struct hip_common *msg)
 {
-    int err            = 0, *newVal = NULL;
+    int err = 0, *newVal = NULL;
     hip_hit_t *dst_hit = NULL;
     hip_hit_t all_zero_hit;
     bzero(&all_zero_hit, sizeof(all_zero_hit));
 
-    dst_hit = hip_get_param_contents(msg, HIP_PARAM_HIT);
-    newVal  = hip_get_param_contents(msg, HIP_PARAM_INT);
+    HIP_IFEL(!(dst_hit = hip_get_param_contents(msg, HIP_PARAM_HIT)),
+             -1, "No HIT set\n");
+    HIP_IFEL(!(newVal = hip_get_param_contents(msg, HIP_PARAM_INT)),
+             -1, "No difficulty set\n");
 
-    hip_set_cookie_difficulty(NULL, *newVal);
+    HIP_IFEL(hip_set_cookie_difficulty(NULL, *newVal), -1,
+             "Setting difficulty failed\n");
 
     return err;
 }
 
+/**
+ * query for current puzzle difficulty
+ *
+ * @param not_used not used
+ * @return the puzzle difficulty
+ */
 int hip_get_cookie_difficulty(hip_hit_t *not_used)
 {
     /* Note: we could return a higher value if we detect DoS */
     return hip_cookie_difficulty;
 }
 
+/**
+ * set puzzle difficulty
+ *
+ * @param not_used not used
+ * @param k the new puzzle difficulty
+ * @return the k value on success or negative on error
+ */
 int hip_set_cookie_difficulty(hip_hit_t *not_used, int k)
 {
     if (k > HIP_PUZZLE_MAX_K || k < 1) {
@@ -76,12 +104,24 @@
     return k;
 }
 
+/**
+ * increase cookie difficulty by one
+ *
+ * @param not_used not used
+ * @return the new cookie difficulty
+ */
 int hip_inc_cookie_difficulty(hip_hit_t *not_used)
 {
     int k = hip_get_cookie_difficulty(NULL) + 1;
     return hip_set_cookie_difficulty(NULL, k);
 }
 
+/**
+ * decrease cookie difficulty by one
+ *
+ * @param not_used not used
+ * @return the new cookie difficulty
+ */
 int hip_dec_cookie_difficulty(hip_hit_t *not_used)
 {
     int k = hip_get_cookie_difficulty(NULL) - 1;
@@ -89,7 +129,8 @@
 }
 
 /**
- * hip_calc_cookie_idx - get an index
+ * calculate the index of a cookie
+ *
  * @param ip_i Initiator's IPv6 address
  * @param ip_r Responder's IPv6 address
  * @param hit_i Initiators HIT
@@ -117,11 +158,12 @@
 }
 
 /**
- * hip_fetch_cookie_entry - Get a copy of R1entry structure
+ * get a copy of R1entry structure
+ *
  * @param ip_i Initiator's IPv6
  * @param ip_r Responder's IPv6
  *
- * Comments for the if 0 code are inlined below.
+ * @note Comments for the if 0 code are inlined below.
  *
  * Returns NULL if error.
  */
@@ -203,6 +245,11 @@
     return err;
 }
 
+/**
+ * initialize an R1 entry structure
+ *
+ * @return The allocated R1 entry structure. Caller deallocates.
+ */
 struct hip_r1entry *hip_init_r1(void)
 {
     struct hip_r1entry *err;
@@ -215,8 +262,15 @@
     return err;
 }
 
-/*
- * @sign the signing function to use
+/**
+ * precreate an R1 packet
+ *
+ * @param r1table a pointer to R1 table structure
+ * @param hit the local HIT
+ * @param sign a signing callback function
+ * @param privkey the private key to use for signing
+ * @param pubkey the host id (public key)
+ * @return zero on success and non-zero on error
  */
 int hip_precreate_r1(struct hip_r1entry *r1table, struct in6_addr *hit,
                      int (*sign)(void *key, struct hip_common *m),
@@ -244,6 +298,11 @@
     return 0;
 }
 
+/**
+ * uninitialize R1 table
+ *
+ * @param hip_r1table R1 table
+ */
 void hip_uninit_r1(struct hip_r1entry *hip_r1table)
 {
     int i;
@@ -374,6 +433,13 @@
     return err;
 }
 
+/**
+ * recreate R1 packets corresponding to one HI
+ *
+ * @param entry the host id entry
+ * @param new_hash unused
+ * @return zero on success or negative on error
+ */
 static int hip_recreate_r1s_for_entry_move(struct hip_host_id_entry *entry,
                                            void *new_hash)
 {
@@ -399,6 +465,11 @@
     return err;
 }
 
+/**
+ * precreate all R1 packets
+ *
+ * @return zero on success or negative on error
+ */
 int hip_recreate_all_precreated_r1_packets()
 {
     HIP_HASHTABLE *ht = hip_ht_init(hip_hidb_hash, hip_hidb_match);

Other related posts:

  • » [hipl-commit] [trunk] Rev 3974: Doxygen for cookie.c - Miika Komu