adding number of preferences to allow iterating over preferences

[oweals/gnunet.git] / src / include / gnunet_common.h

diff --git a/src/include/gnunet_common.h b/src/include/gnunet_common.h
index ec077d355fe175ae40427af373952140986289c2..fc5cb80d90466ce91e6959520d7128cf6e503bf7 100644 (file)
--- a/src/include/gnunet_common.h
+++ b/src/include/gnunet_common.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     (C) 2006-2013 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2006-2013 Christian Grothoff (and other contributing authors)
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
@@ -259,7 +259,18 @@ GNUNET_NETWORK_STRUCT_END
  *  #GNUNET_NO to stop iteration with no error,
  *  #GNUNET_SYSERR to abort iteration with error!
  */
-typedef int (*GNUNET_FileNameCallback) (void *cls, const char *filename);
+typedef int
+(*GNUNET_FileNameCallback) (void *cls,
+                            const char *filename);
+
+
+/**
+ * Generic continuation callback.
+ *
+ * @param cls  Closure.
+ */
+typedef void
+(*GNUNET_ContinuationCallback) (void *cls);
 
 
 /* ****************************** logging ***************************** */
@@ -291,9 +302,12 @@ enum GNUNET_ErrorType
  * @param date when was the message logged?
  * @param message what is the message
  */
-typedef void (*GNUNET_Logger) (void *cls, enum GNUNET_ErrorType kind,
-                               const char *component, const char *date,
-                               const char *message);
+typedef void
+(*GNUNET_Logger) (void *cls,
+                  enum GNUNET_ErrorType kind,
+                  const char *component,
+                  const char *date,
+                  const char *message);
 
 
 /**
@@ -303,14 +317,16 @@ typedef void (*GNUNET_Logger) (void *cls, enum GNUNET_ErrorType kind,
  * @return number of log calls to be ignored
  */
 int
-GNUNET_get_log_skip ();
+GNUNET_get_log_skip (void);
+
 
 #if !defined(GNUNET_CULL_LOGGING)
 int
 GNUNET_get_log_call_status (int caller_level,
                             const char *comp,
                             const char *file,
-                            const char *function, int line);
+                            const char *function,
+                            int line);
 #endif
 
 
@@ -427,9 +443,11 @@ GNUNET_log_config_invalid (enum GNUNET_ErrorType kind,
 /**
  * @ingroup logging
  * Abort the process, generate a core dump if possible.
+ * Most code should use `GNUNET_assert (0)` instead to
+ * first log the location of the failure.
  */
 void
-GNUNET_abort (void) GNUNET_NORETURN;
+GNUNET_abort_ (void) GNUNET_NORETURN;
 
 
 /**
@@ -437,10 +455,11 @@ GNUNET_abort (void) GNUNET_NORETURN;
  * Ignore the next @a n calls to the log function.
  *
  * @param n number of log calls to ignore (could be negative)
- * @param check_reset GNUNET_YES to assert that the log skip counter is currently zero
+ * @param check_reset #GNUNET_YES to assert that the log skip counter is currently zero
  */
 void
-GNUNET_log_skip (int n, int check_reset);
+GNUNET_log_skip (int n,
+                 int check_reset);
 
 
 /**
@@ -453,7 +472,9 @@ GNUNET_log_skip (int n, int check_reset);
  * @return #GNUNET_OK on success, #GNUNET_SYSERR if logfile could not be opened
  */
 int
-GNUNET_log_setup (const char *comp, const char *loglevel, const char *logfile);
+GNUNET_log_setup (const char *comp,
+                  const char *loglevel,
+                  const char *logfile);
 
 
 /**
@@ -464,7 +485,8 @@ GNUNET_log_setup (const char *comp, const char *loglevel, const char *logfile);
  * @param logger_cls closure for @a logger
  */
 void
-GNUNET_logger_add (GNUNET_Logger logger, void *logger_cls);
+GNUNET_logger_add (GNUNET_Logger logger,
+                   void *logger_cls);
 
 
 /**
@@ -472,10 +494,11 @@ GNUNET_logger_add (GNUNET_Logger logger, void *logger_cls);
  * Remove a custom logger.
  *
  * @param logger log function
- * @param logger_cls closure for logger
+ * @param logger_cls closure for @a logger
  */
 void
-GNUNET_logger_remove (GNUNET_Logger logger, void *logger_cls);
+GNUNET_logger_remove (GNUNET_Logger logger,
+                      void *logger_cls);
 
 
 /**
@@ -513,7 +536,7 @@ GNUNET_h2s_full (const struct GNUNET_HashCode * hc);
  *
  * @param pid the peer identity
  * @return string form of the pid; will be overwritten by next
- *         call to #GNUNET_i2s.
+ *         call to #GNUNET_i2s().
  */
 const char *
 GNUNET_i2s (const struct GNUNET_PeerIdentity *pid);
@@ -527,7 +550,7 @@ GNUNET_i2s (const struct GNUNET_PeerIdentity *pid);
  *
  * @param pid the peer identity
  * @return string form of the pid; will be overwritten by next
- *         call to #GNUNET_i2s.
+ *         call to #GNUNET_i2s_full().
  */
 const char *
 GNUNET_i2s_full (const struct GNUNET_PeerIdentity *pid);
@@ -540,12 +563,13 @@ GNUNET_i2s_full (const struct GNUNET_PeerIdentity *pid);
  * in the entire API that is NOT reentrant!
  *
  * @param addr the address
- * @param addrlen the length of the address
+ * @param addrlen the length of the @a addr
  * @return nicely formatted string for the address
- *  will be overwritten by next call to GNUNET_a2s.
+ *  will be overwritten by next call to #GNUNET_a2s().
  */
 const char *
-GNUNET_a2s (const struct sockaddr *addr, socklen_t addrlen);
+GNUNET_a2s (const struct sockaddr *addr,
+            socklen_t addrlen);
 
 
 /**
@@ -563,14 +587,14 @@ GNUNET_error_type_to_string (enum GNUNET_ErrorType kind);
  * @ingroup logging
  * Use this for fatal errors that cannot be handled
  */
-#define GNUNET_assert(cond) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), __FILE__, __LINE__); GNUNET_abort(); } } while(0)
+#define GNUNET_assert(cond) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), __FILE__, __LINE__); GNUNET_abort_(); } } while(0)
 
 
 /**
  * @ingroup logging
  * Use this for fatal errors that cannot be handled
  */
-#define GNUNET_assert_at(cond, f, l) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), f, l); GNUNET_abort(); } } while(0)
+#define GNUNET_assert_at(cond, f, l) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), f, l); GNUNET_abort_(); } } while(0)
 
 
 /**