/*
 * !tpluslib.alarm.h
 *
 * provides RISCOSLib alarm like library functionality of tplus
 *
 *  Tony Howat/Risc User 1996, this code is based on code which is
 *  Acorn Computers Ltd 1994
 *
 * The TPlus library is *not* freeware and should not be distributed by
 * anyone other than Risc User. Those with an official copy of TPlus
 * (on a Risc User Magazine Disc, Special Disc, CD-ROM etc)
 * have an unlimited licence to link the library with their own progams.
 */

#ifndef __alarm_h
#define __alarm_h

#include "tpluslib:tplus.h"

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

#ifdef __cplusplus
  extern "C" {
#endif

/* ----------------------------- alarm_init --------------------------------
 * Description:   Initialise the alarm system.
 *
 * Parameters:    void
 * Returns:       void.
 * Other Info:    If this call is made more than once, then any pending
 *                alarms are cancelled.
 *
 */

void alarm_init(void);

/* ----------------------------- alarm_timenow -----------------------------
 * Description:   Reports the current monotonic time.
 *
 * Parameters:    void
 * Returns:       the current monotonic time.
 * Other Info:    none.
 *
 */

int alarm_timenow(void);

/* --------------------------- alarm_timedifference ------------------------
 * Description:   Returns difference between two times.
 *
 * Parameters:    int t1 -- the earlier time
 *                int t2 -- the later time
 * Returns:       difference between t1 and t2.
 * Other Info:    Times are as in SWI OS_ReadMonotonicTime. Deals with wrap
 *                round of timer.
 *
 */

int alarm_timedifference(int t1, int t2);


/* ------------------------------ alarm_set --------------------------------
 * Description:   Set an alarm at the given time.
 *
 * Parameters:    int at -- time at which alarm should occur
 *                alarm_handler proc -- function to be called at alarm time
 *                void *handle -- caller-supplied handle to be passed to
 *                                function
 * Returns:       void.
 */

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


/* ----------------------------- alarm_remove ------------------------------
 * Description:   Removes an alarm which was set for a given time with a
 *                given handle.
 *
 * Parameters:    int at -- the time at which the alarm was to be made
 *                void *handle -- the given handle
 * Returns:       void.
 * Other Info:    If no such alarm exists this call has no effect.
 *
 */

void alarm_remove(int at, void *handle);


/* --------------------------- alarm_removeall -----------------------------
 * Description:   Removes all alarms which have a given handle.
 *
 * Parameters:    void *handle -- the handle to search for.
 * Returns:       void.
 * Other Info:    none.
 *
 */

void alarm_removeall(void *handle);


/* ---------------------------- alarm_anypending ---------------------------
 * Description:   Returns whether an alarm is pending with a given handle
 *
 * Parameters:    void *handle -- the handle.
 * Returns:       TRUE if there are any pending alarms for this handle.
 * Other Info:    none.
 *
 */

BOOL alarm_anypending(void *handle);


/* ----------------------------- alarm_next --------------------------------
 * Description:   Informs caller whether an alarm is pending and, if so, for
 *                when it is.
 *
 * Parameters:    int *result -- time for which alarm is pending
 * Returns:       TRUE if an alarm is pending.
 *
 */

BOOL alarm_next(int *result);


/* ---------------------------- alarm_callnext -----------------------------
 * Description:   Calls the next alarm handler function.
 *
 * Parameters:    void
 * Returns:       void.
 *
 */

void alarm_callnext(void);

/* ---------------------------- alarm_event_poll ---------------------------
 * Description:   Direct event_poll replacement, any program using the
 *                alarm calls should call this routine in their poll loop
 *                rather than event_poll.
 *
 * Parameters:    int *event_code - pointer to integer to put the event code
 *                                  in.
 *                WimpPollBlock *poll_block - pointer to block for the
 *                                  returned poll block
 *                void *poll_word - poll word
 * Returns:       Any error which may have ocurred
 *
 */

extern _kernel_oserror *alarm_event_poll (int *event_code, WimpPollBlock *poll_block, void *poll_word);

#ifdef __cplusplus
  }
#endif

#endif

/* end of alarm.h */
