X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_common.h;h=fdcae66fa19e9cc71dd6bc4e1bf89d03b108fa26;hb=17047b7bcbe3f1756028058a9887416c6afab5d8;hp=c082398f875cde87458ab6887ab882251f03f4b0;hpb=a5e12b53160fbf359dd469408c600f0eb976590b;p=oweals%2Fgnunet.git

diff --git a/src/include/gnunet_common.h b/src/include/gnunet_common.h
index c082398f8..fdcae66fa 100644
--- a/src/include/gnunet_common.h
+++ b/src/include/gnunet_common.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     Copyright (C) 2006-2013 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2006-2013 GNUnet e.V.
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
@@ -28,6 +28,8 @@
  * @author Nils Durner
  *
  * @defgroup logging Logging
+ * @see [Documentation](https://gnunet.org/logging)
+ *
  * @defgroup memory Memory management
  */
 #ifndef GNUNET_COMMON_H
@@ -64,7 +66,7 @@ extern "C"
 /**
  * Version of the API (for entire gnunetutil.so library).
  */
-#define GNUNET_UTIL_VERSION 0x000A0100
+#define GNUNET_UTIL_VERSION 0x000A0102
 
 
 /**
@@ -330,10 +332,14 @@ enum GNUNET_ErrorType
   GNUNET_ERROR_TYPE_NONE = 0,
   GNUNET_ERROR_TYPE_ERROR = 1,
   GNUNET_ERROR_TYPE_WARNING = 2,
-  GNUNET_ERROR_TYPE_INFO = 4,
-  GNUNET_ERROR_TYPE_DEBUG = 8,
-  GNUNET_ERROR_TYPE_INVALID = 16,
-  GNUNET_ERROR_TYPE_BULK = 32
+  /* UX: We need a message type that is output by
+   * default without looking like there is a problem.
+   */
+  GNUNET_ERROR_TYPE_MESSAGE = 4,
+  GNUNET_ERROR_TYPE_INFO = 8,
+  GNUNET_ERROR_TYPE_DEBUG = 16,
+  GNUNET_ERROR_TYPE_INVALID = 32,
+  GNUNET_ERROR_TYPE_BULK = 64
 };
 
 
@@ -384,7 +390,8 @@ GNUNET_get_log_call_status (int caller_level,
  * @param ... arguments for format string
  */
 void
-GNUNET_log_nocheck (enum GNUNET_ErrorType kind, const char *message, ...);
+GNUNET_log_nocheck (enum GNUNET_ErrorType kind, const char *message, ...)
+  __attribute__ ((format (printf, 2, 3)));
 
 /* from glib */
 #if defined(__GNUC__) && (__GNUC__ > 2) && defined(__OPTIMIZE__)
@@ -524,7 +531,10 @@ GNUNET_log_setup (const char *comp,
 
 /**
  * @ingroup logging
- * Add a custom logger.
+ * Add a custom logger.  Note that installing any custom logger
+ * will disable the standard logger.  When multiple custom loggers
+ * are installed, all will be called.  The standard logger will
+ * only be used if no custom loggers are present.
  *
  * @param logger log function
  * @param logger_cls closure for @a logger
@@ -546,6 +556,19 @@ GNUNET_logger_remove (GNUNET_Logger logger,
                       void *logger_cls);
 
 
+/**
+ * @ingroup logging
+ * Convert a short hash value to a string (for printing debug messages).
+ * This is one of the very few calls in the entire API that is
+ * NOT reentrant!
+ *
+ * @param shc the hash code
+ * @return string
+ */
+const char *
+GNUNET_sh2s (const struct GNUNET_ShortHashCode *shc);
+
+
 /**
  * @ingroup logging
  * Convert a hash value to a string (for printing debug messages).
@@ -587,6 +610,22 @@ const char *
 GNUNET_i2s (const struct GNUNET_PeerIdentity *pid);
 
 
+/**
+ * @ingroup logging
+ * Convert a peer identity to a string (for printing debug messages).
+ * This is one of the very few calls in the entire API that is
+ * NOT reentrant!  Identical to #GNUNET_i2s(), except that another
+ * buffer is used so both #GNUNET_i2s() and #GNUNET_i2s2() can be
+ * used within the same log statement.
+ *
+ * @param pid the peer identity
+ * @return string form of the pid; will be overwritten by next
+ *         call to #GNUNET_i2s().
+ */
+const char *
+GNUNET_i2s2 (const struct GNUNET_PeerIdentity *pid);
+
+
 /**
  * @ingroup logging
  * Convert a peer identity to a string (for printing debug messages).
@@ -642,6 +681,16 @@ GNUNET_error_type_to_string (enum GNUNET_ErrorType kind);
 #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)
 
 
+/**
+ * @ingroup logging
+ * Use this for fatal errors that cannot be handled
+ *
+ * @param cond Condition to evaluate
+ * @param comp Component string to use for logging
+ */
+#define GNUNET_assert_from(cond, comp) do { if (! (cond)) { GNUNET_log_from(GNUNET_ERROR_TYPE_ERROR, comp, _("Assertion failed at %s:%d.\n"), __FILE__, __LINE__); GNUNET_abort_(); } } while(0)
+
+
 /**
  * @ingroup logging
  * Use this for internal assertion violations that are
@@ -686,7 +735,7 @@ GNUNET_error_type_to_string (enum GNUNET_ErrorType kind);
  * a failure of the command 'cmd' with the message given
  * by strerror(errno).
  */
-#define GNUNET_log_strerror_file(level, cmd, filename) do { GNUNET_log(level, _("`%s' failed on file `%s' at %s:%d with error: %s\n"), cmd, filename,__FILE__, __LINE__, STRERROR(errno)); } while(0)
+#define GNUNET_log_strerror_file(level, cmd, filename) do { GNUNET_log(level, _("`%s' failed on file `%s' at %s:%d with error: %s\n"), cmd, filename, __FILE__, __LINE__, STRERROR(errno)); } while(0)
 
 
 /**
@@ -765,6 +814,18 @@ GNUNET_ntoh_double (double d);
  */
 #define GNUNET_new(type) (type *) GNUNET_malloc (sizeof (type))
 
+/**
+ * Call memcpy() but check for @a n being 0 first. In the latter
+ * case, it is now safe to pass NULL for @a src or @a dst.
+ * Unlike traditional memcpy(), returns nothing.
+ *
+ * @param dst destination of the copy, may be NULL if @a n is zero
+ * @param src source of the copy, may be NULL if @a n is zero
+ * @param n number of bytes to copy
+ */
+#define GNUNET_memcpy(dst,src,n) do { if (0 != n) { (void) memcpy (dst,src,n); } } while (0)
+
+
 /**
  * @ingroup memory
  * Allocate a size @a n array with structs or unions of the given @a type.
@@ -776,6 +837,29 @@ GNUNET_ntoh_double (double d);
  */
 #define GNUNET_new_array(n, type) (type *) GNUNET_malloc ((n) * sizeof (type))
 
+/**
+ * @ingroup memory
+ * Allocate a size @a n times @a m array
+ * with structs or unions of the given @a type.
+ *
+ * @param n size of the first dimension
+ * @param m size of the second dimension
+ * @param type name of the struct or union, i.e. pass 'struct Foo'.
+ */
+#define GNUNET_new_array_2d(n, m, type) (type **) GNUNET_xnew_array_2d_ (n, m, sizeof (type), __FILE__, __LINE__)
+
+/**
+ * @ingroup memory
+ * Allocate a size @a n times @a m times @a o array
+ * with structs or unions of the given @a type.
+ *
+ * @param n size of the first dimension
+ * @param m size of the second dimension
+ * @param o size of the third dimension
+ * @param type name of the struct or union, i.e. pass 'struct Foo'.
+ */
+#define GNUNET_new_array_3d(n, m, o, type) (type ***) GNUNET_xnew_array_3d_ (n, m, o, sizeof (type), __FILE__, __LINE__)
+
 /**
  * @ingroup memory
  * Wrapper around malloc. Allocates size bytes of memory.
@@ -809,7 +893,8 @@ GNUNET_ntoh_double (double d);
 
 /**
  * @ingroup memory
- * Wrapper around realloc. Rellocates size bytes of memory.
+ * Wrapper around realloc. Reallocates size bytes of memory.
+ * The content of the intersection of the new and old size will be unchanged.
  *
  * @param ptr the pointer to reallocate
  * @param size the number of bytes to reallocate
@@ -820,7 +905,7 @@ GNUNET_ntoh_double (double d);
 /**
  * @ingroup memory
  * Wrapper around free. Frees the memory referred to by ptr.
- * Note that is is generally better to free memory that was
+ * Note that it is generally better to free memory that was
  * allocated with #GNUNET_array_grow using #GNUNET_array_grow(mem, size, 0) instead of #GNUNET_free.
  *
  * @param ptr location where to free the memory. ptr must have
@@ -873,12 +958,12 @@ GNUNET_ntoh_double (double d);
  *
  * static void push(struct foo * elem) {
  *   GNUNET_array_grow(myVector, myVecLen, myVecLen+1);
- *   memcpy(&myVector[myVecLen-1], elem, sizeof(struct foo));
+ *   GNUNET_memcpy(&myVector[myVecLen-1], elem, sizeof(struct foo));
  * }
  *
  * static void pop(struct foo * elem) {
  *   if (myVecLen == 0) die();
- *   memcpy(elem, myVector[myVecLen-1], sizeof(struct foo));
+ *   GNUNET_memcpy(elem, myVector[myVecLen-1], sizeof(struct foo));
  *   GNUNET_array_grow(myVector, myVecLen, myVecLen-1);
  * }
  * </pre>
@@ -945,6 +1030,45 @@ void *
 GNUNET_xmalloc_ (size_t size, const char *filename, int linenumber);
 
 
+/**
+ * Allocate memory for a two dimensional array in one block
+ * and set up pointers. Aborts if no more memory is available.
+ * Don't use GNUNET_xnew_array_2d_ directly. Use the
+ * #GNUNET_new_array_2d macro.
+ * The memory of the elements will be zero'ed out.
+ *
+ * @param n size of the first dimension
+ * @param m size of the second dimension
+ * @param elementSize size of a single element in bytes
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
+ * @return allocated memory, never NULL
+ */
+void **
+GNUNET_xnew_array_2d_ (size_t n, size_t m, size_t elementSize,
+                       const char *filename, int linenumber);
+
+
+/**
+ * Allocate memory for a three dimensional array in one block
+ * and set up pointers. Aborts if no more memory is available.
+ * Don't use GNUNET_xnew_array_3d_ directly. Use the
+ * #GNUNET_new_array_3d macro.
+ * The memory of the elements will be zero'ed out.
+ *
+ * @param n size of the first dimension
+ * @param m size of the second dimension
+ * @param o size of the third dimension
+ * @param elementSize size of a single element in bytes
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
+ * @return allocated memory, never NULL
+ */
+void ***
+GNUNET_xnew_array_3d_ (size_t n, size_t m, size_t o, size_t elementSize,
+                       const char *filename, int linenumber);
+
+
 /**
  * Allocate and initialize memory. Checks the return value, aborts if no more
  * memory is available.  Don't use GNUNET_xmemdup_ directly. Use the
@@ -1139,7 +1263,4 @@ enum GNUNET_SCHEDULER_Priority
 }
 #endif
 
-
-
-
-#endif /*GNUNET_COMMON_H_ */
+#endif /* GNUNET_COMMON_H */