// 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 <e32std.h>

#include <cntdef.h>

#include <cntdb.h>

#include <cntitem.h>

#include <cntfldst.h>

/**

 *  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<TContactFieldsV1>  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<TContactFieldsV2>  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<TContactFieldsV3>  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<TInt>& 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<TInt>& 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