/*
 * zTimer.h
 * 
 * The Zen API 
 * Copyright (C) 2009-2010 by LMI Technologies Inc.
 * 
 * Licensed under The MIT License.
 * Redistributions of files must retain the above copyright notice.
 */
#ifndef LMITECH_ZTIMER_H_INCLUDED
#define LMITECH_ZTIMER_H_INCLUDED

#include <zApi.h>
#include <zApiBegin.h>

typedef zHandle zTimer;           // Represents a periodic callback timer.

typedef zStatus(ZAPI_CALL *zTimerElapsedCallback) (zHandle context, zTimer timer);  //
//
//  Description:
//      Defines the signature of a callback function to receive timer notifications.
//  Arguments:
//      context - User context handle.
//      receiver - zTimer object. 

ZAPI_EXPORT(zStatus) zTimer_Construct(zTimer* timer); //
//
//  Description:
//      Constructs a zTimer object. 
//  Arguments:
//      timer - Receives a handle to the constructed object. 

ZAPI_EXPORT(zStatus) zTimer_Destroy(zTimer timer); //
//
//  Description:
//      Destroys a zTimer object. 
//  Arguments:
//      timer - zTimer object. 
//  Remarks: 
//      It is guaranteed that callbacks are stopped when this function returns. Deadlock can occur 
//      if a timer callback is in progress and is blocked indefinitely. It is not safe to call 
//      this function from within a timer callback. 

ZAPI_EXPORT(zStatus) zTimer_Start(zTimer timer, z64u period, zTimerElapsedCallback callback, zHandle context); //
//
//  Description:
//      Starts timer callbacks at the specified period.
//  Arguments:
//      timer - zTimer object. 
//      period - Callback period, in microseconds. 
//      callback - Callback function.
//      context - User context handle supplied to the callback function.
//  Remarks: 
//      It is safe to call this function from within a timer callback.  It is valid to call Start multiple
//      times without first calling Stop, in order to change the timer period or callback function. 
//  Remarks: 
//      Each subsequent timer period after the first callback is measured relative to the end 
//      of the previous timer callback. 

ZAPI_EXPORT(zStatus) zTimer_Stop(zTimer timer); //
//
//  Description:
//      Stops timer callbacks.
//  Arguments:
//      timer - zTimer object. 
//  Remarks: 
//      It is guaranteed that callbacks are stopped when this function returns. Deadlock can occur 
//      if a timer callback is in progress and is blocked indefinitely. It is safe to call this function 
//      from within a timer callback. 

ZAPI_EXPORT(zBool) zTimer_Enabled(zTimer timer); //
//
//  Description:
//      Reports whether periodic timer callbacks are currently enabled. 
//  Arguments:
//      timer - zTimer object. 
//  Remarks: 
//      Deadlock can occur if a timer callback is in progress and is blocked indefinitely when this
//      function is called. It is safe to call this function from within a timer callback. 

#include <zApiEnd.h>

#endif          /* #ifndef LMITECH_ZTIMER_H_INCLUDED */
