1 #ifndef __WILC_TIMER_H__
2 #define __WILC_TIMER_H__
6 * @brief Timer (One Shot and Periodic) OS wrapper functionality
8 * @sa wilc_oswrapper.h top level OS wrapper file
13 typedef void (*tpfWILC_TimerFunction)(void *);
16 * @struct tstrWILC_TimerAttrs
17 * @brief Timer API options
23 /* a dummy member to avoid compiler errors*/
25 } tstrWILC_TimerAttrs;
28 * @brief Creates a new timer
29 * @details Timers are a useful utility to execute some callback function
31 * A timer object has 3 states : IDLE, PENDING and EXECUTING
32 * IDLE : initial timer state after creation, no execution for the
33 * callback function is planned
34 * PENDING : a request to execute the callback function is made
35 * using WILC_TimerStart.
36 * EXECUTING : the timer has expired and its callback is now
37 * executing, when execution is done the timer returns to PENDING
38 * if the feature CONFIG_WILC_TIMER_PERIODIC is enabled and
39 * the flag tstrWILC_TimerAttrs.bPeriodicTimer is set. otherwise the
40 * timer will return to IDLE
41 * @param[out] pHandle handle to the newly created timer object
42 * @param[in] pfEntry pointer to the callback function to be called when the
44 * the underlaying OS may put many restrictions on what can be
45 * called inside a timer's callback, as a general rule no blocking
46 * operations (IO or semaphore Acquision) should be perfomred
47 * It is recommended that the callback will be as short as possible
48 * and only flags other threads to do the actual work
49 * also it should be noted that the underlaying OS maynot give any
50 * guarentees on which contect this callback will execute in
51 * @param[in] pstrAttrs Optional attributes, NULL for default
52 * @return Error code indicating sucess/failure
58 WILC_ErrNo WILC_TimerCreate(WILC_TimerHandle *pHandle,
59 tpfWILC_TimerFunction pfCallback, tstrWILC_TimerAttrs *pstrAttrs);
63 * @brief Destroys a given timer
64 * @details This will destroy a given timer freeing any resources used by it
65 * if the timer was PENDING Then must be cancelled as well(i.e.
66 * goes to IDLE, same effect as calling WILC_TimerCancel first)
67 * if the timer was EXECUTING then the callback will be allowed to
68 * finish first then all resources are freed
69 * @param[in] pHandle handle to the timer object
70 * @param[in] pstrAttrs Optional attributes, NULL for default
71 * @return Error code indicating sucess/failure
77 WILC_ErrNo WILC_TimerDestroy(WILC_TimerHandle *pHandle,
78 tstrWILC_TimerAttrs *pstrAttrs);
81 * @brief Starts a given timer
82 * @details This function will move the timer to the PENDING state until the
83 * given time expires (in msec) then the callback function will be
84 * executed (timer in EXECUTING state) after execution is dene the
85 * timer either goes to IDLE (if bPeriodicTimer==WILC_FALSE) or
86 * PENDING with same timeout value (if bPeriodicTimer==WILC_TRUE)
87 * @param[in] pHandle handle to the timer object
88 * @param[in] u32Timeout timeout value in msec after witch the callback
89 * function will be executed. Timeout value of 0 is not allowed for
91 * @param[in] pstrAttrs Optional attributes, NULL for default,
92 * set bPeriodicTimer to run this timer as a periodic timer
93 * @return Error code indicating sucess/failure
99 WILC_ErrNo WILC_TimerStart(WILC_TimerHandle *pHandle, WILC_Uint32 u32Timeout, void *pvArg,
100 tstrWILC_TimerAttrs *pstrAttrs);
104 * @brief Stops a given timer
105 * @details This function will move the timer to the IDLE state cancelling
106 * any sheduled callback execution.
107 * if this function is called on a timer already in the IDLE state
108 * it will have no effect.
109 * if this function is called on a timer in EXECUTING state
110 * (callback has already started) it will wait until executing is
111 * done then move the timer to the IDLE state (which is trivial
112 * work if the timer is non periodic)
113 * @param[in] pHandle handle to the timer object
114 * @param[in] pstrAttrs Optional attributes, NULL for default,
115 * @return Error code indicating sucess/failure
116 * @sa WILC_TimerAttrs
121 WILC_ErrNo WILC_TimerStop(WILC_TimerHandle *pHandle,
122 tstrWILC_TimerAttrs *pstrAttrs);