1.1 --- a/epoc32/include/phbksync.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,358 +0,0 @@
1.4 -// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 -// All rights reserved.
1.6 -// This component and the accompanying materials are made available
1.7 -// 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
1.8 -// which accompanies this distribution, and is available
1.9 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 -//
1.11 -// Initial Contributors:
1.12 -// Nokia Corporation - initial contribution.
1.13 -//
1.14 -// Contributors:
1.15 -//
1.16 -// Description:
1.17 -// Phonebook Synchroniser API header file.
1.18 -// Describes the Phonebook Synchroniser API for use by clients of the
1.19 -// Phonebook Synchroniser Server.
1.20 -//
1.21 -//
1.22 -
1.23 -
1.24 -
1.25 -/**
1.26 - @file
1.27 - @publishedAll
1.28 - @released
1.29 -*/
1.30 -
1.31 -#ifndef __PHBKSYNC_H__
1.32 -#define __PHBKSYNC_H__
1.33 -
1.34 -#include <e32std.h>
1.35 -#include <cntdef.h>
1.36 -#include <cntdb.h>
1.37 -#include <cntitem.h>
1.38 -#include <cntfldst.h>
1.39 -
1.40 -/**
1.41 - * Index not supplied.
1.42 - */
1.43 -const TInt KSyncIndexNotSupplied=-1;
1.44 -
1.45 -
1.46 -//
1.47 -// TUid Phonebook Types used by Contacts Model
1.48 -//
1.49 -#define KUidIccPhonebookNotSpecifiedValue 0x101F7874
1.50 -#define KUidIccGlobalAdnPhonebookValue 0x101F7875
1.51 -#define KUidIccGlobalSdnPhonebookValue 0x101F7876
1.52 -#define KUidIccGlobalLndPhonebookValue 0x101F7877
1.53 -#define KUidUsimAppAdnPhonebookValue 0x101F7878
1.54 -#define KUidIccGlobalFdnPhonebookValue 0x101FB2AF
1.55 -
1.56 -const TUid KUidIccPhonebookNotSpecified = {KUidIccPhonebookNotSpecifiedValue};
1.57 -const TUid KUidIccGlobalAdnPhonebook = {KUidIccGlobalAdnPhonebookValue};
1.58 -const TUid KUidIccGlobalSdnPhonebook = {KUidIccGlobalSdnPhonebookValue};
1.59 -const TUid KUidIccGlobalLndPhonebook = {KUidIccGlobalLndPhonebookValue};
1.60 -const TUid KUidUsimAppAdnPhonebook = {KUidUsimAppAdnPhonebookValue};
1.61 -const TUid KUidIccGlobalFdnPhonebook = {KUidIccGlobalFdnPhonebookValue};
1.62 -
1.63 -
1.64 -/**
1.65 - * Types of cancel requests for the asynchronous server requests.
1.66 - *
1.67 - * @see RPhoneBookSession::CancelRequest
1.68 - */
1.69 -enum TPhonebookSyncRequestCancel
1.70 - {
1.71 - /** Cancel the asynchronous RPhoneBookSession::DoSynchronisation() request */
1.72 - EDoSynchronisationCancelClient,
1.73 -
1.74 - /** Cancel the asynchronous RPhoneBookSession::DeleteContact() request */
1.75 - ESyncDeleteCntFromICCCancelClient,
1.76 -
1.77 - /** Cancel the asynchronous RPhoneBookSession::WriteContact() request */
1.78 - ESyncWriteCntToICCCancelClient,
1.79 -
1.80 - /** Cancel the asynchronous RPhoneBookSession::NotifyPhBkCacheStateChange() request */
1.81 - ESyncNotifyCacheStateChangeCancelClient
1.82 - };
1.83 -
1.84 -
1.85 -/**
1.86 - * Class to hold the contact field formats.
1.87 - *
1.88 - * @publishedAll
1.89 - * @released
1.90 - */
1.91 -class TContactFieldFormat
1.92 - {
1.93 -public:
1.94 - TContactFieldFormat(TInt aLength, TInt aCount, TBool aDisplayed);
1.95 -
1.96 -public:
1.97 - /** The maximum length (i.e. number of characters) of the field. If the field is
1.98 - not a string type this attribute should be ignored. */
1.99 - TInt iLength;
1.100 -
1.101 - /** The maximum number of instances of this field within an item. This is set to
1.102 - -1 if this is unlimited. */
1.103 - TInt iCount;
1.104 -
1.105 - /** Indicates whether this is displayed or hidden. */
1.106 - TBool iDisplayed;
1.107 - };
1.108 -
1.109 -
1.110 -//
1.111 -// Forward declare the internal data storage class.
1.112 -//
1.113 -class CSyncClientData;
1.114 -
1.115 -/**
1.116 - * Provides the CPhoneBookSyncPlugin client access to a session with the
1.117 - * Phonebook Synchronizer Server.
1.118 - *
1.119 - * A handle to an RPhoneBookSession enables the plug-in class to perform
1.120 - * IPC communications with the server.
1.121 - *
1.122 - * @publishedAll
1.123 - * @released
1.124 - */
1.125 -class RPhoneBookSession : public RSessionBase
1.126 - {
1.127 -public:
1.128 - /**
1.129 - * Structure holding the template ID and buffer size. The client has
1.130 - * no need to use this structure.
1.131 - *
1.132 - * @deprecated
1.133 - */
1.134 - struct TTemplateAndBufferSize
1.135 - {
1.136 - TContactItemId templateId;
1.137 - TInt bufferSize;
1.138 - };
1.139 -
1.140 - /**
1.141 - * The synchronisation mode for phonebooks when the server starts.
1.142 - */
1.143 - enum TPhonebookSyncMode
1.144 - {
1.145 - /** Automatic synchronisation will be performed. */
1.146 - EAutoCurrentIcc,
1.147 -
1.148 - /** Automatic synchronisation will only be performed if the current ICC is
1.149 - the same as the last ICC to be synchonised. */
1.150 - EAutoSameIcc,
1.151 -
1.152 - /** Manual synchronisation will be performed when requested. */
1.153 - EManual
1.154 - };
1.155 -
1.156 - /**
1.157 - * The phonebook cache state.
1.158 - */
1.159 - enum TSyncState
1.160 - {
1.161 - /** The server has not yet populated the Contacts Database. */
1.162 - EUnsynchronised,
1.163 -
1.164 - /** The server has finished populating the Contacts Database. */
1.165 - ECacheValid,
1.166 -
1.167 - /** The server encountered an error populating the Contacts Database. */
1.168 - EErrorDuringSync
1.169 - };
1.170 -
1.171 - /**
1.172 - * Specifies format of phonebook fields within an ICC phonebook entry.
1.173 - *
1.174 - * @publishedAll
1.175 - * @released
1.176 - */
1.177 - class TContactFieldsV1
1.178 - {
1.179 - public:
1.180 - /**
1.181 - * Enumeration to describe the version ID of the Phonebook Synchronizer.
1.182 - */
1.183 - enum TContactFieldsExtensionId
1.184 - {
1.185 - /** Phonebook Synchronizer version 1 */
1.186 - KPhBkSyncTContactFieldsV1,
1.187 -
1.188 - /** Phonebook Synchronizer version 2 */
1.189 - KPhBkSyncTContactFieldsV2,
1.190 -
1.191 - /** Phonebook Synchronizer version 3 */
1.192 - KPhBkSyncTContactFieldsV3
1.193 - };
1.194 -
1.195 - /**
1.196 - * Returns the Phonebook Synchronizer API extension number of the class.
1.197 - *
1.198 - * @return The version ID from TContactFieldsExtensionId.
1.199 - */
1.200 - IMPORT_C TInt ExtensionId() const;
1.201 -
1.202 - /**
1.203 - * Standard constructor.
1.204 - */
1.205 - IMPORT_C TContactFieldsV1();
1.206 -
1.207 - public:
1.208 - /** The format of the name field within an ICC phonebook entry. */
1.209 - TContactFieldFormat iNameField;
1.210 -
1.211 - /** The format of the number field within an ICC phonebook entry. */
1.212 - TContactFieldFormat iNumberField;
1.213 -
1.214 - /** The format of the ICC slot number field within an ICC phonebook entry. */
1.215 - TContactFieldFormat iIccSlotField;
1.216 -
1.217 - protected:
1.218 - TInt iExtensionId;
1.219 - };
1.220 -
1.221 - /**
1.222 - * A packaged instance of TContactFieldsV1.
1.223 - */
1.224 - typedef TPckg<TContactFieldsV1> TContactFieldsV1Pckg;
1.225 -
1.226 - /**
1.227 - * Specifies format of phonebook fields within an UICC phonebook entry
1.228 - *
1.229 - * @publishedAll
1.230 - * @released
1.231 - */
1.232 - class TContactFieldsV2 : public TContactFieldsV1
1.233 - {
1.234 - public:
1.235 - IMPORT_C TContactFieldsV2();
1.236 -
1.237 - public:
1.238 - /** The format of any additional number fields within an ICC phonebook entry. */
1.239 - TContactFieldFormat iAdditionalNumString;
1.240 -
1.241 - /** The format of group field within an ICC phonebook entry. */
1.242 - TContactFieldFormat iGroupField;
1.243 -
1.244 - /** The format of email field within an ICC phonebook entry. */
1.245 - TContactFieldFormat iEmailField;
1.246 -
1.247 - /** The UID of the phonebook. */
1.248 - TUid iPhonebook;
1.249 - };
1.250 -
1.251 - /**
1.252 - * A packaged instance of TContactFieldsV2.
1.253 - */
1.254 - typedef TPckg<TContactFieldsV2> TContactFieldsV2Pckg;
1.255 -
1.256 -
1.257 - /**
1.258 - * Specifies additional format information for phonebook fields within a
1.259 - * UICC phonebook entry.
1.260 - *
1.261 - * @publishedAll
1.262 - * @released
1.263 - */
1.264 - class TContactFieldsV3 : public TContactFieldsV2
1.265 - {
1.266 - public:
1.267 - IMPORT_C TContactFieldsV3();
1.268 -
1.269 - public:
1.270 - /** The format of an addition number's text field within an ICC phonebook entry. */
1.271 - TContactFieldFormat iAdditionalNumAlphaString;
1.272 -
1.273 - /** The format of the second name field within an ICC phonebook entry. */
1.274 - TContactFieldFormat iSecondNameField;
1.275 - };
1.276 -
1.277 - /**
1.278 - * A packaged instance of TContactFieldsV3.
1.279 - */
1.280 - typedef TPckg<TContactFieldsV3> TContactFieldsV3Pckg;
1.281 -
1.282 -
1.283 - /**
1.284 - * The phonebook ID type requested from a phonebook. There are two types of IDs
1.285 - * (group IDs and template IDs).
1.286 - *
1.287 - * @see RPhoneBookSession::GetPhoneBookId()
1.288 - */
1.289 - enum TSyncIdType
1.290 - {
1.291 - /** Used to allocate a new entry to the right group in the Contacts Database. */
1.292 - ESyncGroupId,
1.293 -
1.294 - /** Used to define new ICC entries in the Contacts Database. */
1.295 - ESyncTemplateId
1.296 - };
1.297 -
1.298 -public:
1.299 - IMPORT_C RPhoneBookSession();
1.300 - IMPORT_C TInt Connect();
1.301 - IMPORT_C void Close();
1.302 - IMPORT_C TVersion Version() const;
1.303 - IMPORT_C TInt ShutdownServer (TBool aUnconditionally);
1.304 -
1.305 - //
1.306 - // Single (ADN) phonebook support and functions not requiring a phonebook UID.
1.307 - //
1.308 - IMPORT_C void DoSynchronisation(TRequestStatus& aReqStatus);
1.309 - IMPORT_C TInt ValidateContact(MContactSynchroniser::TValidateOperation aOperation, TContactItemId aId);
1.310 - IMPORT_C void WriteContact(TRequestStatus& aReqStatus, CContactICCEntry& aContactItem,
1.311 - TInt& aSlotNumber);
1.312 - IMPORT_C void DeleteContact(TRequestStatus& aReqStatus, TContactItemId aId);
1.313 - IMPORT_C TInt GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType);
1.314 - IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot);
1.315 - IMPORT_C TInt GetContactFormat(TDes8& aContactFields);
1.316 - IMPORT_C TInt GetSyncMode(TPhonebookSyncMode& aSyncMode);
1.317 - IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode);
1.318 - IMPORT_C TInt GetPhoneBookCacheState(TSyncState& aState);
1.319 - IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel);
1.320 - IMPORT_C TInt GetLastSyncError(TInt& aError);
1.321 - IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus& aStatus);
1.322 - IMPORT_C TInt GetNumSlots(TInt& aNumSlots) const;
1.323 - IMPORT_C void GetFreeSlotsL(RArray<TInt>& aFreeSlots) const;
1.324 - IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId& aId) const;
1.325 -
1.326 - //
1.327 - // Multiple phonebooks support. These should be used in preference to the above
1.328 - // ADN specific versions.
1.329 - //
1.330 - IMPORT_C void DoSynchronisation(TRequestStatus& aReqStatus, TUid aPhonebookUid);
1.331 - IMPORT_C void WriteContact(TRequestStatus& aReqStatus, CContactICCEntry& aContactItem,
1.332 - TInt& aSlotNumber, TUid& aPhonebookUid);
1.333 - IMPORT_C TInt GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType, TUid aPhonebookUid);
1.334 - IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot, TUid aPhonebookUid);
1.335 - IMPORT_C TInt GetSyncMode(TPhonebookSyncMode& aSyncMode, TUid aPhonebookId);
1.336 - IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode, TUid aPhonebookId);
1.337 - IMPORT_C TInt GetPhoneBookCacheState(TSyncState& aState, TUid aPhonebookId);
1.338 - IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel, TUid aPhonebookId);
1.339 - IMPORT_C TInt GetLastSyncError(TInt& aError, TUid aPhonebookId);
1.340 - IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus& aStatus, TUid aPhonebookId);
1.341 - IMPORT_C TInt GetNumSlots(TInt& aNumSlots, TUid aPhonebookId) const;
1.342 - IMPORT_C void GetFreeSlotsL(RArray<TInt>& aFreeSlots, TUid aPhonebookId) const;
1.343 - IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId& aId, TUid aPhonebookId) const;
1.344 -
1.345 - //
1.346 - // Memory checking functionality for Debug builds only.
1.347 - //
1.348 - IMPORT_C TInt __DbgMarkHeap();
1.349 - IMPORT_C TInt __DbgCheckHeap(TInt aCount);
1.350 - IMPORT_C TInt __DbgMarkEnd(TInt aCount);
1.351 - IMPORT_C TInt __DbgFailNext(TInt aCount);
1.352 -
1.353 -private:
1.354 - RPhoneBookSession(const RPhoneBookSession& aSession);
1.355 -
1.356 -private:
1.357 - /* Temporary data used by the session. */
1.358 - CSyncClientData* iData;
1.359 - };
1.360 -
1.361 -#endif