/*
 * alarm.h
 *
 * Calling routines at set times
 *
 * © 1994-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel 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 option)
 * any later version.
 *
 * Steel 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.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __alarm_h
#define __alarm_h

#ifndef BOOL
  #define BOOL int
  #define TRUE 1
  #define FALSE 0
#endif

typedef void (*alarm_handler)(int at,void *handle);

/*
 * void alarm_init(void)
 *
 * Use
 *  None at all
 */

void alarm_init(void);

/*
 * int alarm_timenow(void)
 *
 * Use
 *  Reports the time right now
 */

int alarm_timenow(void);

/*
 * int alarm_timedifference(int t1,int t2)
 *
 * Use
 *  Tells you the difference between two times.  t2 is considered to be later
 *  than t1.
 */

int alarm_timedifference(int t1,int t2);

/*
 * void alarm_set(int at,alarm_handler proc,void *handle)
 *
 * Use
 *  Sets up `proc' to be called at time `at', being passed `handle'.
 */

void alarm_set(int at,alarm_handler proc,void *handle);

/*
 * void alarm_remove(int at,void *handle)
 *
 * Use
 *  Removes an alarm identified by a time and a handle
 */

void alarm_remove(int at,void *handle);

/*
 * void alarm_removeall(void *handle)
 *
 * Use
 *  Removes all alarms for the given handle
 */

void alarm_removeall(void *handle);

/*
 * BOOL alarm_anypending(void *handle)
 *
 * Use
 *  Returns TRUE if there are alarms for the given handle
 */

BOOL alarm_anypending(void *handle);

/*
 * BOOL alarm_next(int *when)
 *
 * Use
 *  Informs the caller (a) if there are any alarms waiting, and (b) when
 *  the next one is.
 *
 * Parameters
 *  int *when == where to put the next time for an alarm (unchanged if no
 *    alarm is set)
 *
 * Returns
 *  TRUE if there are any alarms left
 */

BOOL alarm_next(int *when);

/*
 * void alarm_callnext(void)
 *
 * Use
 *  Calls the next alarm and removes it from the list
 */

void alarm_callnext(void);

#endif