1 /* |
|
2 * Copyright (c) 2009-2010 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 "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: Interface for fetching/saving the vmbx entries. |
|
15 * Also notify on a number change is supported. |
|
16 * Interface : External, CVoiceMailbox |
|
17 * |
|
18 */ |
|
19 |
|
20 #ifndef C_VOICEMAILBOX_H |
|
21 #define C_VOICEMAILBOX_H |
|
22 |
|
23 // INCLUDES |
|
24 #include <voicemailboxdefs.h> |
|
25 |
|
26 // FORWARD DECLARATIONS |
|
27 class MVoiceMailboxObserver; |
|
28 class CVoiceMailboxImpl; |
|
29 class CVoiceMailboxEntry; |
|
30 |
|
31 /** |
|
32 * Parameter package for Voice Mailbox API operations. |
|
33 * |
|
34 * @lib vmbxengine.lib |
|
35 */ |
|
36 class TVoiceMailboxParams |
|
37 { |
|
38 public: |
|
39 /** |
|
40 * Version of parameter package. |
|
41 */ |
|
42 IMPORT_C TInt Version(); |
|
43 |
|
44 /** |
|
45 * Default constructor. |
|
46 */ |
|
47 IMPORT_C TVoiceMailboxParams(); |
|
48 |
|
49 /** |
|
50 * Constructor for CVoiceMailboxEntry |
|
51 */ |
|
52 IMPORT_C TVoiceMailboxParams( const CVoiceMailboxEntry& aEntry ); |
|
53 |
|
54 public: |
|
55 |
|
56 /** |
|
57 * Mailbox type. |
|
58 */ |
|
59 TVmbxType iType; |
|
60 |
|
61 /** |
|
62 * Mailbox service id. |
|
63 */ |
|
64 TServiceId iServiceId; |
|
65 |
|
66 /** |
|
67 * Mailbox line type. |
|
68 * Initialized to EVmbxAlsLineDefault. |
|
69 */ |
|
70 TVmbxAlsLineType iLineType; |
|
71 |
|
72 protected: |
|
73 |
|
74 /** |
|
75 * TVoiceMailboxParams package version. |
|
76 */ |
|
77 TInt iVersion; |
|
78 |
|
79 }; |
|
80 |
|
81 /** |
|
82 * CVoiceMailbox offers an interface for fetching and saving |
|
83 * voice mailbox entries. |
|
84 * The API offers also services for querying a new number or to |
|
85 * change an existing one. |
|
86 * |
|
87 * @code |
|
88 * |
|
89 * In this example user selects type of a mailbox to use. Then number |
|
90 * of selected mailbox is fetched. If number wasn't set, then user |
|
91 * is queried to enter a number for the selected mailbox. |
|
92 * |
|
93 * // Creates instance of CVoiceMailbox |
|
94 * CVoiceMailbox* voicemailbox = CVoiceMailbox::NewLC(); |
|
95 * |
|
96 * // Selected mailbox type |
|
97 * TVoiceMailboxParams vmbxParams; |
|
98 * |
|
99 * //Launch type selection query |
|
100 * TInt error = voicemailbox->QueryVmbxType( vmbxParams ); |
|
101 * |
|
102 * CVoiceMailboxEntry* vmbxEntry = NULL; |
|
103 * |
|
104 * if ( KErrNone == error ) |
|
105 * { |
|
106 * if ( KErrNone == |
|
107 * voicemailbox->GetStoredEntry( vmbxParams, vmbxEntry ) ) |
|
108 * { |
|
109 * // Number retrieved succesfully, do appropriate tasks, e.g.: |
|
110 * TPtrC ptrNumber( KNullDesC ); |
|
111 * TInt numError = vmbxEntry->GetVmbxNumber( ptrNumber ); |
|
112 * if ( KErrNone == numError && ptrNumber.Length() ) |
|
113 * { |
|
114 * // Do appropriate tasks, e.g dial a call. |
|
115 * } |
|
116 * } |
|
117 * } |
|
118 * else if ( KErrNotFound == error ) |
|
119 * { |
|
120 * // No number defined, query new entry from user |
|
121 * error = voicemailbox->QueryNewEntry( vmbxParams, vmbxEntry ); |
|
122 * if ( KErrNone == error ) |
|
123 * { |
|
124 * // Do appropriate tasks, e.g. save and dial a call. |
|
125 * error = voicemailbox->SaveEntry( *vmbxEntry ); |
|
126 * // For example get the number/address using |
|
127 * // vmbxEntry->GetVmbxNumber() and then dial a call |
|
128 * } |
|
129 * // else: problem getting the new number/address, e.g. skip |
|
130 * } |
|
131 * |
|
132 * else |
|
133 * { |
|
134 * // User cancelled or no supported mailboxes configured |
|
135 * } |
|
136 * |
|
137 * delete vmbxEntry; // Entry ownership was transferred |
|
138 * vmbxEntry = NULL; |
|
139 * CleanupStack::PopAndDestroy( voicemailbox ); |
|
140 * voicemailbox = NULL; |
|
141 * @endcode |
|
142 * |
|
143 * @lib vmbxengine.lib |
|
144 * @since S60 v5.2 |
|
145 */ |
|
146 |
|
147 class CVoiceMailbox : public CBase |
|
148 { |
|
149 public: |
|
150 |
|
151 /** |
|
152 * Static constructor. |
|
153 * @return New instance of the object. Ownership transferred. |
|
154 */ |
|
155 IMPORT_C static CVoiceMailbox* NewL(); |
|
156 |
|
157 /** |
|
158 * Static constructor. |
|
159 * @return New instance of the object. Ownership transferred. |
|
160 */ |
|
161 IMPORT_C static CVoiceMailbox* NewLC(); |
|
162 |
|
163 /** |
|
164 * Destructor. |
|
165 */ |
|
166 virtual ~CVoiceMailbox(); |
|
167 |
|
168 public: |
|
169 |
|
170 /** |
|
171 * Retrieves voice mailbox entry for the specified service. |
|
172 * |
|
173 * @param in Params Service id and type of the mailbox for which |
|
174 * a number/address should be defined. |
|
175 * @param out aEntry If successful, a new result container is |
|
176 * created and ownership passed to the caller. |
|
177 * @return - KErrNone if an entry is found. |
|
178 * - KErrNotFound if no entry available |
|
179 * - KErrArgument when illegal argument |
|
180 * - Other system wide errors. |
|
181 */ |
|
182 IMPORT_C virtual TInt GetStoredEntry( |
|
183 const TVoiceMailboxParams& aParams, |
|
184 CVoiceMailboxEntry*& aEntry ) const; |
|
185 |
|
186 /** |
|
187 * Saves the vmbx entry to its storage. |
|
188 * |
|
189 * Some mailbox types may not support saving all arguments. |
|
190 * In that case unsupported arguments are ignored. |
|
191 * This method may display related UI notes or queries. |
|
192 * |
|
193 * @param in aEntry The vmbx entry to save. |
|
194 * @return - KErrNone if the entry was saved |
|
195 * - KErrNotSupported if not capable or allowed to execute this |
|
196 * for the specified mailbox service. |
|
197 * - KErrArgument When illegal argument was passed. |
|
198 * - Other system wide errors. |
|
199 */ |
|
200 IMPORT_C virtual TInt SaveEntry( const CVoiceMailboxEntry& aEntry ); |
|
201 |
|
202 /** |
|
203 * Displays a query asking the user to define a mailbox number/address. |
|
204 * Returns the input which the user entered, but does not save it. |
|
205 * For that caller has to use SaveEntry(). |
|
206 * This method may display related UI notes or queries. |
|
207 * |
|
208 * If editing for the specified mailbox service is not allowed, |
|
209 * this method displays an error note and returns an error. |
|
210 * If client is interested, CheckConfiguration() |
|
211 * can be used to check permissions. |
|
212 * |
|
213 * |
|
214 * @param in aParams Service id and type of the mailbox for which |
|
215 * a number/address should be defined. |
|
216 * @param out aEntry If successful, a new result container is |
|
217 * created and ownership passed to the caller. |
|
218 * @return - KErrNone if the number was entered. |
|
219 * - KErrNotFound if the number is not defined |
|
220 * (user entered no number or selected Cancel) |
|
221 * - KErrArgument When illegal argument. |
|
222 * - KErrNotSupported if not capable or allowed to execute this |
|
223 * for the specified mailbox. |
|
224 * - Other system wide errors. |
|
225 */ |
|
226 IMPORT_C virtual TInt QueryNewEntry( |
|
227 const TVoiceMailboxParams& aParams, |
|
228 CVoiceMailboxEntry*& aEntry ); |
|
229 |
|
230 /** |
|
231 * Displays a query asking the user to change a mailbox number/address. |
|
232 * Returns the input from user, but does not save it. |
|
233 * For that caller has to use SaveEntry(). |
|
234 * |
|
235 * If editing for the specified mailbox service is not allowed, |
|
236 * this method displays an error note and returns an error. |
|
237 * If client is interested, CheckConfiguration() |
|
238 * can be used to check permissions. |
|
239 * |
|
240 * @param in aParams Service id and type of the mailbox. |
|
241 * @param out aEntry If successful, a new result container is |
|
242 * created and ownership passed to the caller. |
|
243 * @return - KErrNone if the number was entered. |
|
244 * aNumber will contain the vmbx number. |
|
245 * - KErrCancel If the user selected Cancel. |
|
246 * - KErrArgument When illegal argument. |
|
247 * - KErrNotSupported if not capable or allowed to execute this |
|
248 * for the specified mailbox. |
|
249 * - Other system wide errors. |
|
250 */ |
|
251 IMPORT_C virtual TInt QueryChangeEntry( |
|
252 const TVoiceMailboxParams& aParams, CVoiceMailboxEntry*& aEntry ); |
|
253 |
|
254 /** |
|
255 * Displays a query on the screen asking the user to select a |
|
256 * Voice Mailbox service. |
|
257 * |
|
258 * @param out aParams If successful, |
|
259 * contains selected mailbox info. |
|
260 * @return - KErrNone if successful. |
|
261 * - KErrCancel if user selected Cancel |
|
262 * - KErrNotFound if there is no defined voice number and |
|
263 * user have selected the type to define or the default |
|
264 * type given. |
|
265 * - Other system wide errors. |
|
266 */ |
|
267 IMPORT_C virtual TInt QueryVmbxType( |
|
268 TVoiceMailboxParams& aParams ); |
|
269 |
|
270 /** |
|
271 * Issues a notify request on a vmbx number/address change. |
|
272 * |
|
273 * The observer callback will be called whenever any vmbx number/address |
|
274 * has changed on those mailboxes which support observing. |
|
275 * |
|
276 * Only one notify request can be pending. Method will leave with KErrInUse |
|
277 * if a second request is issued while one is active already. |
|
278 * Leaves if the notify request could not be served. |
|
279 * |
|
280 * @param in aObserver The observer for the notification. |
|
281 * @param in aNotifyOnActiveLineOnly if this is ETrue, notify events will |
|
282 * be generated only if the vmbx number of the active ALS line is |
|
283 * changed, not if the number of the other line is changed. When |
|
284 * there is no ALS support, this has no effect ie. notification |
|
285 * will be generated always. |
|
286 */ |
|
287 IMPORT_C virtual void NotifyVmbxNumberChangeL( |
|
288 MVoiceMailboxObserver& aObserver, |
|
289 const TBool aNotifyOnActiveLineOnly ); |
|
290 |
|
291 /** |
|
292 * Cancels a notify request on a vmbx number change. |
|
293 * |
|
294 */ |
|
295 IMPORT_C virtual void NotifyVmbxNumberChangeCancel(); |
|
296 |
|
297 /** |
|
298 * Checks the Voice Mailbox configuration to find out if a features |
|
299 * are disabled or enabled. |
|
300 * |
|
301 * @param in aParams Specifies which mailbox capabilities, |
|
302 * the caller wants to check. |
|
303 * @param in aFlags Use TVmbxFeatureCapabilityFlag values |
|
304 * for this parameter. |
|
305 * Specifies what features client wants to check. |
|
306 |
|
307 * @return True if feature(s) enabled. |
|
308 */ |
|
309 IMPORT_C virtual TBool CheckConfiguration( |
|
310 const TVoiceMailboxParams& aParams, |
|
311 const TInt aFlags ); |
|
312 |
|
313 |
|
314 /** |
|
315 * Checks the Voice Mailbox how many VoIP service Ids |
|
316 * |
|
317 * @param out aProfileIds |
|
318 * @return KErrNone if get service Ids successfully. |
|
319 */ |
|
320 IMPORT_C virtual TInt GetServiceIds( RIdArray& aProfileIds ) const; |
|
321 |
|
322 /** |
|
323 * Saves provisioned entry to corresponding storage. |
|
324 * |
|
325 * Some mailbox types may not support saving all arguments. |
|
326 * In that case unsupported arguments are ignored. |
|
327 * |
|
328 * @param in aEntry The provisioned vmbx entry to save. |
|
329 * @return - KErrNone if the entry was saved |
|
330 * - KErrNotSupported if not capable or allowed to execute this |
|
331 * for the specified mailbox service. |
|
332 * - KErrArgument When illegal argument was passed. |
|
333 * - Other system wide errors. |
|
334 */ |
|
335 IMPORT_C TInt SaveProvisionedEntry( const CVoiceMailboxEntry& aEntry ); |
|
336 |
|
337 protected: |
|
338 |
|
339 /** |
|
340 * Second phase constructor. |
|
341 * |
|
342 */ |
|
343 void ConstructL(); |
|
344 |
|
345 /** |
|
346 * Default constructor. |
|
347 * |
|
348 */ |
|
349 CVoiceMailbox(); |
|
350 |
|
351 private: // data |
|
352 |
|
353 /** |
|
354 * Implementation of the client API. |
|
355 * Own. |
|
356 **/ |
|
357 CVoiceMailboxImpl* iBody; |
|
358 }; |
|
359 |
|
360 #endif // C_VOICEMAILBOX_H |
|