1 /*

     2 * Copyright (c) 2001-2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  EAP and WLAN authentication protocols.

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #if !defined(_EAP_TIMER_QUEU_H_)

    22 #define _EAP_TIMER_QUEU_H_

    23 

    24 //#include "eap_am_memory.h"

    25 #include "eap_am_tools.h"

    26 #include "eap_tools.h"

    27 #include "abs_eap_am_mutex.h"

    28 

    29 

    30 /** @file */

    31 

    32 const u32_t EAP_TIMER_RESOLUTION  = 500u; ///< Timer resolution in milli seconds.

    33 

    34 const u32_t EAP_TIMER_QUEUE_LONG_SLEEP_TIME = 86400000;  ///< Long timer sleep time of millisecond timer in milli seconds (24 hours).

    35 

    36 class eap_timer_queue_hash_c;

    37 

    38 // ---------------------------------------------------------------------

    39 

    40 /// This class is one timer event stored to timer queue.

    41 class EAP_EXPORT eap_timer_queue_event_c

    42 {

    43 private:

    44 	//--------------------------------------------------

    45 

    46 	abs_eap_am_tools_c * const m_am_tools;

    47 

    48 	abs_eap_base_timer_c *m_initializer; ///< m_initializer is the initializer of timer event. Call backs are directed to initializer.

    49 

    50 	u32_t m_id; ///< m_id is selected by caller. Caller could separate timer events by this value.

    51 

    52 	void *m_data; ///< m_data is pointer to any data of initializer.

    53 

    54 	u32_t m_time_ms; ///< m_time_ms is the time after this timer event should elapse.

    55 

    56 	u32_t m_original_time_ms; ///< m_original_time_ms is the original set time.

    57 

    58 	eap_timer_queue_event_c *m_prev; ///< m_prev is pointer to the previous timer event in the timer queue.

    59 	eap_timer_queue_event_c *m_next; ///< m_next is pointer to the next timer event in the timer queue.

    60 

    61 	eap_timer_queue_hash_c *m_hash;

    62 

    63 	eap_timer_queue_event_c *m_prev_same_time; ///< m_prev_same_time is pointer to the previous timer event with the same elapse time.

    64 	eap_timer_queue_event_c *m_next_same_time; ///< m_next_same_time is pointer to the next timer event with the same elapse time.

    65 

    66 	//--------------------------------------------------

    67 protected:

    68 	//--------------------------------------------------

    69 

    70 	//--------------------------------------------------

    71 public:

    72 	//--------------------------------------------------

    73 

    74 	// 

    75 	virtual ~eap_timer_queue_event_c();

    76 

    77 	//--------------------------------------------------

    78 

    79 	// 

    80 	eap_timer_queue_event_c(

    81 		abs_eap_am_tools_c * const tools, 

    82 		abs_eap_base_timer_c * const initializer, 

    83 		const u32_t id, 

    84 		void * const data,

    85 		const u32_t p_time_ms);

    86 

    87 	//--------------------------------------------------

    88 

    89 	// 

    90 	u32_t get_time() const;

    91 

    92 	//--------------------------------------------------

    93 

    94 	// 

    95 	u32_t get_original_time() const;

    96 

    97 	//--------------------------------------------------

    98 

    99 	// 

   100 	eap_timer_queue_event_c *get_prev() const;

   101 

   102 	//--------------------------------------------------

   103 

   104 	// 

   105 	eap_timer_queue_event_c *get_next() const;

   106 

   107 	//--------------------------------------------------

   108 

   109 	// 

   110 	eap_timer_queue_event_c *get_prev_same_time() const;

   111 

   112 	//--------------------------------------------------

   113 

   114 	// 

   115 	eap_timer_queue_event_c *get_next_same_time() const;

   116 

   117 	//--------------------------------------------------

   118 

   119 	// 

   120 	eap_timer_queue_hash_c * get_hash() const;

   121 

   122 	//--------------------------------------------------

   123 

   124 	// 

   125 	u32_t pulse_time(const u32_t resolution);

   126 

   127 	//--------------------------------------------------

   128 

   129 	// 

   130 	void decrease_time_left(const u32_t decrease_time);

   131 

   132 	//--------------------------------------------------

   133 

   134 	// 

   135 	void increase_time_left(const u32_t increase_time);

   136 

   137 	//--------------------------------------------------

   138 

   139 	// 

   140 	void set_prev(eap_timer_queue_event_c * const prev);

   141 

   142 	//--------------------------------------------------

   143 

   144 	// 

   145 	void set_next(eap_timer_queue_event_c * const next);

   146 

   147 	//--------------------------------------------------

   148 

   149 	// 

   150 	void set_prev_same_time(eap_timer_queue_event_c * const prev_same_time);

   151 

   152 	//--------------------------------------------------

   153 

   154 	// 

   155 	void set_next_same_time(eap_timer_queue_event_c * const next_same_time);

   156 

   157 	//--------------------------------------------------

   158 

   159 	// 

   160 	void set_hash(eap_timer_queue_hash_c * const hash);

   161 

   162 	//--------------------------------------------------

   163 

   164 	// 

   165 	abs_eap_base_timer_c * get_initializer() const;

   166 

   167 	//--------------------------------------------------

   168 

   169 	// 

   170 	u32_t get_id() const;

   171 

   172 	//--------------------------------------------------

   173 

   174 	// 

   175 	void * get_data() const;

   176 

   177 	//--------------------------------------------------

   178 

   179 	// 

   180 	u32_t get_time_ms();

   181 

   182 	//--------------------------------------------------

   183 }; // class eap_timer_queue_event_c

   184 

   185 

   186 // ---------------------------------------------------------------------

   187 

   188 /// This class is hash to timer event stored to timer queue.

   189 /**

   190  * Each timer event is stored to the timer queue (eap_timer_queue_c) with events (eap_timer_queue_event_c)

   191  * and to the hash array of the timer events (eap_timer_queue_c::m_map).

   192  */

   193 class EAP_EXPORT eap_timer_queue_hash_c

   194 {

   195 private:

   196 	//--------------------------------------------------

   197 

   198 	abs_eap_am_tools_c * const m_am_tools;

   199 

   200 	u32_t m_index; ///< Index in the hash array.

   201 	eap_timer_queue_event_c * m_atom; ///< Pointer to the time event.

   202 

   203 	eap_timer_queue_hash_c *m_prev; ///< m_prev is pointer to the revious hash.

   204 	eap_timer_queue_hash_c *m_next; ///< m_next is pointer to the next hash.

   205 

   206 	//--------------------------------------------------

   207 protected:

   208 	//--------------------------------------------------

   209 

   210 	//--------------------------------------------------

   211 public:

   212 	//--------------------------------------------------

   213 

   214 	// 

   215 	virtual ~eap_timer_queue_hash_c();

   216 

   217 	//--------------------------------------------------

   218 

   219 	// 

   220 	eap_timer_queue_hash_c(

   221 		abs_eap_am_tools_c * const tools, 

   222 		eap_timer_queue_event_c * const atom,

   223 		const u32_t index);

   224 

   225 	//--------------------------------------------------

   226 

   227 	// 

   228 	eap_timer_queue_hash_c *get_next() const;

   229 

   230 	//--------------------------------------------------

   231 

   232 	// 

   233 	eap_timer_queue_hash_c *get_prev() const;

   234 

   235 	//--------------------------------------------------

   236 

   237 	// 

   238 	u32_t get_index() const;

   239 

   240 	//--------------------------------------------------

   241 

   242 	// 

   243 	void set_next(eap_timer_queue_hash_c * const next);

   244 

   245 	// 

   246 	void set_prev(eap_timer_queue_hash_c * const prev);

   247 

   248 	eap_timer_queue_event_c * get_atom();

   249 

   250 	i32_t compare(

   251 		const abs_eap_base_timer_c * const a_initializer, 

   252 		const u32_t a_id,

   253 		const abs_eap_base_timer_c * const b_initializer, 

   254 		const u32_t b_id);

   255 

   256 	//--------------------------------------------------

   257 }; // class eap_timer_queue_hash_c

   258 

   259 // ---------------------------------------------------------------------

   260 

   261 /// Size of the hash array of eap_timer_queue_hash_c elements.

   262 /// Hash array optimizes the cancellation of timer event.

   263 const u32_t EAP_TIMER_QUEUE_HASH_SIZE = 1024;

   264 

   265 /// This class implements the timer queue.

   266 /**

   267  * User of the timer queue must be inherited from abs_eap_base_timer_c.

   268  * The abs_eap_base_timer_c class is the call back interface from timer queue to the user.

   269  * @see Note the timer queue interface is used through abs_eap_am_tools_c.

   270  * Functions are abs_eap_am_tools_c::get_timer_resolution_ms(), 

   271  * abs_eap_am_tools_c::set_timer(), 

   272  * abs_eap_am_tools_c::cancel_timer(), 

   273  * abs_eap_am_tools_c::cancel_all_timers() and

   274  * abs_eap_am_tools_c::pulse_timer()

   275  * 

   276  * In the following figure m_timer_queue is pointer to the first timer event in the list.

   277  * The timer list is horizontal list right from m_timer_queue.

   278  * Each timer event in the list represents one time segment

   279  * that must elapse to zero before event is active. Timer event - the square box in the figure -

   280  * is type of eap_timer_queue_event_c.

   281  * Each time segment includes list of the same time values, the vertical lists.

   282  * 

   283  * Place for new timer event is found by stepping the the horizontal timer list

   284  * and adding the time values sum until the list ends

   285  * or time sum is equal or greater than time of the new timer event.

   286  * If time sum is equal to the time of the new timer event, the new timer event is

   287  * added to the second in the vertical list. If time sum is greater than the time of the new timer event,

   288  * the new timer event is added before the existing time event. In this case a new vertical list is created.

   289  * If the list ends the new time event is added to the end of the timer queue.

   290  * 

   291  * @code

   292  *                  +---------------+  +---------------+  +---------------+

   293  *   m_timer_queue->| m_time_ms 0   |->| m_time_ms 2000|->| m_time_ms 500 | // This horizontal list is the timer queue.

   294  *                  +---------------+  +---------------+  +---------------+

   295  *                          |                  |                  |        

   296  *                          V                  V                  V        

   297  *                  +---------------+  +---------------+  +---------------+

   298  *                  | m_time_ms 0   |  | m_time_ms 0   |  | m_time_ms 0   |

   299  *                  +---------------+  +---------------+  +---------------+

   300  *                          |                  |                           

   301  *                          V                  V                           

   302  *                  +---------------+  +---------------+                   

   303  *                  | m_time_ms 0   |  | m_time_ms 0   |                   

   304  *                  +---------------+  +---------------+                   

   305  *                                             |                           

   306  *                                             V                           

   307  *                                     +---------------+                   

   308  *                                     | m_time_ms 0   |                   

   309  *                                     +---------------+                   

   310  *   // Each vertical list includes the timer events that have the same time.

   311  * @endcode

   312  */

   313 class EAP_EXPORT eap_timer_queue_c

   314 {

   315 private:

   316 	//--------------------------------------------------

   317 

   318 	/// This is pointer to the tools class.

   319 	abs_eap_am_tools_c * const m_am_tools;

   320 

   321 	/// This is pointer to the first timer event.

   322 	eap_timer_queue_event_c *m_timer_queue;

   323 

   324 	/// These are begin and end of the list of new events

   325 	/// that are will be added to timer queue

   326 	/// during the next pulse_timer() function

   327 	/// call.

   328 	eap_timer_queue_event_c *m_new_event_begin;

   329 	eap_timer_queue_event_c *m_new_event_end;

   330 

   331 	/// This is the resolution of this timer queue.

   332 	/// Each pulse is assumed to be this length.

   333 	/// This is also the minimum timer value.

   334 	u32_t m_timer_resolution_ms;

   335 	

   336 	/// This is hash array of timer events.

   337 	eap_timer_queue_hash_c * m_map[EAP_TIMER_QUEUE_HASH_SIZE];

   338 

   339 	/// This indicates whether this timer queue is active. Inactive timer queue does not accept new timer events.

   340 	bool m_is_active;

   341 

   342 	/// This indicates whether this object was generated successfully.

   343 	bool m_is_valid;

   344 

   345 	bool m_use_eap_millisecond_timer;

   346 

   347 	//--------------------------------------------------

   348 

   349 	/**

   350 	 * this function traces one timer event.

   351 	 */

   352 	void trace_timer_event(

   353 		const eap_const_string prefix, 

   354 		const eap_timer_queue_event_c * const event);

   355 

   356 	/**

   357 	 * This function traces all initialized timer events.

   358 	 */

   359 	void trace_timer();

   360 

   361 	eap_status_e add_hash_of_timer_event(

   362 		eap_timer_queue_event_c * const event,

   363 		const abs_eap_base_timer_c * const initializer, 

   364 		const u32_t id);

   365 

   366 	eap_timer_queue_event_c * get_hashed_timer_event(

   367 		const abs_eap_base_timer_c * const initializer, 

   368 		const u32_t id);

   369 

   370 	eap_status_e remove_hash_of_timer_event(

   371 		eap_timer_queue_event_c * const event);

   372 

   373 	//--------------------------------------------------

   374 

   375 	// 

   376 	u32_t hash(

   377 		const u32_t size,

   378 		const abs_eap_base_timer_c * const initializer, 

   379 		const u32_t id) const;

   380 

   381 	//--------------------------------------------------

   382 

   383 	/**

   384 	 * This function deactivate this timer queue.

   385 	 * This is called before the timer queue is deleted.

   386 	 * Inactive timer queue does not accept new timer events.

   387 	 */

   388 	void deactivate_timer_queue();

   389 

   390 	/**

   391 	 * This function adds the timer event immediately to timer queue.

   392 	 */

   393 	eap_status_e add_timer(

   394 		eap_timer_queue_event_c *event);

   395 

   396 	/**

   397 	 * New timer events are added with this function because the next pulse might

   398 	 * be very long, and the long pulse will cause the new event expire immediately.

   399 	 * By using this function the shortest timer events in the

   400 	 * timer queue are handled and after that the new timer events

   401 	 * are added to timer queue.

   402 	 */

   403 	eap_status_e add_pending_timer();

   404 

   405 	void add_end_of_vertical_list(

   406 		eap_timer_queue_event_c *begin,

   407 		eap_timer_queue_event_c *event);

   408 

   409 	eap_status_e add_new_pending_timer(

   410 		eap_timer_queue_event_c *event);

   411 

   412 	/**

   413 	 * This function cancels all pending timer events.

   414 	 */

   415 	eap_status_e cancel_pending_timer(

   416 		abs_eap_base_timer_c * const initializer, 

   417 		const u32_t id);

   418 

   419 	//--------------------------------------------------

   420 protected:

   421 	//--------------------------------------------------

   422 

   423 	//--------------------------------------------------

   424 public:

   425 	//--------------------------------------------------

   426 

   427 	/**

   428 	 * Destructor does nothing special.

   429 	 * Note user is assumed to call cancel_all_timers()

   430 	 * before timer queue is deleted.

   431 	 */

   432 	virtual ~eap_timer_queue_c();

   433 

   434 	//--------------------------------------------------

   435 

   436 	/**

   437 	 * Constructor initializes the timer queue.

   438 	 * @param timer_resolution_ms is the resolution in milli seconds of this timer.

   439 	 * The pulse() member function is assumed to be called using 

   440 	 * timer_resolution_ms interval.

   441 	 */

   442 	eap_timer_queue_c(

   443 		abs_eap_am_tools_c * const tools, 

   444 		const u32_t timer_resolution_ms);

   445 

   446 	//--------------------------------------------------

   447 

   448 	/**

   449 	 * This function re-activates timer queue.

   450 	 * Symbian AM call this function when AM-tools object is re-used.

   451 	 * This can be called after cancel_all_timers() function.

   452 	 * cancel_all_timers() function de-activated timer queue.

   453 	 */

   454 	eap_status_e re_activate_timer_queue();

   455 

   456 	//--------------------------------------------------

   457 

   458 	/**

   459 	 * This function returns flag whether millisecond timer is in use (true) or not (false).

   460 	 */

   461 	bool get_use_eap_milli_second_timer();

   462 

   463 	//--------------------------------------------------

   464 

   465 	/**

   466 	 * This function activates millisecond timer with true value.

   467 	 */

   468 	void set_use_eap_milli_second_timer(const bool use_eap_millisecond_timer);

   469 

   470 	//--------------------------------------------------

   471 

   472 	/**

   473 	 * @return Returns the initialized timer resolution.

   474 	 */

   475 	u32_t get_timer_resolution_ms();

   476 

   477 	//--------------------------------------------------

   478 

   479 	/**

   480 	 * @return Sets the timer resolution.

   481 	 */

   482 	void set_timer_resolution_ms(const u32_t timer_resolution_ms);

   483 

   484 	//--------------------------------------------------

   485 

   486 	/**

   487 	 * The pulse() member function is assumed to be called using 

   488 	 * timer_resolution_ms interval.

   489 	 * This function decreases the remaining time of the first timer event.

   490 	 * When remaining time reaches zero the timer queue calls the timer_expired() function.

   491 	 * Function returns the next sleep time in milli seconds.

   492 	 */

   493 	u32_t pulse_timer(

   494 		const u32_t elapsed_time_in_ms,

   495 		const bool can_call_timer_expired_when_true);

   496 

   497 	//--------------------------------------------------

   498 

   499 	// 

   500 	bool get_timer_queue_is_empty();

   501 

   502 	//--------------------------------------------------

   503 

   504 	/**

   505 	 * This function initializes a new timer event.

   506 	 * @param initializer is the caller of this function. Call backs are directed to initializer.

   507 	 * @param id is selected by caller. Caller could separate timer events by this value.

   508 	 * @param data is pointer to any data. After timer is alapsed or cancelled 

   509 	 * timer queue calls timer_delete_data() function. The initializer could delete possible

   510 	 * allocated data.

   511 	 * @param p_time_ms is the time after this timer event should elapse.

   512 	 */

   513 	eap_status_e set_timer(

   514 		abs_eap_base_timer_c * const initializer, 

   515 		const u32_t id, 

   516 		void * const data,

   517 		const u32_t time_ms);

   518 

   519 	//--------------------------------------------------

   520 

   521 	/**

   522 	 * This function cancels the timer event.

   523 	 * @param initializer is the caller of this function. Call backs are directed to initializer.

   524 	 * @param id is selected by caller. Caller could separate timer events by this value.

   525 	 */

   526 	eap_status_e cancel_timer(

   527 		abs_eap_base_timer_c * const initializer, 

   528 		const u32_t id);

   529 

   530 	//--------------------------------------------------

   531 

   532 	/**

   533 	 * This function cancels all timer events from this timer queue.

   534 	 * This is called before the timer queue is deleted.

   535 	 */

   536 	eap_status_e cancel_all_timers();

   537 

   538 	//--------------------------------------------------

   539 

   540 	/**

   541 	 * The get_is_valid() function returns the status of the eap_core object.

   542 	 * True indicates the object is initialized succesfully.

   543 	 */

   544 	bool get_is_valid() const;

   545 

   546 	//--------------------------------------------------

   547 }; // class eap_timer_queue_c

   548 

   549 

   550 #endif //#if !defined(_EAP_TIMER_QUEU_H_)

   551 

   552 

   553 

   554 // End.