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