// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __CNTVIEWBASE_H__

#define __CNTVIEWBASE_H__

// System includes

#include <e32std.h>

#include <s32mem.h>

#include <cntdb.h>

// Classes referenced

class CViewContactExtension;

class CContactViewBase;

class CContactRemoteViewNotifier;

class CIdleContactSorter;

class CContactViewFindConfigInterface;

class CViewContactSortPlugin;

class TSortPluginViewParams;

/** View preferences for sorted contact views.

This is used to specify the types of contact item that should be sorted and 

included in the view and the behaviour for items that cannot be sorted because 

they do not have content in any of the fields specified in the view's sort 

order.

The default behaviour is to include contact cards only and to sort contact 

cards without content in any of the sort order fields using the first available 

field containing any text.

The view preferences for all concrete contact view classes can be retrieved 

using their implementation of CContactViewBase::ContactViewPreferences(). 

The view preferences are set during construction of a CContactLocalView. 

@publishedAll

@released

*/

enum TContactViewPreferences

	{

	/** Only contact cards (of type KUidContactCard or KUidContactOwnCard) are included 

	in the view. This is the default. */

	EContactsOnly					=0x00000000,

	/** Only contact groups (of type KUidContactGroup) are included in the view. */

	EGroupsOnly						=0x00000001, 

	/** Contact groups and contact cards (of type KUidContactGroup, KUidContactCard 

	or KUidContactOwnCard) are included in the view. */

	EContactAndGroups				=0x00000002, 

	/** Excludes contact items from the view which don't have content in any of the 

	fields specified in the sort order. */

	EIgnoreUnSorted					=0x00000004, 

	/** Includes contacts in the view which don't have content in any of the fields 

	specified in the sort order. These contacts are placed in an unsorted contact 

	list which is located before the sorted list. */

	EUnSortedAtBeginning			=0x00000008, 

	/** Includes contacts in the view which don't have content in any of the fields 

	specified in the sort order. These contacts are placed in an unsorted contact 

	list which is located after the sorted list. */

	EUnSortedAtEnd					=0x00000010, 

	/** Fields containing a single white space only are treated as empty, and therefore 

	unsortable. */

	ESingleWhiteSpaceIsEmptyField	=0x00000020,

	/** Only ICC entries (of type KUidContactICCEntry) are included in the view. */

	EICCEntriesOnly					=0x00000040, 

	/** Only contact cards and ICC entries (of type KUidContactCard, KUidContactOwnCard 

	or KUidContactICCEntry) are included in the view. */

	EICCEntriesAndContacts			=0x00000080,

	/** Only contact cards (of type KUidContactCard) are included 

	in the view. Own card not included. */

    EContactCardsOnly				=0x00000100

	};

class TContactViewEvent

/** Identifies a contact view event.

Sent by contact views when notifying their observers of an event.

@see MContactViewObserver::HandleContactViewEvent() 

@publishedAll

@released

*/

	{

public:

	/** Identifies the event's type. */

	enum TEventType

		{

		/** The observed view's state has changed from EReady to either ENotReady or EInitializing, 

		so is not available for use. */

		EUnavailable,

		/** The observed view's state has changed from ENotReady or EInitializing to EReady 

		so is available for use. */

		EReady,

		/** The observed view's sort order has changed, so observer views need to update 

		themselves. */

		ESortOrderChanged,

		/** An error occurred when sorting the observed view or when appending an observer 

		to its observer array. 

		The error code is provided in iInt. */

		ESortError,

		/** An error occurred in the contacts server.

		The error code is provided in iInt. */

		EServerError,

		/** An error occurred when setting the range for a CContactSubView.

		The error code is provided in iInt. */

		EIndexingError,

		/** An item has been added to the observed view. 

		The ID of the added item is provided in iContactId and the index into the 

		observed view of the added item is provided in iInt. 

		Exception from this are the first version of CContactFindView, CContactSubView and

		CContactGroupView classes.

		For these classes, iInt has KErrNone value */

		EItemAdded,

		/** An item has been removed from the observed view. 

		The ID of the removed item is provided in iContactId and the index into the 

		observed view of the item is provided in iInt. 

		Exception from this are the first version of CContactFindView and CContactSubView classes.

		For these classes, iInt has KErrNone value */

		EItemRemoved,

		/** A change has occurred in a contact group, for instance a contact item has been 

		moved into or out of the group.

		The ID of the group affected is provided in iContactId. */

		EGroupChanged

		};

public:

	inline TContactViewEvent();

	inline TContactViewEvent(TEventType aEventType,TInt aInt = KErrUnknown,TContactItemId aContactId = KErrUnknown); 

public:

	/** The type of event. */

	TEventType iEventType;

	/** The error code (where relevant) or the index of the contact item added to/removed 

	from the underlying view. */

	TInt iInt; 

	/** The ID of the contact item that has been added or removed or the group ID, where 

	relevant. */

	TContactItemId iContactId;//ContactId that has been added / removed if relevant.

	};

struct TContactIdWithMapping

/** A struct used internally by filtered and group views to pair a contact item 

ID and its index into the underlying view. 

@publishedAll

@released

*/

	{

	/** The contact item's ID. */

	TContactItemId iId;

	/** The index of the item into the view's underlying view. */

	TInt iMapping;

	};

class MContactViewObserver

/** The interface for a contact view observer.

Objects that need to observe a contact view should implement this interface. 

The view observer should be passed to the observed view's OpenL() or Open() 

function. This adds the observer to the view's observer array: a view can 

have more than one observer. The observers receive notifications when the 

observed view becomes ready for use and when changes occur in it.

Many contact view classes implement this interface to observe an underlying 

view. They in turn send notification to any objects observing them.

@see CContactViewBase::NotifyObservers()

@see CContactViewBase::NotifyObserverAsync() 

@publishedAll

@released

*/

	{

public:

	/** Handles an event in an observed contact view.

	@param aView The contact view causing the notification.

	@param aEvent The event. */

	virtual void HandleContactViewEvent(const CContactViewBase& aView,const TContactViewEvent& aEvent)=0;

	};

class RContactViewSortOrder

/** Specifies the sort order for a contact view.

It is implemented as an array of TFieldType UIDs, which define the fields 

whose contents are used to sort on, and their order.

The sort order for all concrete contact view classes can be retrieved using 

their implementation of CContactViewBase::SortOrderL(). The sort order is 

set during construction of local and remote views. 

@publishedAll

@released

*/

	{

public:

	IMPORT_C RContactViewSortOrder();

	IMPORT_C void Close();

	IMPORT_C void CopyL(const RContactViewSortOrder& aSortOrder);

	IMPORT_C void InternalizeL(RReadStream& aStream);

	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

	IMPORT_C TInt ExternalizedSize() const;

	IMPORT_C TBool operator==(const RContactViewSortOrder& aSortOrder) const;

	inline void AppendL(TFieldType aField);

	inline TFieldType operator[](TInt aIndex) const;

	inline TInt Count() const; 

private:

	RArray<TFieldType> iFields;

	TInt iSpare;

	TInt32 iSpare2;

	TInt32 iSpare3;

	};

/**

Wrapper around RArray, to container TTextFieldMinimal buffers.

Features: minimum size 1, easy resize of array, persistent last counted total.

@internalComponent

@released

*/

class RFieldBufferArray : public RArray<CContactDatabase::TTextFieldMinimal>

    {

public:

	explicit RFieldBufferArray();

	void ResizeL(TInt aNewSize);

	void ZeroAll();

	TInt NewTotal();

	TInt LastTotal() const;

private:

	TInt iTotalLength;

    };

class CViewContact : public CBase

/** The representation of a contact item used in contact views.

It stores the contact item ID and other information. This includes a buffer 

holding the contents of all the item's fields, an array of indexes into the 

buffer indicating the start position of each field and a hint bit field (a 

combination of CContactDatabase::TContactViewFilter values) which is used 

in filtered views.

The fields are defined by the view's sort order (RContactViewSortOrder). 

@publishedAll

@released

*/

	{

public:

	/** Defines whether the contact view item is a contact group. */

	enum TViewContactType

		{

		/** The contact view item is not a contact group. */

		EContactItem,

		/** The contact view item is a contact group (CContactGroup). */

		EGroup

		};

	IMPORT_C CViewContact(TContactItemId aId);

	IMPORT_C static CViewContact* NewL(const CViewContact& aContact);

	IMPORT_C static CViewContact* NewLC(TContactItemId aId);

	IMPORT_C static CViewContact* NewL(TContactItemId aId, TInt aLength);

	static CViewContact* NewLC(RReadStream& aStream);

	IMPORT_C ~CViewContact();

	IMPORT_C void InternalizeL(RReadStream& aStream);

	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

	IMPORT_C TInt ExternalizedSize() const;

	IMPORT_C TInt FieldCount() const;

	IMPORT_C TPtrC Field(TInt aPosition) const;

	IMPORT_C TBool ContactMatchesFilter(TInt aFilter) const;

	IMPORT_C void AddFieldL(const TDesC& aField);

	IMPORT_C TBool IsSortable() const;

	IMPORT_C void SetFirstFieldForBlankContactL(const TDesC& aFirstField);

	IMPORT_C void Reset();

	IMPORT_C TInt ContactHint() const;

	IMPORT_C void SetContactHint(TInt aHint);

	IMPORT_C TUid ContactTypeUid() const;

	IMPORT_C void SetContactTypeUid(TUid aUid);

	inline TContactItemId Id() const;

	inline TViewContactType ContactType() const;

public:

	inline void SetId(TContactItemId aId);

	inline void SetContactType(CViewContact::TViewContactType aContactType);

	static TBool HintFieldMatchesFilter(TInt aHintField, TInt aFilter);

	TPtrC FindFirstPopulatedField(TInt aOffset, TInt& aFoundPosition) const;

    IMPORT_C void  ChangeToLightweightObject();

    TBool IsLightweightObject() const;	

    void  CopyL(const CViewContact& aContact);

private: 

	void ConstructL(TInt aLength = 0);

	void ConstructL(const CViewContact& aContact);

	friend class CContactViewBase;

private:

	TContactItemId iId;

	TViewContactType iContactType;

	CViewContactExtension* iExtension;

	RArray<TInt> iTextIndexes;

	};

/*

 * A view can be named or un-named. An un-named view has a fixed sort order - the 

 * only way to change this is by closing the object and creating a new one with a 

 * different order. Named views may have their sort order changed. When this is 

 * done, first all observers will be informed that the view is 'unavailable'. This

 * notification will be followed by 'sort order changed' and 'ready'. Only once 

 * the 'ready' notification has been received may the view be used again.

 */

class CContactViewBase : public CBase

/** The abstract base class for all contact view classes.

All contact views operate asynchronously, so users of the view must observe 

it, by implementing the MContactViewObserver interface. Immediately after 

construction, views are not in a usable state (the underlying data may be 

being sorted, for instance). Only after the user has received a TContactViewEvent::EReady 

event may the view be used.

View observers are also notified when changes occur, for instance when the 

view's state changes (see TState), when an error occurs, or when an item is 

added or removed. 

@publishedAll

@released

*/

	{

public:

	class CContactViewBaseExtension : public CBase

	/** An extension class that holds member data added in v7.0s.

	It was created for binary compatibility purposes. 

	@internalComponent

	@released */

		{

		public:

			static CContactViewBaseExtension* NewL();

			~CContactViewBaseExtension();

		private:

			CContactViewBaseExtension();

			void ConstructL();

		public:

			/** A standard error code that is passed to view observers by NotifyObservers() 

			(unless its value is KErrNone). */

			TInt iError;

			/** The UID of the view's find configuration plug-in.

			On construction, this is initialised to KNullUid.

			The plug-in is loaded when ContactsMatchingCriteriaL(), ContactsMatchingPrefixL() 

			or MatchesCriteriaL() is called. */

			TUid iFindPluginUid;

			/** The UID of the view's sort plug-in. */

			TUid iSortPluginUid;

		private:

			CContactViewFindConfigInterface*	iFindPluginImpl;

			CViewContactSortPlugin*				iSortPluginImpl;

			TCollationMethod					iCollationMethod;

			friend class CContactViewBase;

		};

	class TVirtualFunction1Params

	/** Holds the two parameters passed to the helper method GetContactIdsL() from 

	the reserved function CContactViewBase_Reserved_1(). It has an inline constructor 

	to initialise the data members. 

	@publishedAll

	@released */

		{

		public:

		   /** Inline constructor to initialize member data

			  @param aIndexes Pointer to an array of indexes in a view

	          @param aIdArray Pointer to array of contact IDs  */

			inline TVirtualFunction1Params(const CArrayFix<TInt>* aIndexes, CContactIdArray* aIdArray) :iIndexes(aIndexes), iIdArray(aIdArray){};

			/** Pointer to an array of indexes in a view  */

			const CArrayFix<TInt>* iIndexes;

			/** Pointer to array of contact IDs  */

			CContactIdArray* iIdArray;

		};

	class TVirtualFunction2Params

	/** Holds the two parameters passed to the method GetContactsMatchingFilterL() 

	from the reserved function CContactViewBase_Reserved_1(). It has an inline 

	constructor to initialise the data members.

	*/

		{

		public:

		   /** Inline constructor to initialize member data.

			  @param aFilter Filter for the contacts

	          @param aMatchingContacts Contacts matching a particular criterion  */

			inline TVirtualFunction2Params(TInt aFilter, RArray<TContactIdWithMapping>& aMatchingContacts) : iFilter(aFilter), iMatchingContacts(aMatchingContacts){};

		public:

			/** Filter for the contacts. */

			TInt iFilter;

			/** List of contacts matching the criteria. */

			RArray<TContactIdWithMapping>& iMatchingContacts;

		};

	/** Search type.

	This controls whether a search term can occur anywhere in a contact item field, 

	or just at the beginning of the field. */

	enum TSearchType

		{

		/** The search uses full wildcard matching so that the search string can occur anywhere 

		in the item's fields. */

		EFullSearch,

		/** The search uses partial wildcard matching so that the search string can only 

		occur at the beginning of the item's fields. */

		EPrefixSearch

		};

	/** Identifies the functions that have been added to CContactViewBase, or that 

	may be added in the future. This identifier is passed to the reserved virtual 

	function CContactViewBase_Reserved_1() and enables the addition of new virtual 

	methods without breaking binary compatibility. */

	enum TFunction

		{

		/** Identifies the function CContactViewBase::GetContactIdsL(). */

		ECContactViewBaseVirtualFunction1,

		/** Identifies the function CContactViewBase::GetContactsMatchingFilterL(). */

		ECContactViewBaseVirtualFunction2,

		// communication with Sort Plug-in

		/** Identifies the function CContactViewBase::InsertContactInView(). */

		ECContactViewBaseVirtualFunction3,

		};

protected:

	/** Defines the contact view states. */

	enum TState

		{

		/** The view is initialising.

		This is the view's state immediately after construction or after a significant change 

		(e.g CurrentDatabaseChanged or UnknownChanges),	indicating that it can't be used yet. */

		EInitializing,

		/** The view is ready to be used. */

		EReady,

		/** The view is not ready to be used, for instance immediately after the sort order 

		has changed, or after an error has occurred. */

		ENotReady

		};

	class TVirtualFunction3Params

		/** Holds the two parameters passed to the method InsertContactInView() from the 

		reserved function CContactViewBase_Reserved_1(). It has an inline 

		constructor to initialise the data members.

		*/

		{

		public:

			inline TVirtualFunction3Params(RPointerArray<CViewContact>& aContacts, const CViewContact* aNewContact) :iContacts(aContacts), iNewContact(aNewContact){};

			RPointerArray<CViewContact>&	iContacts;

			const CViewContact*				iNewContact;

		};

public:

	IMPORT_C void OpenL(MContactViewObserver& aObserver);

	IMPORT_C TInt Open(MContactViewObserver& aObserver);

	IMPORT_C TBool Close(const MContactViewObserver& aObserver);

	/** Returns the contact item ID at the specified index into the view.

	@capability ReadUserData

	@param aIndex Index of the contact item ID into the view.

	@return The contact item ID. */

	virtual TContactItemId AtL(TInt aIndex) const=0; 

	/** Returns the contact item at the specified index into the view.

	@capability ReadUserData

	@param aIndex Index of the contact item into the view.

	@return The contact item. */

	virtual const CViewContact& ContactAtL(TInt aIndex) const =0;

	/** Returns the number of contact items in the view.

	@capability ReadUserData

	@return The number of contact items in the view. */

	virtual TInt CountL() const=0;

	/** Returns the index into the view of the specified contact item.

	@capability ReadUserData

	@param aId The contact item ID to search for.

	@return The index into the view of the contact item ID, or KErrNotFound if 

	no matching ID can be found. */

	virtual TInt FindL(TContactItemId aId) const=0;

	/** Returns a descriptor containing the contents of all fields for an item in the view.

	The field separator is used to separate the contents of each field. It is 

	not appended to the last field.

	@capability ReadUserData

	@param aIndex The index of the contact item into the view.

	@param aSeparator The string to use to separate the fields.

	@return Pointer to the contact item descriptor. */

	virtual HBufC* AllFieldsLC(TInt aIndex,const TDesC& aSeparator) const=0;

	IMPORT_C virtual void ContactsMatchingCriteriaL(const MDesCArray& aFindWords,RPointerArray<CViewContact>& aMatchedContacts);

	/** Gets the view preferences.

	@capability ReadUserData

	@return The view preferences. */

	virtual TContactViewPreferences ContactViewPreferences()=0;

	/** Gets the view's sort order.

	@capability ReadUserData

	@return The sort order. */

	virtual const RContactViewSortOrder& SortOrderL() const = 0;

	IMPORT_C virtual void ContactsMatchingPrefixL(const MDesCArray& aFindWords, RPointerArray<CViewContact>& aMatchedContacts);

	//This is a reserved virtual exported function that is used for BC proofing against present 

	//and future additions of new exported virtual functions. Existing exported virtual methods 

	//that broke BC are now non-virtual exported helper functions called from this method. 

	//All derived classes of CContactViewBase that are public must mandatorily 

	//implement this reserved exported virtual method.