|
1 // Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #include <calsession.h> |
|
17 |
|
18 #include "calsessionimpl.h" |
|
19 |
|
20 CCalSession::CCalSession() |
|
21 { |
|
22 } |
|
23 |
|
24 void CCalSession::ConstructL() |
|
25 { |
|
26 iImpl = CCalSessionImpl::NewL(); |
|
27 } |
|
28 |
|
29 CCalSessionImpl& CCalSession::Impl() const |
|
30 { |
|
31 return *iImpl; |
|
32 } |
|
33 |
|
34 /** Allocates and constructs a session to the Calendar server. |
|
35 @publishedAll |
|
36 @released |
|
37 @capability None |
|
38 |
|
39 @return Pointer to the newly created session. |
|
40 */ |
|
41 EXPORT_C CCalSession* CCalSession::NewL() |
|
42 { |
|
43 CCalSession* self = new (ELeave) CCalSession(); |
|
44 CleanupStack::PushL(self); |
|
45 self->ConstructL(); |
|
46 CleanupStack::Pop(self); |
|
47 return self; |
|
48 } |
|
49 |
|
50 /** Destructor for the session. Clear away any resources. |
|
51 @publishedAll |
|
52 @released |
|
53 @capability None |
|
54 */ |
|
55 EXPORT_C CCalSession::~CCalSession() |
|
56 { |
|
57 delete iImpl; |
|
58 } |
|
59 |
|
60 /** Creates a new calendar file. |
|
61 @leave KErrNotReady If the calendar file is on a drive where the media has been removed. |
|
62 @publishedAll |
|
63 @released |
|
64 @capability WriteUserData |
|
65 |
|
66 @param aFileName The name of the file to create. This is a combination of drive letter |
|
67 and file name, in other words, DriveLetter:FileName, but not a full path. |
|
68 |
|
69 It leaves if the file with the name specified already exists. |
|
70 */ |
|
71 EXPORT_C void CCalSession::CreateCalFileL(const TDesC& aFileName) const |
|
72 { |
|
73 iImpl->CreateCalFileL(aFileName); |
|
74 } |
|
75 |
|
76 /** Creates a new calendar file. |
|
77 @leave KErrNotReady If the calendar file is on a drive where the media has been removed. |
|
78 @publishedAll |
|
79 @released |
|
80 @capability WriteUserData |
|
81 |
|
82 @param aFileName The name of the file to create. This is a combination of drive letter |
|
83 and file name, in other words, DriveLetter:FileName, but not a full path. |
|
84 |
|
85 @param aCalendarInfo The calendar info to set on the file. |
|
86 |
|
87 It leaves if the file with the name specified already exists. |
|
88 */ |
|
89 EXPORT_C void CCalSession::CreateCalFileL(const TDesC& aFileName, const CCalCalendarInfo& aCalendarInfo) const |
|
90 { |
|
91 iImpl->CreateCalFileL(aFileName, aCalendarInfo); |
|
92 } |
|
93 |
|
94 /** Set calendar info on the currently open calendar file. |
|
95 @leave KErrNotReady If there is no calendar file open on this CCalSession. |
|
96 @publishedAll |
|
97 @released |
|
98 @capability WriteUserData |
|
99 |
|
100 @param aCalendarInfo The calendar info to set on the file. |
|
101 */ |
|
102 EXPORT_C void CCalSession::SetCalendarInfoL(const CCalCalendarInfo& aCalendarInfo) const |
|
103 { |
|
104 iImpl->SetCalendarInfoL(aCalendarInfo); |
|
105 } |
|
106 |
|
107 /** Get calendar info on the currently open calendar file. |
|
108 @leave KErrNotReady If there is no calendar file open on this CCalSession. |
|
109 @publishedAll |
|
110 @released |
|
111 @capability ReadUserData |
|
112 |
|
113 @return The calendar file's calendar info. If none has been set on the |
|
114 file, CCalCalendarInfo::IsValid will return EFalse. |
|
115 */ |
|
116 EXPORT_C CCalCalendarInfo* CCalSession::CalendarInfoL() const |
|
117 { |
|
118 return iImpl->CalendarInfoL(); |
|
119 } |
|
120 |
|
121 /** Opens an calendar file using the server. |
|
122 |
|
123 If another agenda file is open in the same server session, it is closed. |
|
124 @publishedAll |
|
125 @released |
|
126 @capability ReadUserData |
|
127 |
|
128 @leave KErrEof If the calendar file is corrupt and cannot be opened because an unexpected end of file was reached. |
|
129 @leave KErrInUse If there is an undeleted view, entry or instance from the file opened with this calendar session. |
|
130 These must all be deleted before a new file can be opened. |
|
131 @leave KErrNotFound If the file has not been created. Call CCalSession::CreateCalFileL to create the file. |
|
132 @leave KErrCorrupt If the calendar file is corrupt and cannot be opened. |
|
133 @leave KErrNotSupported If the file name is not specified in the format DriveLetter:FileName. |
|
134 @leave KErrNotSupported If the file is not a supported version. The parameter aFileSupportStatus will be set to EUnsupportedFileVersion in this case. |
|
135 @leave KErrNotReady If the calendar file is on a drive where the media has been removed. |
|
136 |
|
137 @param aFileName The agenda file to open. This is a combination of drive letter |
|
138 and file name, in other words, DriveLetter:FileName, but not a full path. It |
|
139 leaves if a path is included explicitly. A default file is opened if aFileName is KNullDesC. |
|
140 */ |
|
141 EXPORT_C void CCalSession::OpenL(const TDesC& aFileName) const |
|
142 { |
|
143 CalCommon::TCalFileVersionSupport status; |
|
144 iImpl->OpenL(aFileName,status); |
|
145 } |
|
146 |
|
147 /** Opens a calendar file using the server. |
|
148 |
|
149 If another calendar file is open in the same server session, it is closed. |
|
150 @param aFileName The agenda file to open. This is a combination of drive letter and file name, |
|
151 in other words, DriveLetter:FileName, but not a full path. The default file is opened if aFileName is KNullDesC. |
|
152 @param aFileSupportStatus On return indicates whether or not the calendar file needs to be converted from an |
|
153 older version. File conversion takes place when opening the first instance view or entry view. |
|
154 |
|
155 @leave KErrEof If the calendar file is corrupt and cannot be opened because an unexpected end of file was reached. |
|
156 @leave KErrInUse If there is an undeleted view, entry or instance from the file opened with this calendar session. |
|
157 These must all be deleted before a new file can be opened. |
|
158 @leave KErrNotFound If the file has not been created. Call CCalSession::CreateCalFileL to create the file. |
|
159 @leave KErrCorrupt If the calendar file is corrupt and cannot be opened. |
|
160 @leave KErrNotSupported If the file name is not specified in the format DriveLetter:FileName. |
|
161 @leave KErrNotSupported If the file is not a supported version. The parameter aFileSupportStatus will be set to EUnsupportedFileVersion in this case. |
|
162 @leave KErrNotReady If the calendar file is on a drive where the media has been removed. |
|
163 Otherwise one of the system wide error codes. |
|
164 |
|
165 @pre The file to be opened has been created. |
|
166 @post The file has been opened and it is now possible to build an entry view or instance view. If the file requires conversion, the |
|
167 conversion will take place while building the view. |
|
168 @publishedPartner |
|
169 @released |
|
170 @capability ReadUserData |
|
171 */ |
|
172 EXPORT_C void CCalSession::OpenL(const TDesC& aFileName, CalCommon::TCalFileVersionSupport& aFileSupportStatus) const |
|
173 { |
|
174 iImpl->OpenL(aFileName, aFileSupportStatus); |
|
175 } |
|
176 |
|
177 /** |
|
178 Gets the name of the default calendar file held by the server. |
|
179 @publishedAll |
|
180 @released |
|
181 @capability None |
|
182 |
|
183 @return The default filename. This is a combination of a drive letter and a file name, in other |
|
184 words, DriveLetter:FileName but not a full path. |
|
185 */ |
|
186 EXPORT_C const TDesC& CCalSession::DefaultFileNameL() const |
|
187 { |
|
188 return iImpl->DefaultFileNameL(); |
|
189 } |
|
190 |
|
191 /** Deletes a calendar file with the supplied filename. |
|
192 If the file is opened, it will be closed first |
|
193 |
|
194 This also deletes all calendar attachment files referenced from this calendar store - these are the |
|
195 ones moved when the calendar has taken ownership of the file through the CCalAttachment::NewL APIs. |
|
196 Attachment files stored on a different drive to the calendar file will not be deleted. |
|
197 |
|
198 @publishedAll |
|
199 @released |
|
200 |
|
201 @capability WriteUserData |
|
202 @param aFileName The combination of drive letter and file name, in other |
|
203 words, DriveLetter:FileName, but not a full path |
|
204 |
|
205 @leave KErrNotSupported aFileName includes a path explicitly. |
|
206 @leave KErrNotFound The agenda file has not been found. |
|
207 @leave KErrBadArgument The length of aFileName is zero. |
|
208 @leave KErrInUse One of the attachment file handles from this calendar store is still open. |
|
209 @leave KErrNotReady If the calendar file is on a drive where the media has been removed. |
|
210 */ |
|
211 EXPORT_C void CCalSession::DeleteCalFileL(const TDesC& aFileName) const |
|
212 { |
|
213 iImpl->DeleteCalFileL(aFileName); |
|
214 } |
|
215 |
|
216 /** Gets a list of all calendar files held by the server. |
|
217 The caller takes ownership of the returned descriptor array. |
|
218 @publishedAll |
|
219 @released |
|
220 @capability None |
|
221 |
|
222 @return A list of filenames of the Agenda files held by the server. |
|
223 This is NULL if no file has been found. |
|
224 |
|
225 Note that: |
|
226 - The calendar files can be stored on any drive. |
|
227 - Since the directories are not seen by clients, the filenames returned are a |
|
228 combination of drive letter and file name, in other words DriveLetter:FileName |
|
229 - The files are ordered alphabetically by drive letter. Files on the same drive |
|
230 are ordered by filename, for instance a:agenda, c:agenda, c:calendar, d:agenda, d:calendar. |
|
231 */ |
|
232 EXPORT_C CDesCArray* CCalSession::ListCalFilesL() const |
|
233 { |
|
234 return iImpl->ListCalFilesL(); |
|
235 } |
|
236 |
|
237 /** Start notification of any changes to calendar entries. |
|
238 These changes can be filtered, and when a change occurs the MCalChangeCallBack callback function is called |
|
239 with the type of entry which has changed (event or todo). |
|
240 |
|
241 @param aCallBack The class to notify when a change occurs. |
|
242 @param aChangeEntryType Filter notifications to only notify on entries of the specified type (event/todo/all). |
|
243 @param aIncludeUndatedTodos Filter notifications to include undated todos. |
|
244 @param aFilterStartTime Filter notification to only include entries that are wholly or partly covered by a time range. |
|
245 This specifies the start time of the time range. |
|
246 @param aFilterEndTime Filter notification to only include entries that are wholly or partly covered by a time range. |
|
247 This specifies the end time of the time range. |
|
248 @publishedAll |
|
249 @deprecated |
|
250 @capability None |
|
251 */ |
|
252 EXPORT_C void CCalSession::StartChangeNotification(MCalChangeCallBack* aCallBack, MCalChangeCallBack::TChangeEntryType aChangeEntryType, TBool aIncludeUndatedTodos, TTime aFilterStartTime, TTime aFilterEndTime) |
|
253 { |
|
254 TRAP_IGNORE(iImpl->StartChangeNotificationL(aCallBack, aChangeEntryType, aIncludeUndatedTodos, aFilterStartTime, aFilterEndTime)); |
|
255 } |
|
256 |
|
257 /** Start notification of any changes to calendar entries. |
|
258 These changes can be filtered, and when a change occurs the MCalChangeCallBack2 callback function is called |
|
259 with details about the entry which has changed (TCalLocalUid and entry type) and the type of change (add/delete/modify). |
|
260 |
|
261 @param aCallBack The class to notify when a change occurs. |
|
262 @param aFilter Filter notifications to only notify on certain types of entries. |
|
263 @publishedAll |
|
264 @released |
|
265 @capability None |
|
266 */ |
|
267 EXPORT_C void CCalSession::StartChangeNotification(MCalChangeCallBack2& aChangeObserver, const CCalChangeNotificationFilter& aFilter) |
|
268 { |
|
269 TRAP_IGNORE(iImpl->StartChangeNotificationL(aChangeObserver, aFilter)); |
|
270 } |
|
271 |
|
272 /** Start notification of changes to calendar files. |
|
273 When a change occurs, the MCalFileChangeObserver callback function is called |
|
274 with change types (see MCalFileChangeObserver::TChangeType) about the files. |
|
275 |
|
276 @param aCallBack The class to notify when a change occurs. |
|
277 @publishedAll |
|
278 @prototype |
|
279 @capability None |
|
280 */ |
|
281 EXPORT_C void CCalSession::StartFileChangeNotificationL(MCalFileChangeObserver& aCallBack) |
|
282 { |
|
283 iImpl->StartFileChangeNotificationL(aCallBack); |
|
284 } |
|
285 |
|
286 /** Stop file change notification from this session. |
|
287 @publishedAll |
|
288 @released |
|
289 @capability None |
|
290 */ |
|
291 EXPORT_C void CCalSession::StopFileChangeNotification() |
|
292 { |
|
293 iImpl->StopFileChangeNotification(); |
|
294 } |
|
295 |
|
296 /** Stop entry notifications from this session. |
|
297 @publishedAll |
|
298 @released |
|
299 @capability None |
|
300 */ |
|
301 EXPORT_C void CCalSession::StopChangeNotification() |
|
302 { |
|
303 iImpl->StopChangeNotification(); |
|
304 } |
|
305 |
|
306 /** Disable all notifications from changes made within this session. |
|
307 Changes made within other sessions will still be notified. This can be done before a bulk operation, |
|
308 to prevent a large number of notifications from appearing. |
|
309 Note that this call does not disable publish and subscribe notifications. That must be done from DisablePubSubNotificationsL. |
|
310 @publishedAll |
|
311 @released |
|
312 @capability None |
|
313 */ |
|
314 EXPORT_C void CCalSession::DisableChangeBroadcast() |
|
315 { |
|
316 iImpl->DisableChangeBroadcast(); |
|
317 } |
|
318 |
|
319 /** Re-enable all notifications from changes made within this session. |
|
320 This function has the opposite effect of DisableChangeBroadcast. |
|
321 @publishedAll |
|
322 @released |
|
323 @capability None |
|
324 */ |
|
325 EXPORT_C void CCalSession::EnableChangeBroadcast() |
|
326 { |
|
327 iImpl->EnableChangeBroadcast(); |
|
328 } |
|
329 |
|
330 /** Gets the file ID of the currently open Calendar file. This is unique to the file. |
|
331 @publishedAll |
|
332 @released |
|
333 @capability None |
|
334 @param aCalFileId On return will be the file ID of the currently open Calendar file. The file ID will be set to KNullFileId if the file is not opened. |
|
335 */ |
|
336 EXPORT_C void CCalSession::FileIdL(TCalFileId& aCalFileId) const |
|
337 { |
|
338 iImpl->FileIdL(aCalFileId); |
|
339 } |
|
340 |
|
341 /** Gets the Collection ID of the currently open Calendar file. |
|
342 Note that: |
|
343 |
|
344 This ID should not be persisted because it is re-generated whenever the session is connected. |
|
345 This ID identifies the same Calendar file as the file ID retrieved form CCalSession::FileIdL(TCalFileId& aCalFileId) |
|
346 |
|
347 @publishedAll |
|
348 @released |
|
349 @capability None |
|
350 @return Return the Collection ID of the currently open Calendar file, 0 if the file has not been opened. |
|
351 */ |
|
352 EXPORT_C TCalCollectionId CCalSession::CollectionIdL() const |
|
353 { |
|
354 return iImpl->CollectionId(); |
|
355 } |
|
356 |
|
357 /** Simulates a heap allocation failure for the server-side heap. Debug only. |
|
358 |
|
359 The failure occurs on subsequent calls to new or any of the functions which |
|
360 allocate memory from the server-side heap. |
|
361 |
|
362 The timing of the allocation failure depends on the type of |
|
363 allocation failure requested, i.e. on the value of aFail. |
|
364 |
|
365 The simulation of heap allocation failure is cancelled |
|
366 if aFail is given the value RAllocator::ENone. |
|
367 |
|
368 Notes: |
|
369 |
|
370 1. If the failure type is RAllocator::EFailNext, the next attempt to allocate from |
|
371 the server-side heap fails; however, no further failures will occur. |
|
372 |
|
373 2. For failure types RAllocator::EFailNext and RAllocator::ENone, set aRate to 1. |
|
374 |
|
375 @test |
|
376 @param aFail An enumeration which indicates how to simulate heap allocation failure. |
|
377 @param aRate The rate of failure; when aType is RAllocator::EDeterministic, heap allocation fails every aRate attempt. |
|
378 @pre There is an open calendar session. |
|
379 @post The calendar server will fail memory allocation at the specified point. |
|
380 @released |
|
381 @publishedPartner |
|
382 */ |
|
383 #ifdef _DEBUG |
|
384 EXPORT_C void CCalSession::_DebugSetHeapFailL(RAllocator::TAllocFail aFail, TInt aRate) |
|
385 { |
|
386 iImpl->_DebugSetHeapFailL(aFail, aRate); |
|
387 } |
|
388 #else |
|
389 EXPORT_C void CCalSession::_DebugSetHeapFailL(RAllocator::TAllocFail /*aFail*/, TInt /*aRate*/) |
|
390 { |
|
391 } |
|
392 #endif |
|
393 |
|
394 /** Gets the total number of cells allocated on the server-side heap. Debug only. |
|
395 @test |
|
396 @return The number of cells allocated on the heap. |
|
397 @pre There is an open calendar session. |
|
398 @post None |
|
399 @released |
|
400 @publishedPartner |
|
401 */ |
|
402 EXPORT_C TInt CCalSession::_DebugRequestAllocatedCellsL() |
|
403 { |
|
404 #ifdef _DEBUG |
|
405 return iImpl->_DebugRequestAllocatedCellsL(); |
|
406 #else |
|
407 return 0; |
|
408 #endif |
|
409 } |
|
410 |
|
411 /** Enable Publish and Subscribe notifications for changes made by this client only. |
|
412 @publishedAll |
|
413 @released |
|
414 @capability None |
|
415 */ |
|
416 EXPORT_C void CCalSession::EnablePubSubNotificationsL() |
|
417 { |
|
418 iImpl->EnablePubSubNotificationsL(); |
|
419 } |
|
420 |
|
421 /** Disable Publish and Subscribe notifications for changes made by this client only. |
|
422 @publishedAll |
|
423 @released |
|
424 @capability None |
|
425 */ |
|
426 EXPORT_C void CCalSession::DisablePubSubNotificationsL() |
|
427 { |
|
428 iImpl->DisablePubSubNotificationsL(); |
|
429 } |
|
430 |
|
431 /** Retrieve a calendar file name from its hash value. |
|
432 The hash value comes from the Publish and Subscribe CalInterimAPI data in TCalPubSubData. |
|
433 @publishedAll |
|
434 @released |
|
435 @capability None |
|
436 @param aPubSubData The publish and subscribe data. |
|
437 @param aFileName On return will be the full file name. |
|
438 */ |
|
439 EXPORT_C void CCalSession::GetFileNameL(TCalPubSubData aPubSubData, TDes& aFileName) const |
|
440 { |
|
441 iImpl->GetFileNameL(aPubSubData, aFileName); |
|
442 } |
|
443 |
|
444 /** Test if the full file name passed is the one that was changed. |
|
445 @publishedAll |
|
446 @released |
|
447 @return ETrue if the full file name passed is the one that was changed, EFalse if not. |
|
448 @capability None |
|
449 @param aPubSubData The publish and subscribe data. |
|
450 @param aFileName The full file name to test. |
|
451 */ |
|
452 EXPORT_C TBool CCalSession::IsFileNameL(TCalPubSubData aPubSubData, const TDesC& aFileName) const |
|
453 { |
|
454 return iImpl->IsFileNameL(aPubSubData, aFileName); |
|
455 } |
|
456 |
|
457 /** Test if the publish and subscribe data relates to the currently open calendar file. |
|
458 @publishedAll |
|
459 @released |
|
460 @return ETrue if the publish and subscribe data relates to the currently open calendar file, EFalse if not. |
|
461 @capability None |
|
462 @param aPubSubData The publish and subscribe data. |
|
463 */ |
|
464 EXPORT_C TBool CCalSession::IsOpenedFileL(TCalPubSubData aPubSubData) const |
|
465 { |
|
466 return iImpl->IsOpenedFileL(aPubSubData); |
|
467 } |
|
468 |
|
469 void CCalSession::ConstructL(CCalSession& aCalSession) |
|
470 { |
|
471 iImpl = CCalSessionImpl::NewL(aCalSession.Impl()); |
|
472 } |
|
473 |
|
474 /** Allocates and constructs a session to the Calendar server |
|
475 |
|
476 @pre At least one object of CalSession has been created (which means a connection to server has been established). |
|
477 |
|
478 @publishedAll |
|
479 @released |
|
480 @capability None |
|
481 @param aCalSession A reference to CalSession which is created beforehand. |
|
482 @return Pointer to the newly created session which shares the handle to the Calendar server with aCalSession. |
|
483 */ |
|
484 EXPORT_C CCalSession* CCalSession::NewL(CCalSession& aCalSession) |
|
485 { |
|
486 CCalSession* self = new (ELeave) CCalSession(); |
|
487 CleanupStack::PushL(self); |
|
488 self->ConstructL(aCalSession); |
|
489 CleanupStack::Pop(self); |
|
490 return self; |
|
491 } |
|
492 /** Clears timezone information cached at client side. |
|
493 This API should be used for debug purpose. |
|
494 @internalComponent |
|
495 @released |
|
496 @capability None |
|
497 @param aRestartCaching Set to ETrue if caching needs to be restarted after clearing current cache. |
|
498 */ |
|
499 #if defined(_DEBUG) |
|
500 |
|
501 EXPORT_C void CCalSession::__dbgClearTzClientCacheL(TBool aRestartCaching) |
|
502 { |
|
503 iImpl->__dbgClearTzClientCacheL(aRestartCaching); |
|
504 } |
|
505 |
|
506 #else |
|
507 |
|
508 EXPORT_C void CCalSession::__dbgClearTzClientCacheL(TBool /*aRestartCaching*/) {} |
|
509 |
|
510 #endif |
|
511 |
|
512 |
|
513 EXPORT_C TInt CCalSession::_DebugRequestAllocatedHeapSizeL() |
|
514 { |
|
515 #ifdef _DEBUG |
|
516 return iImpl->_DebugRequestAllocatedHeapSizeL(); |
|
517 #else |
|
518 return 0; |
|
519 #endif |
|
520 } |