/*****************************************************************************
 * File:   TIM_bridge.h
 *
 * Description:
 * This file provides a insulation layer between the BridgePoint built-in
 * External Enity 'Time' (Key Letters: TIM) and the underlying implementation.
 *
 * OOA Timer methods:
 * Note that in the software architecture there will be a (finite but
 * indeterminate) delay between the expiration of a timer and the delivery
 * of the associated event to the receiving state machine.
 *
 * Notice:
 * (C) Copyright 1999, 2000 ROX Software, Inc.
 *     All rights reserved.
 *
 * This document contains confidential and proprietary information and
 * property of ROX Software, Inc.  No part of this document may be
 * reproduced without the express written permission of ROX Software, Inc.
 ****************************************************************************/

#ifndef TIM_BRIDGE_H
#define TIM_BRIDGE_H

#ifdef	__cplusplus
extern "C" {
#endif

#include "e_types.h"
#include "e_events.h"

/*****************************************************************************
 * TIM_create_date
 *
 * Bridge method to create an analysis specific date instance.
 ****************************************************************************/
extern Escher_Date_t TIM_create_date( const int day,
                                      const int hour,
                                      const int minute,
                                      const int month,
                                      const int second,
                                      const int year );

/*****************************************************************************
 * TIM_current_date
 *
 * Bridge method to get the current date.
 ****************************************************************************/
extern Escher_Date_t TIM_current_date( void );

/*****************************************************************************
 *
 * Bridge methods to get time piece components of a given date.
 ****************************************************************************/
extern int TIM_get_year   ( const Escher_Date_t date );
extern int TIM_get_month  ( const Escher_Date_t date );
extern int TIM_get_day    ( const Escher_Date_t date );
extern int TIM_get_hour   ( const Escher_Date_t date );
extern int TIM_get_minute ( const Escher_Date_t date );
extern int TIM_get_second ( const Escher_Date_t date );

/*****************************************************************************
 * TIM_current_clock
 *
 * Bridge method to get the current clock.
 ****************************************************************************/
extern Escher_TimeStamp_t TIM_current_clock( void );

/*****************************************************************************
 * TIM_timer_start
 *
 * Starts a (one shot) timer to expire in <expression> microseconds,
 * sending the event instance <event> upon expiration.
 * Note that upon expiration the timer will be (automatically) deleted.
 * Returns the instance handle of the non-recurring timer.
 ****************************************************************************/
extern Escher_Timer_t * TIM_timer_start( Escher_OoaEvent_s * event,
                                         const Escher_uSec_t expression );

/*****************************************************************************
 * TIM_timer_start_recurring
 *
 * Starts a (recurring) timer to expire in <expression> microseconds,
 * sending the event instance <event> upon expiration.
 * Upon expiration, the timer will be restarted and fire again in
 * <expression> microseconds and (re)generate the event <event>.
 * Returns the instance handle of the recurring timer.
 ****************************************************************************/
extern Escher_Timer_t * TIM_timer_start_recurring( Escher_OoaEvent_s * event,
                                                   const Escher_uSec_t expression );

/*****************************************************************************
 * TIM_timer_remaining_time
 *
 * Returns the time remaining (in microseconds) before the timer
 * specified by <timer> will expire.  If <timer> no longer exists,
 * a zero value will be returned.  It is important to note that even
 * if <timer> no longer exists, a <event> may still be in
 * transit (e.g., was generated) from a previous <timer> expiration.
 * Respectable analysis must account for this "ships passing" possibility.
 ****************************************************************************/
extern Escher_uSec_t TIM_timer_remaining_time( const Escher_Timer_t * const timer );

/*****************************************************************************
 * TIM_timer_reset_time
 *
 * This method attempts to set an existing timer handle <timer> to expire
 * in <expression> microseconds.  If the timer exists (e.g, it has not
 * already expired), a 'true' value is returned.  If the timer no longer
 * exists, a 'false' value is returned.  In either case, it is important
 * to note that an event may still be in transit (e.g., was already
 * generated) from a previous expiration prior to this method invocation.
 * Respectable analysis must account for this "ships passing" possibility.
 ****************************************************************************/
extern bool TIM_timer_reset_time( const Escher_uSec_t expression,
                                  Escher_Timer_t * const timer );

/*****************************************************************************
 * TIM_timer_add_time
 *
 * This method attempts to add <expression> microseconds to the
 * timer handle <timer>.  If the timer exists (e.g, it has not
 * already expired), a 'true' value is returned.  If the timer no longer
 * exists, a 'false' value is returned.  In either case, it is important
 * to note that an event may still be in transit (e.g., was already
 * generated) from a previous expiration prior to this method invocation.
 * Respectable analysis must account for this "ships passing" possibility.
 ****************************************************************************/
extern bool TIM_timer_add_time( const Escher_uSec_t expression,
                                Escher_Timer_t * const timer );

/*****************************************************************************
 * TIM_timer_cancel
 *
 * This method attempts to cancel and delete the timer handle specified
 * by <timer>.  If the timer still exists (e.g, it has not already
 * expired), a 'true' value is returned.  If the timer no longer exists,
 * 'false' value is returned.  In either case, it is important
 * to note that an event may still be in transit (e.g., was already
 * generated) from a previous expiration prior to this method invocation.
 * Respectable analysis must account for this "ships passing" possibility.
 ****************************************************************************/
extern bool TIM_timer_cancel( Escher_Timer_t * const timer );

/*****************************************************************************
 * TIM_tick
 *
 * This provides a periodic tick to give the timer subsystem the
 * opportunity to check for expired timers and fire them and their
 * respective delayed events.  Calling this routine as often as possible
 * increases the accuracy and resolution of the delayed event timers.  One
 * appropriate place to make this call is from UserBackgroundProcessingCallout
 * found among the system callout routines.
 ****************************************************************************/
extern void TIM_tick( void );

/*****************************************************************************
 * TIM_init
 *
 * This method initializes the timer subsystem.  It must be called
 * during system bring-up.  An appropriate place to make this call
 * is from UserPreOoaInitializationCallout.
 ****************************************************************************/
extern void TIM_init( void );


#ifdef	__cplusplus
}
#endif

#endif   /* TIM_BRIDGE_H */