williamr@4: // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@4: // All rights reserved.
williamr@4: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@4: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@4: //
williamr@4: // Initial Contributors:
williamr@4: // Nokia Corporation - initial contribution.
williamr@4: //
williamr@4: // Contributors:
williamr@4: //
williamr@4: // Description:
williamr@4: //
williamr@4: 
williamr@4: #ifndef __CNTVIEWSORTPLUGIN_H__
williamr@4: #define __CNTVIEWSORTPLUGIN_H__
williamr@4: 
williamr@4: #include <e32base.h>
williamr@4: #include "ecom/ecom.h"		// For REComSession
williamr@4: #include <cntviewbase.h>
williamr@4: 
williamr@4: 
williamr@4: 
williamr@4: /** The UID of the ECOM contact view sort interface. 
williamr@4: @publishedAll
williamr@4: @released
williamr@4: */
williamr@4: const TUid KCntSortPluginInterfaceUid = {0x10200FBD};
williamr@4: 
williamr@4: /** The name of the default ECOM contact view sort plug-in. 
williamr@4: @publishedAll
williamr@4: @released
williamr@4: */
williamr@4: _LIT8(KViewSortPluginDefaultName, "/default");
williamr@4: 
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: 
williamr@4: //********************************************************************************************
williamr@4: //
williamr@4: // Parameter blocks passed to Sort Plug-in's NewL, where they should be copied.
williamr@4: //
williamr@4: 
williamr@4: /** The UID for the sort plug-in parameters (TSortPluginParams and 
williamr@4: TSortPluginViewParamsRev1) that are used to pass data to the ECOM plug-in DLL. 
williamr@4: @publishedPartner
williamr@4: @released
williamr@4: */
williamr@4: const TUid KCntSortPluginViewParamsRev1Uid = {0x10201325};
williamr@4: 
williamr@4: /** Information block holding the sort plug-in's parameters.
williamr@4: This is passed to the plug-in instance from the contact view via 
williamr@4: TSortPluginParams::iViewSortParams.
williamr@4: 
williamr@4: It has an inline constructor to initialise the data members.
williamr@4: 
williamr@4: @publishedPartner
williamr@4: @released */
williamr@4: class TSortPluginViewParamsRev1
williamr@4: 	{
williamr@4: public:	// constructors
williamr@4: 	/** Empty default constructor. */
williamr@4: 	TSortPluginViewParamsRev1()
williamr@4: 			{}
williamr@4: 	/** Inline constructor, initialises all data members. 
williamr@4: 	
williamr@4: 	@param aViewPreferences The view's view preferences.
williamr@4: 	@param aCompareViewContactsL A pointer to a default function that is used 
williamr@4: 	to compare two contact items. The plug-in may call this function from its 
williamr@4: 	implementation of SortCompareViewContactsL().
williamr@4: 	@param aIsSortable A pointer to a default function that is used to test 
williamr@4: 	whether a CViewContact is sortable. The plug-in may call this function 
williamr@4: 	from its implementation of ViewContactIsSortable(). */
williamr@4: 	TSortPluginViewParamsRev1(TContactViewPreferences aViewPreferences,
williamr@4: 		TInt(*aCompareViewContactsL)(const CViewContact& aFirst, const CViewContact& aSecond),
williamr@4: 		TBool(*aIsSortable)(const CViewContact& aViewContact)) :
williamr@4: 		iViewPreferences(aViewPreferences), iCompareViewContactsL(aCompareViewContactsL), iIsSortable(aIsSortable)
williamr@4: 			{}
williamr@4: public:
williamr@4: 	// Fields in all versions
williamr@4: 	/** The view's view preferences.*/
williamr@4: 	TContactViewPreferences		iViewPreferences;		// preferences of view (at creation)
williamr@4: 
williamr@4: 	// Default implementations of Compare and IsSortable methods
williamr@4: 	// that the sort Plugin can call.
williamr@4: 	// Must not be NULL !
williamr@4: 	/** A pointer to a default function that is used to compare two contact 
williamr@4: 	items. The plug-in may call this function from its implementation of 
williamr@4: 	SortCompareViewContactsL(). */
williamr@4: 	TInt (*iCompareViewContactsL)(const CViewContact& aFirst, const CViewContact& aSecond);
williamr@4: 	/** A pointer to a default function that is used to test whether a contact item 
williamr@4: 	is sortable. The plug-in may call this function from its implementation of 
williamr@4: 	ViewContactIsSortable(). */
williamr@4: 	TBool(*iIsSortable)(const CViewContact& aViewContact);
williamr@4: 	};
williamr@4: 
williamr@4: 
williamr@4: /** A data class used to pass initialization information to 
williamr@4: CViewContactSortPlugin::NewL().
williamr@4: 
williamr@4: @publishedPartner
williamr@4: @released */
williamr@4: class TSortPluginParams
williamr@4: 	{
williamr@4: public:	// constructors
williamr@4: 	/** Empty default constructor. */
williamr@4: 	TSortPluginParams() {}
williamr@4: 	
williamr@4: 	/** Inline constructor, initialises all data members.
williamr@4: 
williamr@4: 	The parameter revision UID is initialised to KCntSortPluginViewParamsRev1Uid.
williamr@4: 	@param aInterfaceUid Interface UID as specified in the INTERFACE_INFO resource struct, 
williamr@4: 	required by ECOM.
williamr@4: 	@param aImplementationUid Implementation UID, as specified in the IMPLEMENTATION_INFO 
williamr@4: 	resource struct, required by ECOM.
williamr@4: 	@param aViewSortParams View sort parameters pointer. This object should match the 
williamr@4: 	parameter revision UID value. */
williamr@4: 	TSortPluginParams(TUid aInterfaceUid, TUid aImplementationUid, TSortPluginViewParamsRev1* aViewSortParams) : 
williamr@4: 		iParametersRevision(KCntSortPluginViewParamsRev1Uid), iInterfaceUid(aInterfaceUid), 
williamr@4: 		iImplementationUid(aImplementationUid), iViewSortParams(aViewSortParams)
williamr@4: 	{}
williamr@4: public:
williamr@4: 	/** A UID that identifies the revision of the structure holding 
williamr@4: 	the view's sort parameters. A value of KCntSortPluginViewParamsRev1Uid 
williamr@4: 	indicates TSortPluginViewParamsRev1. */
williamr@4: 	TUid	iParametersRevision;	
williamr@4: 
williamr@4: 	// Information for ECOM to load the correct plug-in
williamr@4: 	/** Interface UID as specified in the INTERFACE_INFO resource struct, 
williamr@4: 	required by ECOM.*/
williamr@4: 	TUid	iInterfaceUid;
williamr@4: 	/** Implementation UID, as specified in the IMPLEMENTATION_INFO 
williamr@4: 	resource struct, required by ECOM.*/
williamr@4: 	TUid	iImplementationUid;
williamr@4: 
williamr@4: 	// information block from Contact View
williamr@4: 	/** View sort parameters pointer. This object should match the 
williamr@4: 	parameter revision UID value.*/
williamr@4: 	TAny*	iViewSortParams;
williamr@4: 	};
williamr@4: 
williamr@4: 
williamr@4: 
williamr@4: /** An interface class that enables implementers to configure the way in which 
williamr@4: contacts are sorted in a contact view.
williamr@4: 
williamr@4: This is an abstract base class that will be derived from.
williamr@4: 
williamr@4: @publishedPartner
williamr@4: @released */
williamr@4: class CViewContactSortPlugin : public CBase
williamr@4: 	{
williamr@4: public:
williamr@4: 	/** Identifies the type of sort operation to SortStart(). 
williamr@4: 	
williamr@4: 	@publishedPartner
williamr@4: 	@released */
williamr@4: 	enum TSortStartTypes {
williamr@4: 		/** No sort is in progress. */
williamr@4: 		ESortNull = 0,
williamr@4: 		/** A full sort or re-sort. */
williamr@4: 		ESortStartFull,	
williamr@4: 		/** A single contact has been inserted or changed. */
williamr@4: 		ESortStartInsertOne,
williamr@4: 		/** Multiple contacts have been added. For example, ICC contacts arrived in a 
williamr@4: 		mixed view (one that also includes contacts from the phone's memory). */
williamr@4: 		ESortStartInsertMultiple,
williamr@4: 		// other values are reserved
williamr@4: 		};
williamr@4: 	
williamr@4: 	/* aImplementationUid is used by ECOM to select plugin.
williamr@4: 	Contacts model can use REComSession::ListImplementationsL() to determine
williamr@4: 	DLLs that match the interface UID for this class. */
williamr@4: 	static CViewContactSortPlugin* NewL(TSortPluginParams* aParams);
williamr@4: 
williamr@4: 	/* Class must free all memory, implementation should include:
williamr@4: 	iViewSortOrder.Close();	*/
williamr@4: 	inline virtual ~CViewContactSortPlugin();
williamr@4: 
williamr@4: 
williamr@4: 	//pure virtual methods to be implemented by the plugin.
williamr@4: 
williamr@4: 	/** Called by a contact view to pass the sort plug-in the required sort order.
williamr@4: 	Any processing of the order information is done here.
williamr@4: 
williamr@4:     This function is called when the view is created and when a different sort order 
williamr@4: 	is requested. 
williamr@4: 
williamr@4: 	@param aViewSortOrder The requested sort order. */
williamr@4: 	virtual void SetSortOrderL(const RContactViewSortOrder& aViewSortOrder) = 0;
williamr@4: 
williamr@4: 	/** Called by a contact view to notify the sort plug-in that sorting is about to start.
williamr@4: 
williamr@4: 	@param aSortStartType Indicates the type of sort operation required.
williamr@4: 	@param aCount The approximate number of contacts to be processed.
williamr@4: 	@return KErrNone if successful, otherwise another of the system-wide error codes. */
williamr@4: 	virtual TInt SortStart(TSortStartTypes aSortStartType, TInt aCount) = 0;
williamr@4: 
williamr@4: 	/** Called by a contact view to notify the sort plug-in that sorting is complete. */
williamr@4: 	virtual void SortCompleted() = 0;
williamr@4: 
williamr@4: 	/** Called by a contact view to compare two CViewContact items for sorting in the 
williamr@4: 	view.
williamr@4: 
williamr@4: 	If TDesC::CompareC() is used to implement this function, the return value from 
williamr@4: 	TDesC::CompareC() can be used directly.
williamr@4: 
williamr@4: 	@param aLhs The first item to compare.
williamr@4: 	@param aRhs The second item to compare.
williamr@4: 	@return Zero means that aLhs and aRhs have an equal sorting order.
williamr@4: 	An arbitrary negative value means that aLhs is to be sorted before aRhs. 
williamr@4: 	An arbitrary positive value means that aRhs is to be sorted before aLhs. */
williamr@4: 	virtual TInt SortCompareViewContactsL(const CViewContact& aLhs, const CViewContact& aRhs) = 0;
williamr@4: 
williamr@4: 	/** Tests whether a CViewContact is sortable. 
williamr@4: 	
williamr@4: 	For instance, a contact may be unsortable if none of the fields used to sort on 
williamr@4: 	contain any data. 
williamr@4: 	@param aViewContact The view contact to test.
williamr@4: 	@return ETrue if the view contact is sortable, EFalse if not. */
williamr@4: 	virtual TBool ViewContactIsSortable(const CViewContact& aViewContact) = 0;
williamr@4: 
williamr@4: private:
williamr@4: 	// The uid is stored here, so that it can be used during destruction of the instance.
williamr@4: 	TUid iDtor_ID_Key;
williamr@4: 	};
williamr@4: 
williamr@4: 
williamr@4: //********************************************************************************************
williamr@4: //
williamr@4: // NewL() & destructor inline functions, placed in .h file for simplicity
williamr@4: //
williamr@4: 
williamr@4: // -----------------------CViewContactSortPlugin --------------------------------
williamr@4: 
williamr@4: /** Allocates and constructs a sort plug-in instance.
williamr@4: 
williamr@4: @param aParams The sort plug-in's parameters.
williamr@4: @return Pointer to the newly created sort plug-in implementation. */
williamr@4: inline CViewContactSortPlugin* CViewContactSortPlugin::NewL(TSortPluginParams* aParams)
williamr@4: 	{
williamr@4: 	TAny* ptr = REComSession::CreateImplementationL(aParams->iImplementationUid,
williamr@4: 				_FOFF(CViewContactSortPlugin, iDtor_ID_Key),
williamr@4: 				aParams);
williamr@4: 	return reinterpret_cast<CViewContactSortPlugin*>(ptr);
williamr@4: 	}
williamr@4: 
williamr@4: /** Virtual destructor. */
williamr@4: inline CViewContactSortPlugin::~CViewContactSortPlugin()
williamr@4: 	{
williamr@4: 	REComSession::DestroyedImplementation(iDtor_ID_Key);
williamr@4: 	}
williamr@4: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: 
williamr@4: #endif