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