introducing GNUNET_TIME_Timestamp

6 files changed, 312 insertions, 46 deletions

diff --git a/src/include/gnunet_getopt_lib.h b/src/include/gnunet_getopt_lib.h
index 731be4159..259d648dd 100644
--- a/src/include/gnunet_getopt_lib.h
+++ b/src/include/gnunet_getopt_lib.h
@@ -378,6 +378,24 @@ GNUNET_GETOPT_option_absolute_time (char shortName,
 
 
 /**
+ * Allow user to specify a `struct GNUNET_TIME_Timestamp`
+ * (using human-readable "fancy" time).
+ *
+ * @param shortName short name of the option
+ * @param name long name of the option
+ * @param argumentHelp help text for the option argument
+ * @param description long help text for the option
+ * @param[out] val set to the time specified at the command line
+ */
+struct GNUNET_GETOPT_CommandLineOption
+GNUNET_GETOPT_option_timestamp (char shortName,
+                                const char *name,
+                                const char *argumentHelp,
+                                const char *description,
+                                struct GNUNET_TIME_Timestamp *val);
+
+
+/**
  * Increment @a val each time the option flag is given by one.
  *
  * @param shortName short name of the option
diff --git a/src/include/gnunet_json_lib.h b/src/include/gnunet_json_lib.h
index 5ef4592e5..7d101196c 100644
--- a/src/include/gnunet_json_lib.h
+++ b/src/include/gnunet_json_lib.h
@@ -304,25 +304,25 @@ GNUNET_JSON_spec_boolean (const char *name,
 /* ************ GNUnet-specific parser specifications ******************* */
 
 /**
- * Absolute time.
+ * Timestamp.
  *
  * @param name name of the JSON field
  * @param[out] at where to store the absolute time found under @a name
  */
 struct GNUNET_JSON_Specification
-GNUNET_JSON_spec_absolute_time (const char *name,
-                                struct GNUNET_TIME_Absolute *at);
+GNUNET_JSON_spec_timestamp (const char *name,
+                            struct GNUNET_TIME_Timestamp *t);
 
 
 /**
- * Absolute time in network byte order.
+ * Timestamp in network byte order.
  *
  * @param name name of the JSON field
- * @param[out] at where to store the absolute time found under @a name
+ * @param[out] tn where to store the absolute time found under @a name
  */
 struct GNUNET_JSON_Specification
-GNUNET_JSON_spec_absolute_time_nbo (const char *name,
-                                    struct GNUNET_TIME_AbsoluteNBO *at);
+GNUNET_JSON_spec_timestamp_nbo (const char *name,
+                                struct GNUNET_TIME_TimestampNBO *tn);
 
 
 /**
@@ -385,23 +385,23 @@ GNUNET_JSON_from_data (const void *data, size_t size);
 
 
 /**
- * Convert absolute timestamp to a json string.
+ * Convert timestamp to a json string.
  *
  * @param stamp the time stamp
  * @return a json string with the timestamp in @a stamp
  */
 json_t *
-GNUNET_JSON_from_time_abs (struct GNUNET_TIME_Absolute stamp);
+GNUNET_JSON_from_timestamp (struct GNUNET_TIME_Timestamp stamp);
 
 
 /**
- * Convert absolute timestamp to a json string.
+ * Convert timestamp to a json string.
  *
  * @param stamp the time stamp
  * @return a json string with the timestamp in @a stamp
  */
 json_t *
-GNUNET_JSON_from_time_abs_nbo (struct GNUNET_TIME_AbsoluteNBO stamp);
+GNUNET_JSON_from_timestamp_nbo (struct GNUNET_TIME_TimestampNBO stamp);
 
 
 /**
@@ -747,30 +747,30 @@ GNUNET_JSON_pack_data_varsize (const char *name,
 
 /**
  * Generate packer instruction for a JSON field of type
- * absolute time.
+ * timestamp.
  *
  * @param name name of the field to add to the object
- * @param at absolute time to pack, a value of 0 is only
+ * @param at timestamp pack, a value of 0 is only
  *        allowed with #GNUNET_JSON_pack_allow_null()!
  * @return json pack specification
  */
 struct GNUNET_JSON_PackSpec
-GNUNET_JSON_pack_time_abs (const char *name,
-                           struct GNUNET_TIME_Absolute at);
+GNUNET_JSON_pack_timestamp (const char *name,
+                            struct GNUNET_TIME_Timestamp at);
 
 
 /**
  * Generate packer instruction for a JSON field of type
- * absolute time in network byte order.
+ * timestamp in network byte order.
  *
  * @param name name of the field to add to the object
- * @param at absolute time to pack, a value of 0 is only
+ * @param at timestamp to pack, a value of 0 is only
  *        allowed with #GNUNET_JSON_pack_allow_null()!
  * @return json pack specification
  */
 struct GNUNET_JSON_PackSpec
-GNUNET_JSON_pack_time_abs_nbo (const char *name,
-                               struct GNUNET_TIME_AbsoluteNBO at);
+GNUNET_JSON_pack_timestamp_nbo (const char *name,
+                                struct GNUNET_TIME_TimestampNBO at);
 
 
 /**
diff --git a/src/include/gnunet_pq_lib.h b/src/include/gnunet_pq_lib.h
index 05d373f88..f7bf59212 100644
--- a/src/include/gnunet_pq_lib.h
+++ b/src/include/gnunet_pq_lib.h
@@ -96,7 +96,11 @@ struct GNUNET_PQ_QueryParam
  */
 #define GNUNET_PQ_query_param_end \
   {                               \
-    NULL, NULL, NULL, 0, 0        \
+    .conv = NULL,                 \
+    .conv_cls = NULL,             \
+    .data = NULL,                 \
+    .size = 0,                    \
+    .num_params = 0               \
   }
 
 
@@ -200,6 +204,17 @@ GNUNET_PQ_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
 
 
 /**
+ * Generate query parameter for a timestamp.
+ * The database must store a 64-bit integer.
+ *
+ * @param x pointer to the query parameter to pass
+ * @return query parameter to use
+ */
+struct GNUNET_PQ_QueryParam
+GNUNET_PQ_query_param_timestamp (const struct GNUNET_TIME_Timestamp *x);
+
+
+/**
  * Generate query parameter for an absolute time value.
  * The database must store a 64-bit integer.
  *
@@ -212,6 +227,18 @@ GNUNET_PQ_query_param_absolute_time_nbo (
 
 
 /**
+ * Generate query parameter for a timestamp in NBO.
+ * The database must store a 64-bit integer.
+ *
+ * @param x pointer to the query parameter to pass
+ * @return query parameter to use
+ */
+struct GNUNET_PQ_QueryParam
+GNUNET_PQ_query_param_timestamp_nbo (
+  const struct GNUNET_TIME_TimestampNBO *t);
+
+
+/**
  * Generate query parameter for an uint16_t in host byte order.
  *
  * @param x pointer to the query parameter to pass
@@ -472,6 +499,18 @@ GNUNET_PQ_result_spec_absolute_time (const char *name,
 
 
 /**
+ * Timestamp expected.
+ *
+ * @param name name of the field in the table
+ * @param[out] t where to store the result
+ * @return array entry for the result specification to use
+ */
+struct GNUNET_PQ_ResultSpec
+GNUNET_PQ_result_spec_timestamp (const char *name,
+                                 struct GNUNET_TIME_Timestamp *t);
+
+
+/**
  * Relative time expected.
  *
  * @param name name of the field in the table
@@ -496,6 +535,18 @@ GNUNET_PQ_result_spec_absolute_time_nbo (const char *name,
 
 
 /**
+ * Timestamp expected.
+ *
+ * @param name name of the field in the table
+ * @param[out] tn where to store the result
+ * @return array entry for the result specification to use
+ */
+struct GNUNET_PQ_ResultSpec
+GNUNET_PQ_result_spec_timestamp_nbo (const char *name,
+                                     struct GNUNET_TIME_TimestampNBO *tn);
+
+
+/**
  * uint16_t expected.
  *
  * @param name name of the field in the table
diff --git a/src/include/gnunet_sq_lib.h b/src/include/gnunet_sq_lib.h
index 21ce5b393..e89ded07e 100644
--- a/src/include/gnunet_sq_lib.h
+++ b/src/include/gnunet_sq_lib.h
@@ -40,7 +40,7 @@
  *            so immediately suitable for passing to `sqlite3_bind`-functions.
  * @return #GNUNET_SYSERR on error, #GNUNET_OK on success
  */
-typedef int
+typedef enum GNUNET_GenericReturnValue
 (*GNUNET_SQ_QueryConverter)(void *cls,
                             const void *data,
                             size_t data_len,
@@ -156,8 +156,8 @@ GNUNET_SQ_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x);
  * @param x pointer to the query parameter to pass
  */
 struct GNUNET_SQ_QueryParam
-GNUNET_SQ_query_param_absolute_time_nbo (const struct
-                                         GNUNET_TIME_AbsoluteNBO *x);
+GNUNET_SQ_query_param_absolute_time_nbo (
+  const struct GNUNET_TIME_AbsoluteNBO *x);
 
 
 /**
@@ -222,7 +222,7 @@ GNUNET_SQ_reset (sqlite3 *dbh,
  *   #GNUNET_YES if all results could be extracted
  *   #GNUNET_SYSERR if a result was invalid (non-existing field or NULL)
  */
-typedef int
+typedef enum GNUNET_GenericReturnValue
 (*GNUNET_SQ_ResultConverter)(void *cls,
                              sqlite3_stmt *result,
                              unsigned int column,
@@ -436,7 +436,7 @@ GNUNET_SQ_result_spec_uint64 (uint64_t *u64);
  *   #GNUNET_OK if all results could be extracted
  *   #GNUNET_SYSERR if a result was invalid (non-existing field)
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_SQ_extract_result (sqlite3_stmt *result,
                           struct GNUNET_SQ_ResultSpec *rs);
 
diff --git a/src/include/gnunet_strings_lib.h b/src/include/gnunet_strings_lib.h
index 977c2ead7..2e0c720ee 100644
--- a/src/include/gnunet_strings_lib.h
+++ b/src/include/gnunet_strings_lib.h
@@ -76,7 +76,7 @@ GNUNET_STRINGS_fancy_size_to_bytes (const char *fancy_size,
  * @param rtime set to the relative time
  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_fancy_time_to_relative (const char *fancy_time,
                                        struct GNUNET_TIME_Relative *rtime);
 
@@ -91,12 +91,27 @@ GNUNET_STRINGS_fancy_time_to_relative (const char *fancy_time,
  * @param atime set to the absolute time
  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
  */
-int
+enum GNUNET_GenericReturnValue
 GNUNET_STRINGS_fancy_time_to_absolute (const char *fancy_time,
                                        struct GNUNET_TIME_Absolute *atime);
 
 
 /**
+ * @ingroup time
+ * Convert a given fancy human-readable time to our internal
+ * representation.  The human-readable time is expected to be
+ * in local time, whereas the returned value will be in UTC.
+ *
+ * @param fancy_time human readable string (e.g. %Y-%m-%d %H:%M:%S)
+ * @param atime set to the absolute time
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
+ */
+enum GNUNET_GenericReturnValue
+GNUNET_STRINGS_fancy_time_to_timestamp (const char *fancy_time,
+                                        struct GNUNET_TIME_Timestamp *atime);
+
+
+/**
  * Convert a given filesize into a fancy human-readable format.
  *
  * @param size number of bytes
diff --git a/src/include/gnunet_time_lib.h b/src/include/gnunet_time_lib.h
index 26b442066..5e826ace0 100644
--- a/src/include/gnunet_time_lib.h
+++ b/src/include/gnunet_time_lib.h
@@ -54,6 +54,17 @@ struct GNUNET_TIME_Absolute
 };
 
 /**
+ * Rounded time for timestamps used by GNUnet, in seconds.
+ */
+struct GNUNET_TIME_Timestamp
+{
+  /**
+   * The actual value. Must be round number in seconds.
+   */
+  struct GNUNET_TIME_Absolute abs_time;
+};
+
+/**
  * Time for relative time used by GNUnet, in microseconds.
  * Always positive, so we can only refer to future time.
  */
@@ -89,17 +100,34 @@ struct GNUNET_TIME_AbsoluteNBO
    */
   uint64_t abs_value_us__ GNUNET_PACKED;
 };
+
+/**
+ * Time for timestamps used by GNUnet, in seconds and in network byte order.
+ */
+struct GNUNET_TIME_TimestampNBO
+{
+  /**
+   * The actual value. Must be round number in seconds.
+   */
+  struct GNUNET_TIME_AbsoluteNBO abs_time_nbo;
+};
+
 GNUNET_NETWORK_STRUCT_END
 
 /**
  * Relative time zero.
  */
-#define GNUNET_TIME_UNIT_ZERO     GNUNET_TIME_relative_get_zero_ ()
+#define GNUNET_TIME_UNIT_ZERO ((struct GNUNET_TIME_Relative){0})
 
 /**
  * Absolute time zero.
  */
-#define GNUNET_TIME_UNIT_ZERO_ABS GNUNET_TIME_absolute_get_zero_ ()
+#define GNUNET_TIME_UNIT_ZERO_ABS ((struct GNUNET_TIME_Absolute){0})
+
+/**
+ * Timestamp of zero.
+ */
+#define GNUNET_TIME_UNIT_ZERO_TS ((struct GNUNET_TIME_Timestamp){{0}})
 
 /**
  * One microsecond, our basic time unit.
@@ -154,13 +182,22 @@ GNUNET_NETWORK_STRUCT_END
  * Constant used to specify "forever".  This constant
  * will be treated specially in all time operations.
  */
-#define GNUNET_TIME_UNIT_FOREVER_REL GNUNET_TIME_relative_get_forever_ ()
+#define GNUNET_TIME_UNIT_FOREVER_REL \
+  ((struct GNUNET_TIME_Relative){UINT64_MAX})
 
 /**
  * Constant used to specify "forever".  This constant
  * will be treated specially in all time operations.
  */
-#define GNUNET_TIME_UNIT_FOREVER_ABS GNUNET_TIME_absolute_get_forever_ ()
+#define GNUNET_TIME_UNIT_FOREVER_ABS \
+  ((struct GNUNET_TIME_Absolute){UINT64_MAX})
+
+/**
+ * Constant used to specify "forever".  This constant
+ * will be treated specially in all time operations.
+ */
+#define GNUNET_TIME_UNIT_FOREVER_TS \
+  ((struct GNUNET_TIME_Timestamp){{UINT64_MAX}})
 
 
 /**
@@ -183,6 +220,47 @@ GNUNET_NETWORK_STRUCT_END
 
 
 /**
+ * Convert @a ts to human-readable timestamp.
+ * Note that the returned value will be overwritten if this function
+ * is called again.
+ *
+ * @param ts the timestamp to convert
+ * @return statically allocated string, will change on the next call
+ */
+const char *
+GNUNET_TIME_timestamp2s (struct GNUNET_TIME_Timestamp ts);
+
+
+/**
+ * @ingroup time
+ * Like `asctime`, except for GNUnet time.  Converts a GNUnet internal
+ * absolute time (which is in UTC) to a string in local time.
+ * Note that the returned value will be overwritten if this function
+ * is called again.
+ *
+ * @param t the absolute time to convert
+ * @return timestamp in human-readable form in local time
+ */
+const char *
+GNUNET_TIME_absolute2s (struct GNUNET_TIME_Absolute ts);
+
+
+/**
+ * @ingroup time
+ * Give relative time in human-readable fancy format.
+ * This is one of the very few calls in the entire API that is
+ * NOT reentrant!
+ *
+ * @param delta time in milli seconds
+ * @param do_round are we allowed to round a bit?
+ * @return string in human-readable form
+ */
+const char *
+GNUNET_TIME_relative2s (struct GNUNET_TIME_Relative delta,
+                        bool do_round);
+
+
+/**
  * Randomized exponential back-off, starting at 1 ms
  * and going up by a factor of 2+r, where 0 <= r <= 0.5, up
  * to a maximum of the given threshold.
@@ -192,8 +270,8 @@ GNUNET_NETWORK_STRUCT_END
  * @return the next backoff time
  */
 struct GNUNET_TIME_Relative
-GNUNET_TIME_randomized_backoff (struct GNUNET_TIME_Relative rt, struct
-                                GNUNET_TIME_Relative threshold);
+GNUNET_TIME_randomized_backoff (struct GNUNET_TIME_Relative rt,
+                                struct GNUNET_TIME_Relative threshold);
 
 
 /**
@@ -290,27 +368,69 @@ GNUNET_TIME_relative_to_absolute (struct GNUNET_TIME_Relative rel);
 
 
 /**
- * Round a time value so that it is suitable for transmission
- * via JSON encodings.
+ * Convert relative time to a timestamp in the
+ * future.
+ *
+ * @param rel relative time to convert
+ * @return timestamp that is "rel" in the future, or FOREVER if rel==FOREVER (or if we would overflow)
+ */
+struct GNUNET_TIME_Timestamp
+GNUNET_TIME_relative_to_timestamp (struct GNUNET_TIME_Relative rel);
+
+
+/**
+ * Round an absolute time to a timestamp.
  *
  * @param at time to round
- * @return #GNUNET_OK if time was already rounded, #GNUNET_NO if
- *         it was just now rounded
+ * @return the result
  */
-int
-GNUNET_TIME_round_abs (struct GNUNET_TIME_Absolute *at);
+struct GNUNET_TIME_Timestamp
+GNUNET_TIME_absolute_to_timestamp (struct GNUNET_TIME_Absolute at);
 
 
 /**
- * Round a time value so that it is suitable for transmission
- * via JSON encodings.
+ * Get timestamp representing the current time.
  *
- * @param rt time to round
- * @return #GNUNET_OK if time was already rounded, #GNUNET_NO if
- *         it was just now rounded
+ * @return current time, rounded down to seconds
  */
-int
-GNUNET_TIME_round_rel (struct GNUNET_TIME_Relative *rt);
+struct GNUNET_TIME_Timestamp
+GNUNET_TIME_timestamp_get (void);
+
+
+/**
+ * Compare two absolute times.
+ *
+ * @param t1 first time
+ * @param op compare operator
+ * @param t2 second time
+ * @return true if @a t1 @a op @a t2
+ */
+#define GNUNET_TIME_absolute_cmp(t1,op,t2) \
+  (((void) (1 op 2), (t1).abs_value_us op (t2).abs_value_us))
+
+
+/**
+ * Compare two timestamps
+ *
+ * @param t1 first timestamp
+ * @param op compare operator
+ * @param t2 second timestamp
+ * @return true if @a t1 @a op @a t2
+ */
+#define GNUNET_TIME_timestamp_cmp(t1,op,t2) \
+  GNUNET_TIME_absolute_cmp ((t1).abs_time,op,(t2).abs_time)
+
+
+/**
+ * Compare two relative times.
+ *
+ * @param t1 first time
+ * @param op compare operator
+ * @param t2 second time
+ * @return true if @a t1 @a op @a t2
+ */
+#define GNUNET_TIME_relative_cmp(t1,op,t2) \
+  ((void) (1 op 2), (t1).rel_value_us op (t2).rel_value_us)
 
 
 /**
@@ -362,6 +482,30 @@ GNUNET_TIME_absolute_max (struct GNUNET_TIME_Absolute t1,
 
 
 /**
+ * Return the maximum of two timestamps.
+ *
+ * @param t1 first timestamp
+ * @param t2 other timestamp
+ * @return timestamp that is smaller
+ */
+struct GNUNET_TIME_Timestamp
+GNUNET_TIME_timestamp_max (struct GNUNET_TIME_Timestamp t1,
+                           struct GNUNET_TIME_Timestamp t2);
+
+
+/**
+ * Return the minimum of two timestamps.
+ *
+ * @param t1 first timestamp
+ * @param t2 other timestamp
+ * @return timestamp that is smaller
+ */
+struct GNUNET_TIME_Timestamp
+GNUNET_TIME_timestamp_min (struct GNUNET_TIME_Timestamp t1,
+                           struct GNUNET_TIME_Timestamp t2);
+
+
+/**
  * Given a timestamp in the future, how much time
  * remains until then?
  *
@@ -530,6 +674,16 @@ GNUNET_TIME_absolute_hton (struct GNUNET_TIME_Absolute a);
 
 
 /**
+ * Convert timestamp to network byte order.
+ *
+ * @param t time to convert
+ * @return converted time value
+ */
+struct GNUNET_TIME_TimestampNBO
+GNUNET_TIME_timestamp_hton (struct GNUNET_TIME_Timestamp t);
+
+
+/**
  * Convert milliseconds after the UNIX epoch to absolute time.
  *
  * @param ms_after_epoch millisecond timestamp to convert
@@ -558,6 +712,15 @@ GNUNET_TIME_absolute_is_past (struct GNUNET_TIME_Absolute abs);
 
 
 /**
+ * Test if @a abs is truly zero.
+ *
+ * @return true if it is.
+ */
+bool
+GNUNET_TIME_absolute_is_zero (struct GNUNET_TIME_Absolute abs);
+
+
+/**
  * Test if @a abs is truly in the future (excluding now).
  *
  * @return true if it is.
@@ -595,6 +758,15 @@ GNUNET_TIME_absolute_from_s (uint64_t s_after_epoch);
 
 
 /**
+ * Convert seconds after the UNIX epoch to timestamp.
+ *
+ * @param s_after_epoch seconds after epoch to convert
+ * @return converted time value
+ */struct GNUNET_TIME_Timestamp
+GNUNET_TIME_timestamp_from_s (uint64_t s_after_epoch);
+
+
+/**
  * Convert absolute time from network byte order.
  *
  * @param a time to convert
@@ -605,6 +777,16 @@ GNUNET_TIME_absolute_ntoh (struct GNUNET_TIME_AbsoluteNBO a);
 
 
 /**
+ * Convert timestamp from network byte order.
+ *
+ * @param tn time to convert
+ * @return converted time value
+ */
+struct GNUNET_TIME_Timestamp
+GNUNET_TIME_timestamp_ntoh (struct GNUNET_TIME_TimestampNBO tn);
+
+
+/**
  * Set the timestamp offset for this instance.
  *
  * @param offset the offset to skew the locale time by