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 awsTimer 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 awsTimer struct
00036  */
00037 #include "timer_platform.h "
00038 
00039 #include <stdint.h>
00040 #include <stdbool.h>
00041 
00042 /**
00043  * @brief awsTimer 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 awsTimer  awsTimer;
00051 
00052 /**
00053  * @brief Check if a timer is expired
00054  *
00055  * Call this function passing in a timer to check if that timer has expired.
00056  *
00057  * @param awsTimer - pointer to the timer to be checked for expiration
00058  * @return bool - true = timer expired, false = timer not expired
00059  */
00060 bool has_timer_expired(awsTimer *);
00061 
00062 /**
00063  * @brief Create a timer (milliseconds)
00064  *
00065  * Sets the timer to expire in a specified number of milliseconds.
00066  *
00067  * @param awsTimer - pointer to the timer to be set to expire in milliseconds
00068  * @param uint32_t - set the timer to expire in this number of milliseconds
00069  */
00070 void countdown_ms(awsTimer *, uint32_t);
00071 
00072 /**
00073  * @brief Create a timer (seconds)
00074  *
00075  * Sets the timer to expire in a specified number of seconds.
00076  *
00077  * @param awsTimer - pointer to the timer to be set to expire in seconds
00078  * @param uint32_t - set the timer to expire in this number of seconds
00079  */
00080 void countdown_sec(awsTimer *, uint32_t);
00081 
00082 /**
00083  * @brief Check the time remaining on a given timer
00084  *
00085  * Checks the input timer and returns the number of milliseconds remaining on the timer.
00086  *
00087  * @param awsTimer - pointer to the timer to be set to checked
00088  * @return int - milliseconds left on the countdown timer
00089  */
00090 uint32_t left_ms(awsTimer *);
00091 
00092 /**
00093  * @brief Initialize a timer
00094  *
00095  * Performs any initialization required to the timer passed in.
00096  *
00097  * @param awsTimer - pointer to the timer to be initialized
00098  */
00099 void init_timer(awsTimer *);
00100 
00101 #ifdef __cplusplus
00102 }
00103 #endif
00104 
00105 #endif //__TIMER_INTERFACE_H_