+/*
+
+ silctimer.h
+
+ Author: Pekka Riikonen <priikone@silcnet.org>
+
+ Copyright (C) 2007 Pekka Riikonen
+
+ This program 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; version 2 of the License.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+*/
+
+/****h* silcutil/SILC Timer Interface
+ *
+ * SILC Timer interface provides a simple way to measure time intervals.
+ * The SILC Timer works with microsecond resolution, depending on platform.
+ *
+ ***/
+
+#ifndef SILCTIMER_H
+#define SILCTIMER_H
+
+/****s* silcutil/SilcTimerAPI/SilcTimer
+ *
+ * NAME
+ *
+ * typedef struct SilcTimerObject *SilcTimer, SilcTimerStruct;
+ *
+ * DESCRIPTION
+ *
+ * The timer context. The context is given as argument to all
+ * silc_timer_* functions.
+ *
+ ***/
+typedef struct SilcTimerObject *SilcTimer, SilcTimerStruct;
+
+/****f* silcutil/SilcTimerAPI/silc_timer_start
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_timer_start(SilcTimer timer);
+ *
+ * DESCRIPTION
+ *
+ * Starts the timer. If the timer is already running this will reset
+ * the timer and continue.
+ *
+ * EXAMPLE
+ *
+ * SilcTimerStruct timer;
+ *
+ * silc_timer_start(&timer);
+ * ... time passes ...
+ * silc_timer_stop(&timer);
+ * silc_timer_value(&timer, &elapsed_sec, &elapsed_usec);
+ *
+ ***/
+void silc_timer_start(SilcTimer timer);
+
+/****f* silcutil/SilcTimerAPI/silc_timer_stop
+ *
+ * SYNOPSIS
+ *
+ * void silc_timer_stop(SilcTimer timer);
+ *
+ * DESCRIPTION
+ *
+ * Stop the timer. The elapsed time can be retrieved by calling the
+ * silc_timer_value function.
+ *
+ ***/
+void silc_timer_stop(SilcTimer timer);
+
+/****f* silcutil/SilcTimerAPI/silc_timer_continue
+ *
+ * SYNOPSIS
+ *
+ * void silc_timer_continue(SilcTimer timer);
+ *
+ * DESCRIPTION
+ *
+ * Continue stopped timer. If timer is running already this does nothing.
+ *
+ ***/
+void silc_timer_continue(SilcTimer timer);
+
+/****f* silcutil/SilcTimerAPI/silc_timer_value
+ *
+ * SYNOPSIS
+ *
+ * void silc_timer_value(SilcTimer timer,
+ * SilcUInt64 *elapsed_time_seconds,
+ * SilcUInt32 *elapsed_time_microseconds);
+ *
+ * DESCRIPTION
+ *
+ * Returns either the current value or the end value of the timer. If the
+ * timer is currently running this returns the currently elapsed time. If
+ * the timer is stopped this returns the cumulative elapsed time.
+ *
+ ***/
+void silc_timer_value(SilcTimer timer,
+ SilcUInt64 *elapsed_time_seconds,
+ SilcUInt32 *elapsed_time_microseconds);
+
+/****f* silcutil/SilcTimerAPI/silc_timer_value_time
+ *
+ * SYNOPSIS
+ *
+ * void silc_timer_value_time(SilcTimer timer, SilcTime ret_time);
+ *
+ * DESCRIPTION
+ *
+ * Same as silc_timer_value but returns the elapsed time to `ret_time'
+ * SilcTime structure as absolute date and time. This is useful if the
+ * returned time needs to be converted into some other format such as
+ * time and date strings.
+ *
+ ***/
+void silc_timer_value_time(SilcTimer timer, SilcTime ret_time);
+
+/****f* silcutil/SilcTimerAPI/silc_timer_start_time
+ *
+ * SYNOPSIS
+ *
+ * void silc_timer_start_time(SilcTimer timer, SilcTime ret_start_time);
+ *
+ * DESCRIPTION
+ *
+ * Returns the timer's start time into `ret_start_time' SilcTime structure.
+ *
+ ***/
+void silc_timer_start_time(SilcTimer timer, SilcTime ret_start_time);
+
+/****f* silcutil/SilcTimerAPI/silc_timer_is_running
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_timer_is_running(SilcTimer timer);
+ *
+ * DESCRIPTION
+ *
+ * Returns TRUE if the timer is currently running, FALSE otherwise.
+ *
+ ***/
+SilcBool silc_timer_is_running(SilcTimer timer);
+
+#include "silctimer_i.h"
+
+#endif /* SILCTIMER_H */