timer_interface.h

00001 /*******************************************************************************
00002  * Copyright (c) 2014 IBM Corp.
00003  *
00004  * All rights reserved. This program and the accompanying materials
00005  * are made available under the terms of the Eclipse Public License v1.0
00006  * and Eclipse Distribution License v1.0 which accompany this distribution.
00007  *
00008  * The Eclipse Public License is available at
00009  *    http://www.eclipse.org/legal/epl-v10.html
00010  * and the Eclipse Distribution License is available at
00011  *   http://www.eclipse.org/org/documents/edl-v10.php.
00012  *
00013  * Contributors:
00014  *    Allan Stockdill-Mander - initial API and implementation and/or initial documentation
00015  *******************************************************************************/
00016 
00017 /**
00018  * @file timer_interface.h
00019  * @brief Timer interface definition for MQTT client.
00020  *
00021  * Defines an interface to timers that can be used by other system
00022  * components.  MQTT client requires timers to handle timeouts and
00023  * MQTT keep alive.
00024  * Starting point for porting the SDK to the timer hardware layer of a new platform.
00025  */
00026 
00027 #ifndef __TIMER_INTERFACE_H_
00028 #define __TIMER_INTERFACE_H_
00029 
00030 #ifdef __cplusplus
00031 extern "C" {
00032 #endif
00033 
00034 /**
00035  * The platform specific timer header that defines the Timer struct
00036  */
00037 #include "timer_platform.h"
00038 
00039 #include <stdint.h>
00040 #include <stdbool.h>
00041 
00042 /**
00043  * @brief Timer Type
00044  *
00045  * Forward declaration of a timer struct.  The definition of this struct is
00046  * platform dependent.  When porting to a new platform add this definition
00047  * in "timer_<platform>.h" and include that file above.
00048  *
00049  */
00050 //typedef struct Timer Timer;
00051 typedef TimerExt TimerAWS;
00052 
00053 /**
00054  * @brief Check if a timer is expired
00055  *
00056  * Call this function passing in a timer to check if that timer has expired.
00057  *
00058  * @param Timer - pointer to the timer to be checked for expiration
00059  * @return bool - true = timer expired, false = timer not expired
00060  */
00061 bool has_timer_expired(TimerAWS *);
00062 
00063 /**
00064  * @brief Create a timer (milliseconds)
00065  *
00066  * Sets the timer to expire in a specified number of milliseconds.
00067  *
00068  * @param Timer - pointer to the timer to be set to expire in milliseconds
00069  * @param uint32_t - set the timer to expire in this number of milliseconds
00070  */
00071 void countdown_ms(TimerAWS *, uint32_t);
00072 
00073 /**
00074  * @brief Create a timer (seconds)
00075  *
00076  * Sets the timer to expire in a specified number of seconds.
00077  *
00078  * @param Timer - pointer to the timer to be set to expire in seconds
00079  * @param uint32_t - set the timer to expire in this number of seconds
00080  */
00081 void countdown_sec(TimerAWS *, uint32_t);
00082 
00083 /**
00084  * @brief Check the time remaining on a given timer
00085  *
00086  * Checks the input timer and returns the number of milliseconds remaining on the timer.
00087  *
00088  * @param Timer - pointer to the timer to be set to checked
00089  * @return int - milliseconds left on the countdown timer
00090  */
00091 uint32_t left_ms(TimerAWS *);
00092 
00093 /**
00094  * @brief Initialize a timer
00095  *
00096  * Performs any initialization required to the timer passed in.
00097  *
00098  * @param Timer - pointer to the timer to be initialized
00099  */
00100 void init_timer(TimerAWS *);
00101 
00102 #ifdef __cplusplus
00103 }
00104 #endif
00105 
00106 #endif //__TIMER_INTERFACE_H_