author | Arnaud Lenoir |
Tue, 27 Jul 2010 14:02:05 +0100 | |
changeset 17 | fc9a6286e87d |
parent 0 | bb4b476bbb96 |
permissions | -rw-r--r-- |
0
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
1 |
/* |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
2 |
idletimer.h |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
3 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
4 |
Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
5 |
All rights reserved. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
6 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
7 |
This program and the accompanying materials are made available |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
8 |
under the terms of the Eclipse Public License v1.0 which accompanies |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
9 |
this distribution, and is available at |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
10 |
http://www.eclipse.org/legal/epl-v10.html |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
11 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
12 |
Initial Contributors: |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
13 |
Nokia Corporation - initial contribution. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
14 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
15 |
Contributors: |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
16 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
17 |
// Description |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
18 |
// |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
19 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
20 |
#ifndef IDLETIMER_H |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
21 |
#define IDLETIMER_H |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
22 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
23 |
#include <nkern.h> |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
24 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
25 |
/** |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
26 |
@file API for Idle Timers |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
27 |
@publishedPartner |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
28 |
@prototype |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
29 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
30 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
31 |
/** |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
32 |
@publishedPartner |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
33 |
@prototype |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
34 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
35 |
Idle Timer class. These are a timers which allow the client to specify a window in which |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
36 |
the timer should queue a Dfc. The implementation aligns multiple timers to allow the device |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
37 |
to spend longer periods in low power modes, thus saving power. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
38 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
39 |
NONSHARABLE_CLASS(TIdleTimer) |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
40 |
{ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
41 |
public: |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
42 |
static const TInt KNoTimeout = -1; |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
43 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
44 |
enum TFault |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
45 |
{ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
46 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
47 |
/** |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
48 |
This fault is raised from TIdleTimer::SetDfcQ if an attempt is made to set the Dfc |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
49 |
queue for an Idle Timer where one has already been set. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
50 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
51 |
EDfcQueAlreadySet = 0, |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
52 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
53 |
/** |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
54 |
This fault is raised from TIdleTimer::SetFunciton if an attempt is made to change |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
55 |
the function the Dfc callback should call whilst either a OneShot or Periodic |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
56 |
request is outstanding on the Idle Timer. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
57 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
58 |
ESetFunctionCalledOnPendingTimer = 1, |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
59 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
60 |
/** |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
61 |
This fault is raised if either TIdleTimer::OneShot or TIdleTimer::Periodic is |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
62 |
called but no Dfc queue has been set for the Idle Timer. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
63 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
64 |
ENoDfcQSet = 2 |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
65 |
}; |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
66 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
67 |
public: |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
68 |
/** Idle Timer constructor |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
69 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
70 |
@param aFunction, function to call on completion of the timer |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
71 |
@param aPtr, parameter to be passed to function callback |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
72 |
@param aPriority, priority of DFC within the queue (0 to 7, where 7 is highest) |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
73 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
74 |
IMPORT_C TIdleTimer(TDfcFn aFunction, TAny* aPtr, TInt aPriority); |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
75 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
76 |
/** Idle Timer constructor |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
77 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
78 |
@param aFunction, function to call on completion of the timer |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
79 |
@param aPtr, parameter to be passed to function callback |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
80 |
@param aDfcQ, pointer to a DFC queue on which this Idle Timer should queue |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
81 |
the DFC callback on timer completion. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
82 |
@param aPriority, priority of DFC within the queue (0 to 7, where 7 is highest) |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
83 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
84 |
IMPORT_C TIdleTimer(TDfcFn aFunction, TAny* aPtr, TDfcQue* aDfcQ, TInt aPriority); |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
85 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
86 |
/** Set the Dfc queue on which this Idle Timer should make its Dfc callback on |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
87 |
completion of the timer. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
88 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
89 |
A Dfc queue must be set either with this function or from the TIdleTimer |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
90 |
constructor before the Idle Timer can be used – not doing so will fault the |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
91 |
kernel when the Idle Timer is scheduled. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
92 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
93 |
This function should only be used in the initialization of the Idle Timer, |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
94 |
when it has not previously had a Dfc queue set. This function does not move |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
95 |
the Idle Timer from one queue to another –attempting to do so will fault the kernel. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
96 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
97 |
@param aDfcQ, pointer to a DFC queue on which this Idle Timer should queue |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
98 |
the DFC callback on timer completion. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
99 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
100 |
IMPORT_C void SetDfcQ(TDfcQue* aDfcQ); |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
101 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
102 |
/** Sets the function to be run when the Idle Timer is completed. This function |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
103 |
may only be called when the Idle Timer is not queued - attempting otherwise will |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
104 |
fault the kernel. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
105 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
106 |
@param aDfcFn, The function called when the TIdleTimer expires |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
107 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
108 |
IMPORT_C void SetFunction(TDfcFn aDfcFn); |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
109 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
110 |
/** Starts a one-shot Idle Timer |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
111 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
112 |
The timer will queue a Dfc callback at a time (in nanokernel ticks) between aTime |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
113 |
and aMaxTime after this function is called. The callback will be made to the previously |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
114 |
set DfcFn on the requested DfcQue. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
115 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
116 |
If the default value of KNoTimeout is specified for aMaxTime the Idle Timer will |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
117 |
have no upper bound on when to schedule the DFC callback. As such, if the device was |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
118 |
idle at the time aTime number of ticks after the OneShot request was made, the |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
119 |
Idle Timer will not be completed (i.e. the Dfc callback will not be queued) until the next |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
120 |
occasion the device comes out of idle. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
121 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
122 |
@param aTime the minimum number of nanokernel ticks after which the Dfc callback |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
123 |
is to be be queued. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
124 |
@param aMaxTime the maximum number of nanokernel ticks before which the Dfc |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
125 |
callback must be queued. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
126 |
@return KErrNone if no error, KErrInUse if timer is already active, KErrArgument if |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
127 |
aMaxTime is neither greater than aMinTime nor equal to TIdleTimer::KNoTimeout |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
128 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
129 |
@pre No fast mutex can be held. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
130 |
@pre Kernel must be unlocked. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
131 |
@pre Call in a thread context. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
132 |
@pre Interrupts must be enabled. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
133 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
134 |
@see NKern::TimerTicks() |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
135 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
136 |
IMPORT_C TInt OneShot(TInt aTime, TInt aMaxTime = KNoTimeout); |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
137 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
138 |
/** Starts a periodic Idle Timer |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
139 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
140 |
The timer will queue a DFC callback at a time (in nanokernel ticks) between aTime and aMaxTime |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
141 |
after this function is called, and then at successive intervals somewhere between aTime |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
142 |
and aMaxTime after the previous queuing. The callback will be made to the previously set |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
143 |
DfcFn on the requested DfcQue. Since the callback is queued automatically, the Idle Timer |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
144 |
must be explicitly cancelled after Periodic is called on it before it can safely go out of scope. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
145 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
146 |
If the default value of KNoTimeout is specified for aMaxTime, the Idle Timer will have no |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
147 |
maximum timeout each cycle. In this case, if the device was idle at the minimum expiry time |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
148 |
(aTime + time of previous expiry) queuing of the Dfc will not occur until the next time the |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
149 |
device comes out of idle. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
150 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
151 |
@param aTime – the minimum number of nanokernel ticks from the previous completion |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
152 |
after which the Dfc callback is to be queued. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
153 |
@param aMaxTime – the maximum number of nanokernel ticks after the previous |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
154 |
completion before which the Dfc callback must be queued. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
155 |
@return KErrNone if no error, KErrInUse if timer is already active, KErrArgument if |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
156 |
aMaxTime is neither greater than aMinTime nor equal to TIdleTimer::KNoTimeout |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
157 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
158 |
@pre No fast mutex can be held. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
159 |
@pre Kernel must be unlocked. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
160 |
@pre Call in a thread context. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
161 |
@pre Interrupts must be enabled. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
162 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
163 |
@see NKern::TimerTicks() |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
164 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
165 |
IMPORT_C TInt Periodic(TInt aTime, TInt aMaxTime = KNoTimeout); |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
166 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
167 |
/** Cancels an Idle Timer |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
168 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
169 |
This function does nothing if the Idle Timer is not scheduled. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
170 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
171 |
Note that the implementation of this function is such that, if Cancel is called from a |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
172 |
thread (i.e. DFC queue) other than the one that the callback is to be made on… |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
173 |
• if the callback has started, Cancel will block until the callback has finished |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
174 |
• if the callback hasn’t started, Cancel will ensure that it won’t run after Cancel |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
175 |
has returned |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
176 |
In order to do this, if called from a different thread, the Cancel function blocks the calling |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
177 |
thread on a semaphore until the DFC queue thread used for the callback eventually signals it. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
178 |
Given this, if the callback function somehow reciprocally blocks on the thread that is calling |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
179 |
Cancel, a deadlock could occur. It is up to the client to ensure this doesn’t happen. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
180 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
181 |
To re-iterate - the deadlock scenario described above is only a possibility if Cancel is called |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
182 |
from a different thread (i.e. DFC queue) than that in which the callback is made. If Cancel |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
183 |
is called from the same thread then there’s nothing to worry about in this respect. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
184 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
185 |
@pre No fast mutex can be held. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
186 |
@pre Kernel must be unlocked. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
187 |
@pre Call in a thread context. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
188 |
@pre Interrupts must be enabled. |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
189 |
*/ |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
190 |
IMPORT_C void Cancel(); |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
191 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
192 |
private: |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
193 |
TInt iData[20]; //Reserved space for implementation |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
194 |
}; |
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
195 |
|
bb4b476bbb96
Initial contribution of SHAI APIs from Nokia.
Daniel Rubio <danielr@symbian.org>
parents:
diff
changeset
|
196 |
#endif //IDLETIMER_H |