|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-87CD8C58-F6B9-5D6B-9D7B-862979DE3B6F" xml:lang="en"><title>Notification |
|
13 Request Tutorial</title><shortdesc>This tutorial describes how to receive notification of the events |
|
14 with the telephony API for applications. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
15 |
|
16 |
|
17 <context id="GUID-1EA31B19-BBB0-5723-9896-66666FEABC1D"><p> <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony</apiname></xref> can |
|
18 notify the client applications about the status changes to the events like: </p> <ul> |
|
19 <li id="GUID-180B5C84-9ECB-55FE-8B9E-E84ED56C32A3"><p>to detect inbound calls </p> </li> |
|
20 <li id="GUID-8305981A-F9B6-52EC-97F1-CF74C0238315"><p>to detect the phone |
|
21 charger connection </p> </li> |
|
22 <li id="GUID-F0140C6D-2A85-587B-91BB-C432918518AF"><p>battery charge information </p> </li> |
|
23 </ul> <p>The client applications can get the notification of the events that |
|
24 contain a <b>notification event</b>, an <b>information class</b> and a <b>cancellation |
|
25 code</b>. For example, the <xref href="GUID-0DA6722B-0700-5612-884A-F3B7733E5252.dita">Voice |
|
26 Line Status</xref> event describes that the client applications can receive |
|
27 the notification when it changes. The event description contains: </p> <table id="GUID-603AF473-FC6E-52FE-A2B7-CA4211A0D9BF"> |
|
28 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
29 <thead> |
|
30 <row> |
|
31 <entry>Item</entry> |
|
32 <entry>Description</entry> |
|
33 </row> |
|
34 </thead> |
|
35 <tbody> |
|
36 <row> |
|
37 <entry><p> <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::EVoiceLineStatusChange</apiname></xref> </p> </entry> |
|
38 <entry><p>notification event </p> </entry> |
|
39 </row> |
|
40 <row> |
|
41 <entry><p> <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::TCallStatus</apiname></xref> </p> </entry> |
|
42 <entry><p>information class </p> </entry> |
|
43 </row> |
|
44 <row> |
|
45 <entry><p> <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::EVoiceLineStatusChangeCancel</apiname></xref> </p> </entry> |
|
46 <entry><p>cancellation code </p> </entry> |
|
47 </row> |
|
48 </tbody> |
|
49 </tgroup> |
|
50 </table> </context> |
|
51 <steps id="GUID-0A66184A-7434-5CA1-B4A6-D07BB52AB6A9"> |
|
52 <step id="GUID-78BA430F-A345-52AC-833A-FE170FEAF79A"><cmd/> |
|
53 <info>create an instance of <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony</apiname></xref> </info> |
|
54 <stepxmp><codeblock id="GUID-8E9E0D08-7AB5-537F-880E-8342F38BA6C4" xml:space="preserve">CTelephony* telephonyApi = CTelephony::NewL(); |
|
55 CleanupStack::PushL( telephonyApi );</codeblock> </stepxmp> |
|
56 </step> |
|
57 <step id="GUID-570A8873-7F1E-5569-9791-9F530FE03520"><cmd/> |
|
58 <info>create an instance of the class, passing it the pointer to <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony</apiname></xref> </info> |
|
59 <stepxmp><codeblock id="GUID-901E03A3-028E-5B2D-B336-3CD1E309F692" xml:space="preserve">CNotifyExample *exampleObject = new CNotifyExample( telephonyApi ); |
|
60 CleanupStack::PushL( exampleObject );</codeblock> </stepxmp> |
|
61 </step> |
|
62 <step id="GUID-CC391D40-F006-5874-95EF-36683EE2180B"><cmd/> |
|
63 <info>call the object's <codeph>RequestNotification</codeph> method to start |
|
64 the request. This calls <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::NotifyChange()</apiname></xref> </info> |
|
65 <stepxmp><codeblock id="GUID-EFC8D54E-B490-5E5E-A742-8E0796CA48BE" xml:space="preserve">exampleObject->RequestNotification();</codeblock> </stepxmp> |
|
66 <info>pass the notification event and an empty instance of the information |
|
67 class. This method starts an asynchronous operation that completes when the |
|
68 requested notification event occurs </info> |
|
69 <info>The new status will have been written into the <codeph>TCallStatus</codeph> object |
|
70 that was given to <codeph>NotifyChange()</codeph> </info> |
|
71 </step> |
|
72 <step id="GUID-34EEDBDE-BA17-5261-8B22-222AAA95D3E2"><cmd/> |
|
73 <info>you can see all the notification events in <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::TNotificationEvent</apiname></xref>. |
|
74 This also shows which information class is associated with each event </info> |
|
75 </step> |
|
76 <step id="GUID-BC613CF8-E088-55CF-A721-420B6ADC70FD"><cmd/> |
|
77 <info>you can cancel a request for notification any time before the operation |
|
78 finished. Do this by passing <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::CancelAsync()</apiname></xref> the |
|
79 cancellation code </info> |
|
80 <info><p><note> You should not request notification before the previous notification |
|
81 request is either completed or cancelled. The notification request is started |
|
82 after the active object is created, so there could not be a request. If you |
|
83 are <bold>not</bold> sure that previous requests for that object have |
|
84 completed, call the<xref href="GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F.dita#GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F/GUID-0BEA3D01-369A-3ED4-A8DB-22D3B1A11C97"><apiname>CActive::Cancel</apiname></xref> method before issuing |
|
85 a new request:<codeblock xml:space="preserve">exampleObject->Cancel();exampleObject->RequestNotification();</codeblock> |
|
86 This will cancel any previous requests.</note></p></info> |
|
87 </step> |
|
88 </steps> |
|
89 <example id="GUID-6366AAAA-6C55-517C-B702-420730097399"><title>Voice line |
|
90 status example</title> <p>Here is an active object that detects a change in |
|
91 voice line status. It doesn't do much when the voice line status changes; |
|
92 it simply stores the new status values and then starts the next asynchronous |
|
93 operation. </p> <p>This is a basic <xref href="GUID-890F06C6-DE32-5EB1-BF0F-D41794F47AE1.dita">Active |
|
94 Object</xref>. You will need to know about active objects in order to use <codeph>CTelephony</codeph>'s |
|
95 notification abilities. </p> <codeblock id="GUID-86411553-8C98-5D4E-BBC5-5F7F3C8D8D91" xml:space="preserve"> |
|
96 /* |
|
97 Example CTelephony Notification |
|
98 |
|
99 This class uses the CTelephony API to get notification when a |
|
100 phone's voice line status changes. |
|
101 |
|
102 This class is an active object. You will need to have knowledge of |
|
103 active objects in order to understand this class. All active |
|
104 object are derived from CActive. |
|
105 |
|
106 This program can be easily modified to get notification when other |
|
107 events occur. |
|
108 |
|
109 See CTelephony::TNotificationEvent for a list of |
|
110 events. |
|
111 |
|
112 */ |
|
113 |
|
114 #include <e32base.h> |
|
115 #include <Etel3rdParty.h> |
|
116 |
|
117 class CNotifyExample : public CActive |
|
118 { |
|
119 |
|
120 public: |
|
121 // Constructor/Destructor |
|
122 CNotifyExample( CTelephony* aTelephony ); |
|
123 |
|
124 // Request voice line status change notification |
|
125 void RequestNotification(); |
|
126 |
|
127 private: |
|
128 /* |
|
129 These are the pure virtual methods from CActive that |
|
130 MUST be implemented by all active objects |
|
131 */ |
|
132 void RunL(); |
|
133 void DoCancel(); |
|
134 |
|
135 private: |
|
136 /* |
|
137 A reference to a CTelephony, obtained with CTelephony::NewL() |
|
138 or NewLC() |
|
139 */ |
|
140 CTelephony* iTelephony; |
|
141 |
|
142 /* |
|
143 When the voice line status changes (and hence the asynchronous |
|
144 operation completes) the new voice line status is written into |
|
145 iLineStatus. Until this point, iLineStatus is not valid. |
|
146 |
|
147 If you change this class to get notification of other events, |
|
148 then change this class. CTelephony::TNotificationEvent lists |
|
149 the classes associated with each event. |
|
150 */ |
|
151 CTelephony::TCallStatusV1 iLineStatus; |
|
152 CTelephony::TCallStatusV1Pckg iLineStatusPckg; |
|
153 }; |
|
154 |
|
155 |
|
156 |
|
157 |
|
158 /* |
|
159 Default constructor. Pass it a reference to a CTelephony, created |
|
160 with CTelephony::NewL() or NewLC() |
|
161 */ |
|
162 CNotifyExample::CNotifyExample(CTelephony* aTelephony): CActive( EPriorityStandard ), iTelephony( aTelephony ), iLineStatusPckg( iLineStatus ) |
|
163 { |
|
164 //default constructor |
|
165 iLineStatus.iStatus = CTelephony::EStatusUnknown; |
|
166 } |
|
167 |
|
168 |
|
169 |
|
170 /* |
|
171 This method requests notification by calling |
|
172 CTelephony::NotifyChange() to initialise an asynchronous operation. |
|
173 Then it immediately calls CActive::SetActive to start the |
|
174 operation. The operation completes when the notification event |
|
175 occurs. |
|
176 |
|
177 In this case, we tell CTelephony to wait for the |
|
178 CTelephony::EVoiceLineStatusChange notification event, hence the |
|
179 event occurs when the voice line status changes. |
|
180 |
|
181 For other events, change the notification event in the call to |
|
182 CTelephony::NotifyChange(). The CTelephony::TNotificationEvent |
|
183 description all the notification events. |
|
184 It also list the information class to |
|
185 pass to CTelephony::NotifyChange(). The TCallStatus |
|
186 class is associated with CTelephony::EVoiceLineStatusChange. |
|
187 */ |
|
188 void CNotifyExample::RequestNotification() |
|
189 { |
|
190 |
|
191 /* |
|
192 Panic if this object is already performing an asynchronous |
|
193 operation |
|
194 */ |
|
195 _LIT( KNotifyExamplePanic, "CNotifyExample" ); |
|
196 __ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic, 1 )); |
|
197 |
|
198 iTelephony->NotifyChange( iStatus, CTelephony::EVoiceLineStatusChange, iLineStatusPckg ); |
|
199 SetActive(); |
|
200 } |
|
201 |
|
202 |
|
203 /* |
|
204 The active object's RunL method is called when the asynchronous |
|
205 event completes. In this case, RunL is called when the voice line |
|
206 status changes. When this occurs, the new voice line status is |
|
207 written to the iLineStatus. iLineStatus was passed to |
|
208 CTelephony::NotifyChange() when the asynchronous operation was |
|
209 started. |
|
210 |
|
211 This is where you put your code to respond to your chosen |
|
212 notification event. |
|
213 |
|
214 In all active objects, iStatus indicates whether the asynchronous |
|
215 operation succeeded, failed, or is still in progress. KErrNone |
|
216 indicates success, and hence the value in iStatus is valid. |
|
217 */ |
|
218 void CNotifyExample::RunL() |
|
219 { |
|
220 if( iStatus==KErrNone ) |
|
221 { |
|
222 /* |
|
223 Insert code to respond to the change of voice line status |
|
224 here. A typical use to answer a call if the voice line |
|
225 status is 'ringing' (EStatusRinging) |
|
226 |
|
227 Remember that you must implement a RunError() method if |
|
228 your code in RunL can leave. |
|
229 */ |
|
230 if( iLineStatus.iStatus == CTelephony::EStatusRinging ); // Answer call by calling 'AnswerIncomingCall()' |
|
231 { |
|
232 /* Request the next notification */ |
|
233 iTelephony->NotifyChange( iStatus, CTelephony::ESignalStrengthChange, iLineStatusPckg ); |
|
234 SetActive(); |
|
235 } |
|
236 } |
|
237 } |
|
238 |
|
239 /* |
|
240 Like all active objects, you must supply a DoCancel() method to |
|
241 cancel the asynchronous operation. This must cancel a CTelephony |
|
242 notification operation with CTelephony::CancelAsync. Give the method |
|
243 the appropriate 'cancellation event' from those in 'TCancellationRequest' |
|
244 |
|
245 In this case, we are cancelling the "voice line status Change" event, |
|
246 and so we need to supply the EVoiceLineStatusChange cancellation code. |
|
247 If you change this class to respond to a different notification |
|
248 event, remember to change the call to CTelephony::CancelAsync. |
|
249 */ |
|
250 |
|
251 void CNotifyExample::DoCancel() |
|
252 { |
|
253 iTelephony->CancelAsync( CTelephony::EVoiceLineStatusChangeCancel ); |
|
254 } </codeblock> </example> |
|
255 <postreq id="GUID-CD5428AA-DCE8-5BEA-AEC4-7A159853EF76"><p><b>Receive notification of other events </b> </p> <p>The previous examples |
|
256 detect changes in voice line status. You can adapt this example for other |
|
257 events as follows: </p> <ul> |
|
258 <li id="GUID-BC170E42-C666-5882-AA89-13804DC9B28E"><p>In the <codeph>RequestNotification()</codeph> method, |
|
259 pass <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::NotifyChange()</apiname></xref> the <b>notification |
|
260 event</b> you want to detect, listed in <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::TNotificationEvent</apiname></xref>. |
|
261 Each event has an <b>information class</b> associated with it, which stores |
|
262 the new information after it has changed. Pass <codeph>NotifyChange()</codeph> an |
|
263 instance of the information class, too: </p> <codeblock id="GUID-D7A25EFA-D6C0-5EE3-965E-795F6DD99FF6" xml:space="preserve">CNotifyExample::RequestNotification() |
|
264 { |
|
265 _LIT( KNotifyExamplePanic, "CNotifyExample" ); |
|
266 __ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic, 1 )); |
|
267 |
|
268 iTelephony->NotifyChange( iStatus, |
|
269 ---Insert notification event--- |
|
270 ---Insert packaged information class instance--- ); |
|
271 SetActive(); |
|
272 }</codeblock> <p>You will need to declare the information class instance |
|
273 in the <codeph>CNotifyExample</codeph>'s declaration. </p> </li> |
|
274 <li id="GUID-FE3772D6-9624-528F-BDDD-0B474466CB0E"><p>Change the code in <codeph>CNotifyExample::RunL</codeph> that |
|
275 handles the event. </p> </li> |
|
276 <li id="GUID-F104AF0D-D6AC-5052-9A96-010B49D5C600"><p>Change the <codeph>DoCancel</codeph> method |
|
277 to cancel the correct event. Insert the correct <b>cancellation code</b> from |
|
278 those in <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::TCancellationRequest</apiname></xref>: </p> <codeblock id="GUID-2E58B2CD-BC95-5C79-86D9-0EC6EA81C9AF" xml:space="preserve">CNotifyExample::DoCancel() |
|
279 { |
|
280 iTelephony->CancelAsync(---Insert cancellation code--- ); |
|
281 }</codeblock> </li> |
|
282 </ul> </postreq> |
|
283 </taskbody></task> |