/* IRCfs - IRC FileServ for *nix.
 * Copyright (C) 2002  Nick 'Zaf' Clifford <zaf@nrc.co.nz>
 * For licensing details, refer to the LICENSE file in the source 
 * code directory.
 */
#ifndef __include_timer_h__
#define __include_timer_h__

/* For time_t type */
#include <time.h>
#include <sys/time.h>

#define MAGIC_TIMER	0xfabadaba
struct timer;

typedef int (*timer_callback_t)(struct timer *t, void *appdata);

/* Starts a timer, will call the callback function cb in howlong seconds
 *
 * When the time elapses, the callback function will be called.
 * If the callback function doesn't reset or restart the specified timer,
 * it will be destroyed. You may safely restart, stop, reset, or destroy
 * a timer at anytime including in the callback function.
 * 
 * Note: The callback function will be called no EARLIER than howlong
 * seconds, it may however be called at ANY time after howlong seconds.
 * The callback function will only be called once, UNLESS the callback
 * function resets the timer (using timer_reset or timer_restart)
 */
struct timer *timer_start(time_t howlong, timer_callback_t cb, void *appdata);

time_t timer_reset(struct timer *t);
time_t timer_restart(struct timer *t, time_t howlong);

/* Stops the specified timer */
int timer_stop(struct timer *t);

/* Searchs through the timer list for a timer that calls the specified
 * callback
 */
struct timer *timer_search(timer_callback_t cb);

/* Searchs through the timer list for a timer that calls the specified
 * callback AND has an appdata with the same value
 */
struct timer *timer_search2(timer_callback_t cb, void *appdata);

/* Returns the appdata set when the timer was created. */
void *timer_get_appdata(struct timer *t);
/* Returns the duration specified for the timer. See timer_get_time_left
 * for how long until the timer times out.
 */
time_t timer_get_duration(struct timer *t);
/* Returns how many seconds left until the timer times out. (See notes
 * for timer_start on the timing interval
 */
time_t timer_get_time_left(struct timer *t);

/* Returns a pointer to the callback function that will be called when
 * the timer times out
 */
timer_callback_t timer_get_callback(struct timer *t);

/* Destroys the specifed timer and frees any memory associated with it.
 * After this the timer handle is invalid
 */
void timer_destroy(struct timer *t);

#endif