williamr@2: // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@4: // under the terms of "Eclipse Public License v1.0" williamr@2: // which accompanies this distribution, and is available williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: // williamr@2: // Initial Contributors: williamr@2: // Nokia Corporation - initial contribution. williamr@2: // williamr@2: // Contributors: williamr@2: // williamr@2: // Description: williamr@2: // Phonebook Synchroniser API header file. williamr@2: // Describes the Phonebook Synchroniser API for use by clients of the williamr@2: // Phonebook Synchroniser Server. williamr@2: // williamr@2: // williamr@2: williamr@2: /** williamr@2: @file williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: williamr@2: #ifndef __PHBKSYNC_H__ williamr@2: #define __PHBKSYNC_H__ williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: /** williamr@2: * Index not supplied. williamr@2: */ williamr@2: const TInt KSyncIndexNotSupplied=-1; williamr@2: williamr@2: williamr@2: // williamr@2: // TUid Phonebook Types used by Contacts Model williamr@2: // williamr@2: #define KUidIccPhonebookNotSpecifiedValue 0x101F7874 williamr@2: #define KUidIccGlobalAdnPhonebookValue 0x101F7875 williamr@2: #define KUidIccGlobalSdnPhonebookValue 0x101F7876 williamr@2: #define KUidIccGlobalLndPhonebookValue 0x101F7877 williamr@2: #define KUidUsimAppAdnPhonebookValue 0x101F7878 williamr@2: #define KUidIccGlobalFdnPhonebookValue 0x101FB2AF williamr@2: williamr@2: const TUid KUidIccPhonebookNotSpecified = {KUidIccPhonebookNotSpecifiedValue}; williamr@2: const TUid KUidIccGlobalAdnPhonebook = {KUidIccGlobalAdnPhonebookValue}; williamr@2: const TUid KUidIccGlobalSdnPhonebook = {KUidIccGlobalSdnPhonebookValue}; williamr@2: const TUid KUidIccGlobalLndPhonebook = {KUidIccGlobalLndPhonebookValue}; williamr@2: const TUid KUidUsimAppAdnPhonebook = {KUidUsimAppAdnPhonebookValue}; williamr@2: const TUid KUidIccGlobalFdnPhonebook = {KUidIccGlobalFdnPhonebookValue}; williamr@2: williamr@2: williamr@2: /** williamr@2: * Types of cancel requests for the asynchronous server requests. williamr@2: * williamr@2: * @see RPhoneBookSession::CancelRequest williamr@2: */ williamr@2: enum TPhonebookSyncRequestCancel williamr@2: { williamr@2: /** Cancel the asynchronous RPhoneBookSession::DoSynchronisation() request */ williamr@2: EDoSynchronisationCancelClient, williamr@2: williamr@2: /** Cancel the asynchronous RPhoneBookSession::DeleteContact() request */ williamr@2: ESyncDeleteCntFromICCCancelClient, williamr@2: williamr@2: /** Cancel the asynchronous RPhoneBookSession::WriteContact() request */ williamr@2: ESyncWriteCntToICCCancelClient, williamr@2: williamr@2: /** Cancel the asynchronous RPhoneBookSession::NotifyPhBkCacheStateChange() request */ williamr@2: ESyncNotifyCacheStateChangeCancelClient williamr@2: }; williamr@2: williamr@2: williamr@2: /** williamr@2: * Class to hold the contact field formats. williamr@2: * williamr@2: * @publishedAll williamr@2: * @released williamr@2: */ williamr@2: class TContactFieldFormat williamr@2: { williamr@2: public: williamr@2: TContactFieldFormat(TInt aLength, TInt aCount, TBool aDisplayed); williamr@2: williamr@2: public: williamr@2: /** The maximum length (i.e. number of characters) of the field. If the field is williamr@2: not a string type this attribute should be ignored. */ williamr@2: TInt iLength; williamr@2: williamr@2: /** The maximum number of instances of this field within an item. This is set to williamr@2: -1 if this is unlimited. */ williamr@2: TInt iCount; williamr@2: williamr@2: /** Indicates whether this is displayed or hidden. */ williamr@2: TBool iDisplayed; williamr@2: }; williamr@2: williamr@2: williamr@2: // williamr@2: // Forward declare the internal data storage class. williamr@2: // williamr@2: class CSyncClientData; williamr@2: williamr@2: /** williamr@2: * Provides the CPhoneBookSyncPlugin client access to a session with the williamr@2: * Phonebook Synchronizer Server. williamr@2: * williamr@2: * A handle to an RPhoneBookSession enables the plug-in class to perform williamr@2: * IPC communications with the server. williamr@2: * williamr@2: * @publishedAll williamr@2: * @released williamr@2: */ williamr@2: class RPhoneBookSession : public RSessionBase williamr@2: { williamr@2: public: williamr@2: /** williamr@2: * Structure holding the template ID and buffer size. The client has williamr@2: * no need to use this structure. williamr@2: * williamr@2: * @deprecated williamr@2: */ williamr@2: struct TTemplateAndBufferSize williamr@2: { williamr@2: TContactItemId templateId; williamr@2: TInt bufferSize; williamr@2: }; williamr@2: williamr@2: /** williamr@2: * The synchronisation mode for phonebooks when the server starts. williamr@2: */ williamr@2: enum TPhonebookSyncMode williamr@2: { williamr@2: /** Automatic synchronisation will be performed. */ williamr@2: EAutoCurrentIcc, williamr@2: williamr@2: /** Automatic synchronisation will only be performed if the current ICC is williamr@2: the same as the last ICC to be synchonised. */ williamr@2: EAutoSameIcc, williamr@2: williamr@2: /** Manual synchronisation will be performed when requested. */ williamr@2: EManual williamr@2: }; williamr@2: williamr@2: /** williamr@2: * The phonebook cache state. williamr@2: */ williamr@2: enum TSyncState williamr@2: { williamr@2: /** The server has not yet populated the Contacts Database. */ williamr@2: EUnsynchronised, williamr@2: williamr@2: /** The server has finished populating the Contacts Database. */ williamr@2: ECacheValid, williamr@2: williamr@2: /** The server encountered an error populating the Contacts Database. */ williamr@2: EErrorDuringSync williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Specifies format of phonebook fields within an ICC phonebook entry. williamr@2: * williamr@2: * @publishedAll williamr@2: * @released williamr@2: */ williamr@2: class TContactFieldsV1 williamr@2: { williamr@2: public: williamr@2: /** williamr@2: * Enumeration to describe the version ID of the Phonebook Synchronizer. williamr@2: */ williamr@2: enum TContactFieldsExtensionId williamr@2: { williamr@2: /** Phonebook Synchronizer version 1 */ williamr@2: KPhBkSyncTContactFieldsV1, williamr@2: williamr@2: /** Phonebook Synchronizer version 2 */ williamr@2: KPhBkSyncTContactFieldsV2, williamr@2: williamr@2: /** Phonebook Synchronizer version 3 */ williamr@2: KPhBkSyncTContactFieldsV3 williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Returns the Phonebook Synchronizer API extension number of the class. williamr@2: * williamr@2: * @return The version ID from TContactFieldsExtensionId. williamr@2: */ williamr@2: IMPORT_C TInt ExtensionId() const; williamr@2: williamr@2: /** williamr@2: * Standard constructor. williamr@2: */ williamr@2: IMPORT_C TContactFieldsV1(); williamr@2: williamr@2: public: williamr@2: /** The format of the name field within an ICC phonebook entry. */ williamr@2: TContactFieldFormat iNameField; williamr@2: williamr@2: /** The format of the number field within an ICC phonebook entry. */ williamr@2: TContactFieldFormat iNumberField; williamr@2: williamr@2: /** The format of the ICC slot number field within an ICC phonebook entry. */ williamr@2: TContactFieldFormat iIccSlotField; williamr@2: williamr@2: protected: williamr@2: TInt iExtensionId; williamr@2: }; williamr@2: williamr@2: /** williamr@2: * A packaged instance of TContactFieldsV1. williamr@2: */ williamr@2: typedef TPckg TContactFieldsV1Pckg; williamr@2: williamr@2: /** williamr@2: * Specifies format of phonebook fields within an UICC phonebook entry williamr@2: * williamr@2: * @publishedAll williamr@2: * @released williamr@2: */ williamr@2: class TContactFieldsV2 : public TContactFieldsV1 williamr@2: { williamr@2: public: williamr@2: IMPORT_C TContactFieldsV2(); williamr@2: williamr@2: public: williamr@2: /** The format of any additional number fields within an ICC phonebook entry. */ williamr@2: TContactFieldFormat iAdditionalNumString; williamr@2: williamr@2: /** The format of group field within an ICC phonebook entry. */ williamr@2: TContactFieldFormat iGroupField; williamr@2: williamr@2: /** The format of email field within an ICC phonebook entry. */ williamr@2: TContactFieldFormat iEmailField; williamr@2: williamr@2: /** The UID of the phonebook. */ williamr@2: TUid iPhonebook; williamr@2: }; williamr@2: williamr@2: /** williamr@2: * A packaged instance of TContactFieldsV2. williamr@2: */ williamr@2: typedef TPckg TContactFieldsV2Pckg; williamr@2: williamr@2: williamr@2: /** williamr@2: * Specifies additional format information for phonebook fields within a williamr@2: * UICC phonebook entry. williamr@2: * williamr@2: * @publishedAll williamr@2: * @released williamr@2: */ williamr@2: class TContactFieldsV3 : public TContactFieldsV2 williamr@2: { williamr@2: public: williamr@2: IMPORT_C TContactFieldsV3(); williamr@2: williamr@2: public: williamr@2: /** The format of an addition number's text field within an ICC phonebook entry. */ williamr@2: TContactFieldFormat iAdditionalNumAlphaString; williamr@2: williamr@2: /** The format of the second name field within an ICC phonebook entry. */ williamr@2: TContactFieldFormat iSecondNameField; williamr@2: }; williamr@2: williamr@2: /** williamr@2: * A packaged instance of TContactFieldsV3. williamr@2: */ williamr@2: typedef TPckg TContactFieldsV3Pckg; williamr@2: williamr@2: williamr@2: /** williamr@2: * The phonebook ID type requested from a phonebook. There are two types of IDs williamr@2: * (group IDs and template IDs). williamr@2: * williamr@2: * @see RPhoneBookSession::GetPhoneBookId() williamr@2: */ williamr@2: enum TSyncIdType williamr@2: { williamr@2: /** Used to allocate a new entry to the right group in the Contacts Database. */ williamr@2: ESyncGroupId, williamr@2: williamr@2: /** Used to define new ICC entries in the Contacts Database. */ williamr@2: ESyncTemplateId williamr@2: }; williamr@2: williamr@2: public: williamr@2: IMPORT_C RPhoneBookSession(); williamr@2: IMPORT_C TInt Connect(); williamr@2: IMPORT_C void Close(); williamr@2: IMPORT_C TVersion Version() const; williamr@2: IMPORT_C TInt ShutdownServer (TBool aUnconditionally); williamr@2: williamr@2: // williamr@2: // Single (ADN) phonebook support and functions not requiring a phonebook UID. williamr@2: // williamr@2: IMPORT_C void DoSynchronisation(TRequestStatus& aReqStatus); williamr@2: IMPORT_C TInt ValidateContact(MContactSynchroniser::TValidateOperation aOperation, TContactItemId aId); williamr@2: IMPORT_C void WriteContact(TRequestStatus& aReqStatus, CContactICCEntry& aContactItem, williamr@2: TInt& aSlotNumber); williamr@2: IMPORT_C void DeleteContact(TRequestStatus& aReqStatus, TContactItemId aId); williamr@2: IMPORT_C TInt GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType); williamr@2: IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot); williamr@2: IMPORT_C TInt GetContactFormat(TDes8& aContactFields); williamr@2: IMPORT_C TInt GetSyncMode(TPhonebookSyncMode& aSyncMode); williamr@2: IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode); williamr@2: IMPORT_C TInt GetPhoneBookCacheState(TSyncState& aState); williamr@2: IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel); williamr@2: IMPORT_C TInt GetLastSyncError(TInt& aError); williamr@2: IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus& aStatus); williamr@2: IMPORT_C TInt GetNumSlots(TInt& aNumSlots) const; williamr@2: IMPORT_C void GetFreeSlotsL(RArray& aFreeSlots) const; williamr@2: IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId& aId) const; williamr@2: williamr@2: // williamr@2: // Multiple phonebooks support. These should be used in preference to the above williamr@2: // ADN specific versions. williamr@2: // williamr@2: IMPORT_C void DoSynchronisation(TRequestStatus& aReqStatus, TUid aPhonebookUid); williamr@2: IMPORT_C void WriteContact(TRequestStatus& aReqStatus, CContactICCEntry& aContactItem, williamr@2: TInt& aSlotNumber, TUid& aPhonebookUid); williamr@2: IMPORT_C TInt GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType, TUid aPhonebookUid); williamr@2: IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot, TUid aPhonebookUid); williamr@2: IMPORT_C TInt GetSyncMode(TPhonebookSyncMode& aSyncMode, TUid aPhonebookId); williamr@2: IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode, TUid aPhonebookId); williamr@2: IMPORT_C TInt GetPhoneBookCacheState(TSyncState& aState, TUid aPhonebookId); williamr@2: IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel, TUid aPhonebookId); williamr@2: IMPORT_C TInt GetLastSyncError(TInt& aError, TUid aPhonebookId); williamr@2: IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus& aStatus, TUid aPhonebookId); williamr@2: IMPORT_C TInt GetNumSlots(TInt& aNumSlots, TUid aPhonebookId) const; williamr@2: IMPORT_C void GetFreeSlotsL(RArray& aFreeSlots, TUid aPhonebookId) const; williamr@2: IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId& aId, TUid aPhonebookId) const; williamr@2: williamr@2: // williamr@2: // Memory checking functionality for Debug builds only. williamr@2: // williamr@2: IMPORT_C TInt __DbgMarkHeap(); williamr@2: IMPORT_C TInt __DbgCheckHeap(TInt aCount); williamr@2: IMPORT_C TInt __DbgMarkEnd(TInt aCount); williamr@2: IMPORT_C TInt __DbgFailNext(TInt aCount); williamr@2: williamr@2: private: williamr@2: RPhoneBookSession(const RPhoneBookSession& aSession); williamr@2: williamr@2: private: williamr@2: /* Temporary data used by the session. */ williamr@2: CSyncClientData* iData; williamr@2: }; williamr@2: williamr@2: #endif