|
1 // Copyright (c) 2002-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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Phonebook Synchroniser API header file. |
|
15 // Describes the Phonebook Synchroniser API for use by clients of the |
|
16 // Phonebook Synchroniser Server. |
|
17 // |
|
18 // |
|
19 |
|
20 |
|
21 |
|
22 /** |
|
23 @file |
|
24 @publishedAll |
|
25 @released |
|
26 */ |
|
27 |
|
28 #ifndef __PHBKSYNC_H__ |
|
29 #define __PHBKSYNC_H__ |
|
30 |
|
31 #include <e32std.h> |
|
32 #include <cntdef.h> |
|
33 #include <cntdb.h> |
|
34 #include <cntitem.h> |
|
35 #include <cntfldst.h> |
|
36 |
|
37 /** |
|
38 * Index not supplied. |
|
39 */ |
|
40 const TInt KSyncIndexNotSupplied=-1; |
|
41 |
|
42 |
|
43 // |
|
44 // TUid Phonebook Types used by Contacts Model |
|
45 // |
|
46 #define KUidIccPhonebookNotSpecifiedValue 0x101F7874 |
|
47 #define KUidIccGlobalAdnPhonebookValue 0x101F7875 |
|
48 #define KUidIccGlobalSdnPhonebookValue 0x101F7876 |
|
49 #define KUidIccGlobalLndPhonebookValue 0x101F7877 |
|
50 #define KUidUsimAppAdnPhonebookValue 0x101F7878 |
|
51 #define KUidIccGlobalFdnPhonebookValue 0x101FB2AF |
|
52 |
|
53 const TUid KUidIccPhonebookNotSpecified = {KUidIccPhonebookNotSpecifiedValue}; |
|
54 const TUid KUidIccGlobalAdnPhonebook = {KUidIccGlobalAdnPhonebookValue}; |
|
55 const TUid KUidIccGlobalSdnPhonebook = {KUidIccGlobalSdnPhonebookValue}; |
|
56 const TUid KUidIccGlobalLndPhonebook = {KUidIccGlobalLndPhonebookValue}; |
|
57 const TUid KUidUsimAppAdnPhonebook = {KUidUsimAppAdnPhonebookValue}; |
|
58 const TUid KUidIccGlobalFdnPhonebook = {KUidIccGlobalFdnPhonebookValue}; |
|
59 |
|
60 |
|
61 /** |
|
62 * Types of cancel requests for the asynchronous server requests. |
|
63 * |
|
64 * @see RPhoneBookSession::CancelRequest |
|
65 */ |
|
66 enum TPhonebookSyncRequestCancel |
|
67 { |
|
68 /** Cancel the asynchronous RPhoneBookSession::DoSynchronisation() request */ |
|
69 EDoSynchronisationCancelClient, |
|
70 |
|
71 /** Cancel the asynchronous RPhoneBookSession::DeleteContact() request */ |
|
72 ESyncDeleteCntFromICCCancelClient, |
|
73 |
|
74 /** Cancel the asynchronous RPhoneBookSession::WriteContact() request */ |
|
75 ESyncWriteCntToICCCancelClient, |
|
76 |
|
77 /** Cancel the asynchronous RPhoneBookSession::NotifyPhBkCacheStateChange() request */ |
|
78 ESyncNotifyCacheStateChangeCancelClient |
|
79 }; |
|
80 |
|
81 |
|
82 /** |
|
83 * Class to hold the contact field formats. |
|
84 * |
|
85 * @publishedAll |
|
86 * @released |
|
87 */ |
|
88 class TContactFieldFormat |
|
89 { |
|
90 public: |
|
91 TContactFieldFormat(TInt aLength, TInt aCount, TBool aDisplayed); |
|
92 |
|
93 public: |
|
94 /** The maximum length (i.e. number of characters) of the field. If the field is |
|
95 not a string type this attribute should be ignored. */ |
|
96 TInt iLength; |
|
97 |
|
98 /** The maximum number of instances of this field within an item. This is set to |
|
99 -1 if this is unlimited. */ |
|
100 TInt iCount; |
|
101 |
|
102 /** Indicates whether this is displayed or hidden. */ |
|
103 TBool iDisplayed; |
|
104 }; |
|
105 |
|
106 |
|
107 // |
|
108 // Forward declare the internal data storage class. |
|
109 // |
|
110 class CSyncClientData; |
|
111 |
|
112 /** |
|
113 * Provides the CPhoneBookSyncPlugin client access to a session with the |
|
114 * Phonebook Synchronizer Server. |
|
115 * |
|
116 * A handle to an RPhoneBookSession enables the plug-in class to perform |
|
117 * IPC communications with the server. |
|
118 * |
|
119 * @publishedAll |
|
120 * @released |
|
121 */ |
|
122 class RPhoneBookSession : public RSessionBase |
|
123 { |
|
124 public: |
|
125 /** |
|
126 * Structure holding the template ID and buffer size. The client has |
|
127 * no need to use this structure. |
|
128 * |
|
129 * @deprecated |
|
130 */ |
|
131 struct TTemplateAndBufferSize |
|
132 { |
|
133 TContactItemId templateId; |
|
134 TInt bufferSize; |
|
135 }; |
|
136 |
|
137 /** |
|
138 * The synchronisation mode for phonebooks when the server starts. |
|
139 */ |
|
140 enum TPhonebookSyncMode |
|
141 { |
|
142 /** Automatic synchronisation will be performed. */ |
|
143 EAutoCurrentIcc, |
|
144 |
|
145 /** Automatic synchronisation will only be performed if the current ICC is |
|
146 the same as the last ICC to be synchonised. */ |
|
147 EAutoSameIcc, |
|
148 |
|
149 /** Manual synchronisation will be performed when requested. */ |
|
150 EManual |
|
151 }; |
|
152 |
|
153 /** |
|
154 * The phonebook cache state. |
|
155 */ |
|
156 enum TSyncState |
|
157 { |
|
158 /** The server has not yet populated the Contacts Database. */ |
|
159 EUnsynchronised, |
|
160 |
|
161 /** The server has finished populating the Contacts Database. */ |
|
162 ECacheValid, |
|
163 |
|
164 /** The server encountered an error populating the Contacts Database. */ |
|
165 EErrorDuringSync |
|
166 }; |
|
167 |
|
168 /** |
|
169 * Specifies format of phonebook fields within an ICC phonebook entry. |
|
170 * |
|
171 * @publishedAll |
|
172 * @released |
|
173 */ |
|
174 class TContactFieldsV1 |
|
175 { |
|
176 public: |
|
177 /** |
|
178 * Enumeration to describe the version ID of the Phonebook Synchronizer. |
|
179 */ |
|
180 enum TContactFieldsExtensionId |
|
181 { |
|
182 /** Phonebook Synchronizer version 1 */ |
|
183 KPhBkSyncTContactFieldsV1, |
|
184 |
|
185 /** Phonebook Synchronizer version 2 */ |
|
186 KPhBkSyncTContactFieldsV2, |
|
187 |
|
188 /** Phonebook Synchronizer version 3 */ |
|
189 KPhBkSyncTContactFieldsV3 |
|
190 }; |
|
191 |
|
192 /** |
|
193 * Returns the Phonebook Synchronizer API extension number of the class. |
|
194 * |
|
195 * @return The version ID from TContactFieldsExtensionId. |
|
196 */ |
|
197 IMPORT_C TInt ExtensionId() const; |
|
198 |
|
199 /** |
|
200 * Standard constructor. |
|
201 */ |
|
202 IMPORT_C TContactFieldsV1(); |
|
203 |
|
204 public: |
|
205 /** The format of the name field within an ICC phonebook entry. */ |
|
206 TContactFieldFormat iNameField; |
|
207 |
|
208 /** The format of the number field within an ICC phonebook entry. */ |
|
209 TContactFieldFormat iNumberField; |
|
210 |
|
211 /** The format of the ICC slot number field within an ICC phonebook entry. */ |
|
212 TContactFieldFormat iIccSlotField; |
|
213 |
|
214 protected: |
|
215 TInt iExtensionId; |
|
216 }; |
|
217 |
|
218 /** |
|
219 * A packaged instance of TContactFieldsV1. |
|
220 */ |
|
221 typedef TPckg<TContactFieldsV1> TContactFieldsV1Pckg; |
|
222 |
|
223 /** |
|
224 * Specifies format of phonebook fields within an UICC phonebook entry |
|
225 * |
|
226 * @publishedAll |
|
227 * @released |
|
228 */ |
|
229 class TContactFieldsV2 : public TContactFieldsV1 |
|
230 { |
|
231 public: |
|
232 IMPORT_C TContactFieldsV2(); |
|
233 |
|
234 public: |
|
235 /** The format of any additional number fields within an ICC phonebook entry. */ |
|
236 TContactFieldFormat iAdditionalNumString; |
|
237 |
|
238 /** The format of group field within an ICC phonebook entry. */ |
|
239 TContactFieldFormat iGroupField; |
|
240 |
|
241 /** The format of email field within an ICC phonebook entry. */ |
|
242 TContactFieldFormat iEmailField; |
|
243 |
|
244 /** The UID of the phonebook. */ |
|
245 TUid iPhonebook; |
|
246 }; |
|
247 |
|
248 /** |
|
249 * A packaged instance of TContactFieldsV2. |
|
250 */ |
|
251 typedef TPckg<TContactFieldsV2> TContactFieldsV2Pckg; |
|
252 |
|
253 |
|
254 /** |
|
255 * Specifies additional format information for phonebook fields within a |
|
256 * UICC phonebook entry. |
|
257 * |
|
258 * @publishedAll |
|
259 * @released |
|
260 */ |
|
261 class TContactFieldsV3 : public TContactFieldsV2 |
|
262 { |
|
263 public: |
|
264 IMPORT_C TContactFieldsV3(); |
|
265 |
|
266 public: |
|
267 /** The format of an addition number's text field within an ICC phonebook entry. */ |
|
268 TContactFieldFormat iAdditionalNumAlphaString; |
|
269 |
|
270 /** The format of the second name field within an ICC phonebook entry. */ |
|
271 TContactFieldFormat iSecondNameField; |
|
272 }; |
|
273 |
|
274 /** |
|
275 * A packaged instance of TContactFieldsV3. |
|
276 */ |
|
277 typedef TPckg<TContactFieldsV3> TContactFieldsV3Pckg; |
|
278 |
|
279 |
|
280 /** |
|
281 * The phonebook ID type requested from a phonebook. There are two types of IDs |
|
282 * (group IDs and template IDs). |
|
283 * |
|
284 * @see RPhoneBookSession::GetPhoneBookId() |
|
285 */ |
|
286 enum TSyncIdType |
|
287 { |
|
288 /** Used to allocate a new entry to the right group in the Contacts Database. */ |
|
289 ESyncGroupId, |
|
290 |
|
291 /** Used to define new ICC entries in the Contacts Database. */ |
|
292 ESyncTemplateId |
|
293 }; |
|
294 |
|
295 public: |
|
296 IMPORT_C RPhoneBookSession(); |
|
297 IMPORT_C TInt Connect(); |
|
298 IMPORT_C void Close(); |
|
299 IMPORT_C TVersion Version() const; |
|
300 IMPORT_C TInt ShutdownServer (TBool aUnconditionally); |
|
301 |
|
302 // |
|
303 // Single (ADN) phonebook support and functions not requiring a phonebook UID. |
|
304 // |
|
305 IMPORT_C void DoSynchronisation(TRequestStatus& aReqStatus); |
|
306 IMPORT_C TInt ValidateContact(MContactSynchroniser::TValidateOperation aOperation, TContactItemId aId); |
|
307 IMPORT_C void WriteContact(TRequestStatus& aReqStatus, CContactICCEntry& aContactItem, |
|
308 TInt& aSlotNumber); |
|
309 IMPORT_C void DeleteContact(TRequestStatus& aReqStatus, TContactItemId aId); |
|
310 IMPORT_C TInt GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType); |
|
311 IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot); |
|
312 IMPORT_C TInt GetContactFormat(TDes8& aContactFields); |
|
313 IMPORT_C TInt GetSyncMode(TPhonebookSyncMode& aSyncMode); |
|
314 IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode); |
|
315 IMPORT_C TInt GetPhoneBookCacheState(TSyncState& aState); |
|
316 IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel); |
|
317 IMPORT_C TInt GetLastSyncError(TInt& aError); |
|
318 IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus& aStatus); |
|
319 IMPORT_C TInt GetNumSlots(TInt& aNumSlots) const; |
|
320 IMPORT_C void GetFreeSlotsL(RArray<TInt>& aFreeSlots) const; |
|
321 IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId& aId) const; |
|
322 |
|
323 // |
|
324 // Multiple phonebooks support. These should be used in preference to the above |
|
325 // ADN specific versions. |
|
326 // |
|
327 IMPORT_C void DoSynchronisation(TRequestStatus& aReqStatus, TUid aPhonebookUid); |
|
328 IMPORT_C void WriteContact(TRequestStatus& aReqStatus, CContactICCEntry& aContactItem, |
|
329 TInt& aSlotNumber, TUid& aPhonebookUid); |
|
330 IMPORT_C TInt GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType, TUid aPhonebookUid); |
|
331 IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot, TUid aPhonebookUid); |
|
332 IMPORT_C TInt GetSyncMode(TPhonebookSyncMode& aSyncMode, TUid aPhonebookId); |
|
333 IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode, TUid aPhonebookId); |
|
334 IMPORT_C TInt GetPhoneBookCacheState(TSyncState& aState, TUid aPhonebookId); |
|
335 IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel, TUid aPhonebookId); |
|
336 IMPORT_C TInt GetLastSyncError(TInt& aError, TUid aPhonebookId); |
|
337 IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus& aStatus, TUid aPhonebookId); |
|
338 IMPORT_C TInt GetNumSlots(TInt& aNumSlots, TUid aPhonebookId) const; |
|
339 IMPORT_C void GetFreeSlotsL(RArray<TInt>& aFreeSlots, TUid aPhonebookId) const; |
|
340 IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId& aId, TUid aPhonebookId) const; |
|
341 |
|
342 // |
|
343 // Memory checking functionality for Debug builds only. |
|
344 // |
|
345 IMPORT_C TInt __DbgMarkHeap(); |
|
346 IMPORT_C TInt __DbgCheckHeap(TInt aCount); |
|
347 IMPORT_C TInt __DbgMarkEnd(TInt aCount); |
|
348 IMPORT_C TInt __DbgFailNext(TInt aCount); |
|
349 |
|
350 private: |
|
351 RPhoneBookSession(const RPhoneBookSession& aSession); |
|
352 |
|
353 private: |
|
354 /* Temporary data used by the session. */ |
|
355 CSyncClientData* iData; |
|
356 }; |
|
357 |
|
358 #endif |