use namestore API for zone import instead of using plugin directly

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

diff --git a/src/include/gnunet_time_lib.h b/src/include/gnunet_time_lib.h
index 4504177305dbfba21cf9cb7848907eeba5af6313..224edc03e94920568786aaabd587a778020bfdd0 100644 (file)
--- a/src/include/gnunet_time_lib.h
+++ b/src/include/gnunet_time_lib.h
@@ -1,10 +1,10 @@
 /*
      This file is part of GNUnet.
 /*
      This file is part of GNUnet.

-     (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2001-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
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published

-     by the Free Software Foundation; either version 2, or (at your
+     by the Free Software Foundation; either version 3, or (at your

      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but


@@ -14,15 +14,19 @@
 
      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the
 
      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the

-     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-     Boston, MA 02111-1307, USA.
+     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+     Boston, MA 02110-1301, USA.

 */
 
 /**
 */
 
 /**

- * @file include/gnunet_time_lib.h
- * @brief functions related to time
- *

  * @author Christian Grothoff
  * @author Christian Grothoff

+ *
+ * @file
+ * Functions related to time
+ *
+ * @defgroup time  Time library
+ * Time and time calculations.
+ * @{

  */
 
 #ifndef GNUNET_TIME_LIB_H
  */
 
 #ifndef GNUNET_TIME_LIB_H


@@ -39,18 +43,18 @@ extern "C"
 #include "gnunet_common.h"
 
 /**
 #include "gnunet_common.h"
 
 /**

- * Time for absolute times used by GNUnet, in milliseconds.
+ * Time for absolute times used by GNUnet, in microseconds.

  */
 struct GNUNET_TIME_Absolute
 {
   /**
    * The actual value.
    */
  */
 struct GNUNET_TIME_Absolute
 {
   /**
    * The actual value.
    */

-  uint64_t abs_value;
+  uint64_t abs_value_us;

 };
 
 /**
 };
 
 /**

- * Time for relative time used by GNUnet, in milliseconds.
+ * Time for relative time used by GNUnet, in microseconds.

  * Always positive, so we can only refer to future time.
  */
 struct GNUNET_TIME_Relative
  * Always positive, so we can only refer to future time.
  */
 struct GNUNET_TIME_Relative


@@ -58,32 +62,32 @@ struct GNUNET_TIME_Relative
   /**
    * The actual value.
    */
   /**
    * The actual value.
    */

-  uint64_t rel_value;
+  uint64_t rel_value_us;

 };
 
 GNUNET_NETWORK_STRUCT_BEGIN
 
 /**
 };
 
 GNUNET_NETWORK_STRUCT_BEGIN
 
 /**

- * Time for relative time used by GNUnet, in milliseconds and in network byte order.
+ * Time for relative time used by GNUnet, in microseconds and in network byte order.

  */
 struct GNUNET_TIME_RelativeNBO
 {
   /**
    * The actual value (in network byte order).
    */
  */
 struct GNUNET_TIME_RelativeNBO
 {
   /**
    * The actual value (in network byte order).
    */

-  uint64_t rel_value__ GNUNET_PACKED;
+  uint64_t rel_value_us__ GNUNET_PACKED;

 };
 
 
 /**
 };
 
 
 /**

- * Time for absolute time used by GNUnet, in milliseconds and in network byte order.
+ * Time for absolute time used by GNUnet, in microseconds and in network byte order.

  */
 struct GNUNET_TIME_AbsoluteNBO
 {
   /**
    * The actual value (in network byte order).
    */
  */
 struct GNUNET_TIME_AbsoluteNBO
 {
   /**
    * The actual value (in network byte order).
    */

-  uint64_t abs_value__ GNUNET_PACKED;
+  uint64_t abs_value_us__ GNUNET_PACKED;

 };
 GNUNET_NETWORK_STRUCT_END
 
 };
 GNUNET_NETWORK_STRUCT_END
 


@@ -98,9 +102,14 @@ GNUNET_NETWORK_STRUCT_END
 #define GNUNET_TIME_UNIT_ZERO_ABS GNUNET_TIME_absolute_get_zero_()
 
 /**
 #define GNUNET_TIME_UNIT_ZERO_ABS GNUNET_TIME_absolute_get_zero_()
 
 /**

- * One millisecond, our basic time unit.
+ * One microsecond, our basic time unit.

  */
  */

-#define GNUNET_TIME_UNIT_MILLISECONDS GNUNET_TIME_relative_get_unit_()
+#define GNUNET_TIME_UNIT_MICROSECONDS GNUNET_TIME_relative_get_unit_()
+
+/**
+ * One millisecond.
+ */
+#define GNUNET_TIME_UNIT_MILLISECONDS GNUNET_TIME_relative_get_millisecond_()

 
 /**
  * One second.
 
 /**
  * One second.


@@ -181,12 +190,19 @@ GNUNET_TIME_absolute_get_zero_ (void);
 
 
 /**
 
 
 /**

- * Return relative time of 1ms.
+ * Return relative time of 1 microsecond.

  */
 struct GNUNET_TIME_Relative
 GNUNET_TIME_relative_get_unit_ (void);
 
 
  */
 struct GNUNET_TIME_Relative
 GNUNET_TIME_relative_get_unit_ (void);
 
 

+/**
+ * Return relative time of 1ms.
+ */
+struct GNUNET_TIME_Relative
+GNUNET_TIME_relative_get_millisecond_ (void);
+
+

 /**
  * Return relative time of 1s.
  */
 /**
  * Return relative time of 1s.
  */


@@ -242,6 +258,30 @@ struct GNUNET_TIME_Absolute
 GNUNET_TIME_relative_to_absolute (struct GNUNET_TIME_Relative rel);
 
 
 GNUNET_TIME_relative_to_absolute (struct GNUNET_TIME_Relative rel);
 
 

+/**
+ * Round a time value so that it is suitable for transmission
+ * via JSON encodings.
+ *
+ * @param at time to round
+ * @return #GNUNET_OK if time was already rounded, #GNUNET_NO if
+ *         it was just now rounded
+ */
+int
+GNUNET_TIME_round_abs (struct GNUNET_TIME_Absolute *at);
+
+
+/**
+ * Round a time value so that it is suitable for transmission
+ * via JSON encodings.
+ *
+ * @param rt time to round
+ * @return #GNUNET_OK if time was already rounded, #GNUNET_NO if
+ *         it was just now rounded
+ */
+int
+GNUNET_TIME_round_rel (struct GNUNET_TIME_Relative *rt);
+
+

 /**
  * Return the minimum of two relative time values.
  *
 /**
  * Return the minimum of two relative time values.
  *


@@ -336,7 +376,7 @@ GNUNET_TIME_absolute_get_difference (struct GNUNET_TIME_Absolute start,
  * difference of the current time and the given start time "hence".
  *
  * @param whence some absolute time, typically in the past
  * difference of the current time and the given start time "hence".
  *
  * @param whence some absolute time, typically in the past

- * @return aborts if hence==FOREVER, 0 if hence > now, otherwise now-hence.
+ * @return 0 if hence > now, otherwise now-hence.

  */
 struct GNUNET_TIME_Relative
 GNUNET_TIME_absolute_get_duration (struct GNUNET_TIME_Absolute whence);
  */
 struct GNUNET_TIME_Relative
 GNUNET_TIME_absolute_get_duration (struct GNUNET_TIME_Absolute whence);


@@ -377,7 +417,19 @@ GNUNET_TIME_absolute_subtract (struct GNUNET_TIME_Absolute start,
  */
 struct GNUNET_TIME_Relative
 GNUNET_TIME_relative_multiply (struct GNUNET_TIME_Relative rel,
  */
 struct GNUNET_TIME_Relative
 GNUNET_TIME_relative_multiply (struct GNUNET_TIME_Relative rel,

-                               unsigned int factor);
+                               unsigned long long factor);
+
+
+/**
+ * Saturating multiply relative time by a given factor.
+ *
+ * @param rel some duration
+ * @param factor integer to multiply with
+ * @return FOREVER if rel=FOREVER or on overflow; otherwise rel*factor
+ */
+struct GNUNET_TIME_Relative
+GNUNET_TIME_relative_saturating_multiply (struct GNUNET_TIME_Relative rel,
+                                          unsigned long long factor);

 
 
 /**
 
 
 /**


@@ -389,7 +441,7 @@ GNUNET_TIME_relative_multiply (struct GNUNET_TIME_Relative rel,
  */
 struct GNUNET_TIME_Relative
 GNUNET_TIME_relative_divide (struct GNUNET_TIME_Relative rel,
  */
 struct GNUNET_TIME_Relative
 GNUNET_TIME_relative_divide (struct GNUNET_TIME_Relative rel,

-                             unsigned int factor);
+                             unsigned long long factor);

 
 
 /**
 
 
 /**


@@ -437,7 +489,7 @@ GNUNET_TIME_relative_ntoh (struct GNUNET_TIME_RelativeNBO a);
 
 
 /**
 
 
 /**

- * Convert relative time to network byte order.
+ * Convert absolute time to network byte order.

  *
  * @param a time to convert
  * @return converted time value
  *
  * @param a time to convert
  * @return converted time value


@@ -447,7 +499,7 @@ GNUNET_TIME_absolute_hton (struct GNUNET_TIME_Absolute a);
 
 
 /**
 
 
 /**

- * Convert relative time from network byte order.
+ * Convert absolute time from network byte order.

  *
  * @param a time to convert
  * @return converted time value
  *
  * @param a time to convert
  * @return converted time value


@@ -470,10 +522,37 @@ GNUNET_TIME_set_offset (long long offset);
  *
  * @return the offset we currently skew the locale time by
  */
  *
  * @return the offset we currently skew the locale time by
  */

-long long 
+long long

 GNUNET_TIME_get_offset (void);
 
 
 GNUNET_TIME_get_offset (void);
 
 

+/**
+ * Return the current year (i.e. '2011').
+ */
+unsigned int
+GNUNET_TIME_get_current_year (void);
+
+
+/**
+ * Convert a year to an expiration time of January 1st of that year.
+ *
+ * @param year a year (after 1970, please ;-)).
+ * @return absolute time for January 1st of that year.
+ */
+struct GNUNET_TIME_Absolute
+GNUNET_TIME_year_to_time (unsigned int year);
+
+
+/**
+ * Convert an expiration time to the respective year (rounds)
+ *
+ * @param at absolute time
+ * @return year a year (after 1970), 0 on error
+ */
+unsigned int
+GNUNET_TIME_time_to_year (struct GNUNET_TIME_Absolute at);
+
+

 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif


@@ -483,4 +562,7 @@ GNUNET_TIME_get_offset (void);
 
 /* ifndef GNUNET_TIME_LIB_H */
 #endif
 
 /* ifndef GNUNET_TIME_LIB_H */
 #endif

+
+/** @} */ /* end of group time */
+

 /* end of gnunet_time_lib.h */
 /* end of gnunet_time_lib.h */