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 <e32std.h>
williamr@2: #include <cntdef.h>
williamr@2: #include <cntdb.h>
williamr@2: #include <cntitem.h>
williamr@2: #include <cntfldst.h>
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<TContactFieldsV1>  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<TContactFieldsV2>  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<TContactFieldsV3>  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<TInt>& 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<TInt>& 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