1 // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __CNTVIEWSORTPLUGIN_H__
17 #define __CNTVIEWSORTPLUGIN_H__
20 #include "ecom/ecom.h" // For REComSession
21 #include <cntviewbase.h>
25 /** The UID of the ECOM contact view sort interface.
29 const TUid KCntSortPluginInterfaceUid = {0x10200FBD};
31 /** The name of the default ECOM contact view sort plug-in.
35 _LIT8(KViewSortPluginDefaultName, "/default");
37 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
39 //********************************************************************************************
41 // Parameter blocks passed to Sort Plug-in's NewL, where they should be copied.
44 /** The UID for the sort plug-in parameters (TSortPluginParams and
45 TSortPluginViewParamsRev1) that are used to pass data to the ECOM plug-in DLL.
49 const TUid KCntSortPluginViewParamsRev1Uid = {0x10201325};
51 /** Information block holding the sort plug-in's parameters.
52 This is passed to the plug-in instance from the contact view via
53 TSortPluginParams::iViewSortParams.
55 It has an inline constructor to initialise the data members.
59 class TSortPluginViewParamsRev1
61 public: // constructors
62 /** Empty default constructor. */
63 TSortPluginViewParamsRev1()
65 /** Inline constructor, initialises all data members.
67 @param aViewPreferences The view's view preferences.
68 @param aCompareViewContactsL A pointer to a default function that is used
69 to compare two contact items. The plug-in may call this function from its
70 implementation of SortCompareViewContactsL().
71 @param aIsSortable A pointer to a default function that is used to test
72 whether a CViewContact is sortable. The plug-in may call this function
73 from its implementation of ViewContactIsSortable(). */
74 TSortPluginViewParamsRev1(TContactViewPreferences aViewPreferences,
75 TInt(*aCompareViewContactsL)(const CViewContact& aFirst, const CViewContact& aSecond),
76 TBool(*aIsSortable)(const CViewContact& aViewContact)) :
77 iViewPreferences(aViewPreferences), iCompareViewContactsL(aCompareViewContactsL), iIsSortable(aIsSortable)
80 // Fields in all versions
81 /** The view's view preferences.*/
82 TContactViewPreferences iViewPreferences; // preferences of view (at creation)
84 // Default implementations of Compare and IsSortable methods
85 // that the sort Plugin can call.
87 /** A pointer to a default function that is used to compare two contact
88 items. The plug-in may call this function from its implementation of
89 SortCompareViewContactsL(). */
90 TInt (*iCompareViewContactsL)(const CViewContact& aFirst, const CViewContact& aSecond);
91 /** A pointer to a default function that is used to test whether a contact item
92 is sortable. The plug-in may call this function from its implementation of
93 ViewContactIsSortable(). */
94 TBool(*iIsSortable)(const CViewContact& aViewContact);
98 /** A data class used to pass initialization information to
99 CViewContactSortPlugin::NewL().
103 class TSortPluginParams
105 public: // constructors
106 /** Empty default constructor. */
107 TSortPluginParams() {}
109 /** Inline constructor, initialises all data members.
111 The parameter revision UID is initialised to KCntSortPluginViewParamsRev1Uid.
112 @param aInterfaceUid Interface UID as specified in the INTERFACE_INFO resource struct,
114 @param aImplementationUid Implementation UID, as specified in the IMPLEMENTATION_INFO
115 resource struct, required by ECOM.
116 @param aViewSortParams View sort parameters pointer. This object should match the
117 parameter revision UID value. */
118 TSortPluginParams(TUid aInterfaceUid, TUid aImplementationUid, TSortPluginViewParamsRev1* aViewSortParams) :
119 iParametersRevision(KCntSortPluginViewParamsRev1Uid), iInterfaceUid(aInterfaceUid),
120 iImplementationUid(aImplementationUid), iViewSortParams(aViewSortParams)
123 /** A UID that identifies the revision of the structure holding
124 the view's sort parameters. A value of KCntSortPluginViewParamsRev1Uid
125 indicates TSortPluginViewParamsRev1. */
126 TUid iParametersRevision;
128 // Information for ECOM to load the correct plug-in
129 /** Interface UID as specified in the INTERFACE_INFO resource struct,
132 /** Implementation UID, as specified in the IMPLEMENTATION_INFO
133 resource struct, required by ECOM.*/
134 TUid iImplementationUid;
136 // information block from Contact View
137 /** View sort parameters pointer. This object should match the
138 parameter revision UID value.*/
139 TAny* iViewSortParams;
144 /** An interface class that enables implementers to configure the way in which
145 contacts are sorted in a contact view.
147 This is an abstract base class that will be derived from.
151 class CViewContactSortPlugin : public CBase
154 /** Identifies the type of sort operation to SortStart().
158 enum TSortStartTypes {
159 /** No sort is in progress. */
161 /** A full sort or re-sort. */
163 /** A single contact has been inserted or changed. */
165 /** Multiple contacts have been added. For example, ICC contacts arrived in a
166 mixed view (one that also includes contacts from the phone's memory). */
167 ESortStartInsertMultiple,
168 // other values are reserved
171 /* aImplementationUid is used by ECOM to select plugin.
172 Contacts model can use REComSession::ListImplementationsL() to determine
173 DLLs that match the interface UID for this class. */
174 static CViewContactSortPlugin* NewL(TSortPluginParams* aParams);
176 /* Class must free all memory, implementation should include:
177 iViewSortOrder.Close(); */
178 inline virtual ~CViewContactSortPlugin();
181 //pure virtual methods to be implemented by the plugin.
183 /** Called by a contact view to pass the sort plug-in the required sort order.
184 Any processing of the order information is done here.
186 This function is called when the view is created and when a different sort order
189 @param aViewSortOrder The requested sort order. */
190 virtual void SetSortOrderL(const RContactViewSortOrder& aViewSortOrder) = 0;
192 /** Called by a contact view to notify the sort plug-in that sorting is about to start.
194 @param aSortStartType Indicates the type of sort operation required.
195 @param aCount The approximate number of contacts to be processed.
196 @return KErrNone if successful, otherwise another of the system-wide error codes. */
197 virtual TInt SortStart(TSortStartTypes aSortStartType, TInt aCount) = 0;
199 /** Called by a contact view to notify the sort plug-in that sorting is complete. */
200 virtual void SortCompleted() = 0;
202 /** Called by a contact view to compare two CViewContact items for sorting in the
205 If TDesC::CompareC() is used to implement this function, the return value from
206 TDesC::CompareC() can be used directly.
208 @param aLhs The first item to compare.
209 @param aRhs The second item to compare.
210 @return Zero means that aLhs and aRhs have an equal sorting order.
211 An arbitrary negative value means that aLhs is to be sorted before aRhs.
212 An arbitrary positive value means that aRhs is to be sorted before aLhs. */
213 virtual TInt SortCompareViewContactsL(const CViewContact& aLhs, const CViewContact& aRhs) = 0;
215 /** Tests whether a CViewContact is sortable.
217 For instance, a contact may be unsortable if none of the fields used to sort on
219 @param aViewContact The view contact to test.
220 @return ETrue if the view contact is sortable, EFalse if not. */
221 virtual TBool ViewContactIsSortable(const CViewContact& aViewContact) = 0;
224 // The uid is stored here, so that it can be used during destruction of the instance.
229 //********************************************************************************************
231 // NewL() & destructor inline functions, placed in .h file for simplicity
234 // -----------------------CViewContactSortPlugin --------------------------------
236 /** Allocates and constructs a sort plug-in instance.
238 @param aParams The sort plug-in's parameters.
239 @return Pointer to the newly created sort plug-in implementation. */
240 inline CViewContactSortPlugin* CViewContactSortPlugin::NewL(TSortPluginParams* aParams)
242 TAny* ptr = REComSession::CreateImplementationL(aParams->iImplementationUid,
243 _FOFF(CViewContactSortPlugin, iDtor_ID_Key),
245 return reinterpret_cast<CViewContactSortPlugin*>(ptr);
248 /** Virtual destructor. */
249 inline CViewContactSortPlugin::~CViewContactSortPlugin()
251 REComSession::DestroyedImplementation(iDtor_ID_Key);
253 #endif //SYMBIAN_ENABLE_SPLIT_HEADERS