Contiki-NG
coap-timer.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016, SICS, Swedish ICT AB.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  */
29 
30 /**
31  * \file
32  * CoAP timer API.
33  * \author
34  * Niclas Finne <nfi@sics.se>
35  * Joakim Eriksson <joakime@sics.se>
36  */
37 
38 /**
39  * \addtogroup coap
40  * @{
41  *
42  * \defgroup coap-timer CoAP timer API
43  * @{
44  *
45  * The CoAP timer API defines a common interface for CoAP timer and time functionality.
46  */
47 
48 #ifndef COAP_TIMER_H_
49 #define COAP_TIMER_H_
50 
51 #include "contiki.h"
52 #include <stdint.h>
53 
54 typedef struct coap_timer coap_timer_t;
55 struct coap_timer {
56  coap_timer_t *next;
57  void (* callback)(coap_timer_t *);
58  void *user_data;
59  uint64_t expiration_time;
60 };
61 
62 typedef struct {
63  void (* init)(void);
64  uint64_t (* uptime)(void);
65  void (* update)(void);
66 } coap_timer_driver_t;
67 
68 #ifndef COAP_TIMER_DRIVER
69 #ifdef COAP_TIMER_CONF_DRIVER
70 #define COAP_TIMER_DRIVER COAP_TIMER_CONF_DRIVER
71 #else /* COAP_TIMER_CONF_DRIVER */
72 #define COAP_TIMER_DRIVER coap_timer_default_driver
73 #endif /* COAP_TIMER_CONF_DRIVER */
74 #endif /* COAP_TIMER_DRIVER */
75 
76 extern const coap_timer_driver_t COAP_TIMER_DRIVER;
77 
78 /**
79  * \brief Get the time since boot in milliseconds.
80  * \return The number of milliseconds since boot.
81  */
82 static inline uint64_t
84 {
85  return COAP_TIMER_DRIVER.uptime();
86 }
87 
88 /**
89  * \brief Get the time since boot in seconds.
90  * \return The number of seconds since boot.
91  */
92 static inline uint32_t
94 {
95  return (uint32_t)(COAP_TIMER_DRIVER.uptime() / 1000);
96 }
97 
98 /**
99  * \brief Set a callback function to be called when a CoAP timer expires.
100  *
101  * \param timer A pointer to a CoAP timer.
102  * \param callback A callback function.
103  */
104 static inline void
105 coap_timer_set_callback(coap_timer_t *timer, void (* callback)(coap_timer_t *))
106 {
107  timer->callback = callback;
108 }
109 
110 /**
111  * \brief Get user data that has been attached to a CoAP timer.
112  *
113  * \param timer A pointer to a CoAP timer.
114  * \return An opaque pointer to user data or NULL if no user data is
115  * attached to the timer.
116  */
117 static inline void *
118 coap_timer_get_user_data(coap_timer_t *timer)
119 {
120  return timer->user_data;
121 }
122 
123 /**
124  * \brief Attach user data to a CoAP timer.
125  *
126  * \param timer A pointer to a CoAP timer.
127  * \param data An opaque pointer to user data.
128  */
129 static inline void
130 coap_timer_set_user_data(coap_timer_t *timer, void *data)
131 {
132  timer->user_data = data;
133 }
134 
135 /**
136  * \brief Check if a CoAP timer has expired.
137  *
138  * \param timer A pointer to a CoAP timer.
139  * \return Non-zero if the timer has expired, zero otherwise.
140  */
141 static inline int
142 coap_timer_expired(const coap_timer_t *timer)
143 {
144  return timer->expiration_time <= coap_timer_uptime();
145 }
146 
147 /**
148  * \brief Stop a pending CoAP timer.
149  *
150  * After this function has been called, the timer will be expired
151  * and will not call the callback function.
152  *
153  * \param timer A pointer to a CoAP timer.
154  */
155 void coap_timer_stop(coap_timer_t *timer);
156 
157 /**
158  * \brief Set a CoAP timer to expire after the specified time.
159  *
160  * \param timer A pointer to a CoAP timer.
161  * \param time The time until the timer expires.
162  */
163 void coap_timer_set(coap_timer_t *timer, uint64_t time);
164 
165 /**
166  * \brief Reset a CoAP timer to expire a specified time after the
167  * last expiration time.
168  *
169  * This function sets the CoAP timer to expire the specified time
170  * after the previous expiration time. If the new expiration time
171  * has already passed, the timer will expire as soon as possible.
172  *
173  * If the timer has not yet expired when this function is called,
174  * the time until the timer expires will be extended by the
175  * specified time.
176  *
177  * \param timer A pointer to a CoAP timer.
178  * \param time The time after previous expiration the timer expires.
179  */
180 void coap_timer_reset(coap_timer_t *timer, uint64_t time);
181 
182 /**
183  * Get the time until next CoAP timer expires or 0 if there already exists
184  * expired timers that have not yet been processed. This function is normally
185  * never called by application code.
186  *
187  * Returns the time to next CoAP timer expires or 0 if unprocessed expired
188  * timers exists. Returns a time in the future if there are no timers pending.
189  */
191 
192 /**
193  * This function must be called periodically by the CoAP timer driver to
194  * process any expired CoAP timers. This function is normally never called by
195  * application code.
196  *
197  * Returns non-zero if it needs to run again to process more timers.
198  */
199 int coap_timer_run(void);
200 
201 /**
202  * This function initializes the CoAP timer library. It is automatically
203  * called at first use of a CoAP timer. This function is normally never called
204  * by application code.
205  */
206 void coap_timer_init(void);
207 
208 #endif /* COAP_TIMER_H_ */
209 /** @} */
210 /** @} */
static uint32_t coap_timer_seconds(void)
Get the time since boot in seconds.
Definition: coap-timer.h:93
static void * coap_timer_get_user_data(coap_timer_t *timer)
Get user data that has been attached to a CoAP timer.
Definition: coap-timer.h:118
A timer.
Definition: timer.h:82
static void coap_timer_set_callback(coap_timer_t *timer, void(*callback)(coap_timer_t *))
Set a callback function to be called when a CoAP timer expires.
Definition: coap-timer.h:105
uint64_t coap_timer_time_to_next_expiration(void)
Get the time until next CoAP timer expires or 0 if there already exists expired timers that have not ...
Definition: coap-timer.c:117
void coap_timer_reset(coap_timer_t *timer, uint64_t time)
Reset a CoAP timer to expire a specified time after the last expiration time.
Definition: coap-timer.c:110
static int coap_timer_expired(const coap_timer_t *timer)
Check if a CoAP timer has expired.
Definition: coap-timer.h:142
static uint64_t coap_timer_uptime(void)
Get the time since boot in milliseconds.
Definition: coap-timer.h:83
void coap_timer_init(void)
This function initializes the CoAP timer library.
Definition: coap-timer.c:176
static void coap_timer_set_user_data(coap_timer_t *timer, void *data)
Attach user data to a CoAP timer.
Definition: coap-timer.h:130
void coap_timer_stop(coap_timer_t *timer)
Stop a pending CoAP timer.
Definition: coap-timer.c:92
void coap_timer_set(coap_timer_t *timer, uint64_t time)
Set a CoAP timer to expire after the specified time.
Definition: coap-timer.c:103
int coap_timer_run(void)
This function must be called periodically by the CoAP timer driver to process any expired CoAP timers...
Definition: coap-timer.c:137