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 williamr@4: #include "ecom/ecom.h" // For REComSession williamr@4: #include 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(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