1.1 --- a/epoc32/include/cntviewbase.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/cntviewbase.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,908 @@
1.4 -cntviewbase.h
1.5 +// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifndef __CNTVIEWBASE_H__
1.21 +#define __CNTVIEWBASE_H__
1.22 +
1.23 +// System includes
1.24 +#include <e32std.h>
1.25 +#include <s32mem.h>
1.26 +
1.27 +#include <cntdb.h>
1.28 +
1.29 +// Classes referenced
1.30 +class CViewContactExtension;
1.31 +class CContactViewBase;
1.32 +class CContactRemoteViewNotifier;
1.33 +class CIdleContactSorter;
1.34 +class CContactViewFindConfigInterface;
1.35 +class CViewContactSortPlugin;
1.36 +class TSortPluginViewParams;
1.37 +
1.38 +/** View preferences for sorted contact views.
1.39 +
1.40 +This is used to specify the types of contact item that should be sorted and
1.41 +included in the view and the behaviour for items that cannot be sorted because
1.42 +they do not have content in any of the fields specified in the view's sort
1.43 +order.
1.44 +
1.45 +The default behaviour is to include contact cards only and to sort contact
1.46 +cards without content in any of the sort order fields using the first available
1.47 +field containing any text.
1.48 +
1.49 +The view preferences for all concrete contact view classes can be retrieved
1.50 +using their implementation of CContactViewBase::ContactViewPreferences().
1.51 +The view preferences are set during construction of a CContactLocalView.
1.52 +
1.53 +@publishedAll
1.54 +@released
1.55 +*/
1.56 +enum TContactViewPreferences
1.57 + {
1.58 + /** Only contact cards (of type KUidContactCard or KUidContactOwnCard) are included
1.59 + in the view. This is the default. */
1.60 + EContactsOnly =0x00000000,
1.61 + /** Only contact groups (of type KUidContactGroup) are included in the view. */
1.62 + EGroupsOnly =0x00000001,
1.63 + /** Contact groups and contact cards (of type KUidContactGroup, KUidContactCard
1.64 + or KUidContactOwnCard) are included in the view. */
1.65 + EContactAndGroups =0x00000002,
1.66 + /** Excludes contact items from the view which don't have content in any of the
1.67 + fields specified in the sort order. */
1.68 + EIgnoreUnSorted =0x00000004,
1.69 + /** Includes contacts in the view which don't have content in any of the fields
1.70 + specified in the sort order. These contacts are placed in an unsorted contact
1.71 + list which is located before the sorted list. */
1.72 + EUnSortedAtBeginning =0x00000008,
1.73 + /** Includes contacts in the view which don't have content in any of the fields
1.74 + specified in the sort order. These contacts are placed in an unsorted contact
1.75 + list which is located after the sorted list. */
1.76 + EUnSortedAtEnd =0x00000010,
1.77 + /** Fields containing a single white space only are treated as empty, and therefore
1.78 + unsortable. */
1.79 + ESingleWhiteSpaceIsEmptyField =0x00000020,
1.80 + /** Only ICC entries (of type KUidContactICCEntry) are included in the view. */
1.81 + EICCEntriesOnly =0x00000040,
1.82 + /** Only contact cards and ICC entries (of type KUidContactCard, KUidContactOwnCard
1.83 + or KUidContactICCEntry) are included in the view. */
1.84 + EICCEntriesAndContacts =0x00000080
1.85 + };
1.86 +
1.87 +
1.88 +class TContactViewEvent
1.89 +/** Identifies a contact view event.
1.90 +
1.91 +Sent by contact views when notifying their observers of an event.
1.92 +
1.93 +@see MContactViewObserver::HandleContactViewEvent()
1.94 +@publishedAll
1.95 +@released
1.96 +*/
1.97 + {
1.98 +public:
1.99 + /** Identifies the event's type. */
1.100 + enum TEventType
1.101 + {
1.102 + /** The observed view's state has changed from EReady to either ENotReady or EInitializing,
1.103 + so is not available for use. */
1.104 + EUnavailable,
1.105 + /** The observed view's state has changed from ENotReady or EInitializing to EReady
1.106 + so is available for use. */
1.107 + EReady,
1.108 + /** The observed view's sort order has changed, so observer views need to update
1.109 + themselves. */
1.110 + ESortOrderChanged,
1.111 + /** An error occurred when sorting the observed view or when appending an observer
1.112 + to its observer array.
1.113 +
1.114 + The error code is provided in iInt. */
1.115 + ESortError,
1.116 + /** An error occurred in the contacts server.
1.117 +
1.118 + The error code is provided in iInt. */
1.119 + EServerError,
1.120 + /** An error occurred when setting the range for a CContactSubView.
1.121 +
1.122 + The error code is provided in iInt. */
1.123 + EIndexingError,
1.124 + /** An item has been added to the observed view.
1.125 +
1.126 + The ID of the added item is provided in iContactId and the index into the
1.127 + observed view of the added item is provided in iInt.
1.128 + Exception from this are the first version of CContactFindView, CContactSubView and
1.129 + CContactGroupView classes.
1.130 + For these classes, iInt has KErrNone value */
1.131 +
1.132 + EItemAdded,
1.133 + /** An item has been removed from the observed view.
1.134 +
1.135 + The ID of the removed item is provided in iContactId and the index into the
1.136 + observed view of the item is provided in iInt.
1.137 + Exception from this are the first version of CContactFindView and CContactSubView classes.
1.138 + For these classes, iInt has KErrNone value */
1.139 +
1.140 + EItemRemoved,
1.141 + /** A change has occurred in a contact group, for instance a contact item has been
1.142 + moved into or out of the group.
1.143 +
1.144 + The ID of the group affected is provided in iContactId. */
1.145 + EGroupChanged
1.146 + };
1.147 +public:
1.148 + inline TContactViewEvent();
1.149 + inline TContactViewEvent(TEventType aEventType,TInt aInt = KErrUnknown,TContactItemId aContactId = KErrUnknown);
1.150 +public:
1.151 + /** The type of event. */
1.152 + TEventType iEventType;
1.153 + /** The error code (where relevant) or the index of the contact item added to/removed
1.154 + from the underlying view. */
1.155 + TInt iInt;
1.156 + /** The ID of the contact item that has been added or removed or the group ID, where
1.157 + relevant. */
1.158 + TContactItemId iContactId;//ContactId that has been added / removed if relevant.
1.159 + };
1.160 +
1.161 +
1.162 +struct TContactIdWithMapping
1.163 +/** A struct used internally by filtered and group views to pair a contact item
1.164 +ID and its index into the underlying view.
1.165 +@publishedAll
1.166 +@released
1.167 +*/
1.168 + {
1.169 + /** The contact item's ID. */
1.170 + TContactItemId iId;
1.171 + /** The index of the item into the view's underlying view. */
1.172 + TInt iMapping;
1.173 + };
1.174 +
1.175 +
1.176 +class MContactViewObserver
1.177 +/** The interface for a contact view observer.
1.178 +
1.179 +Objects that need to observe a contact view should implement this interface.
1.180 +The view observer should be passed to the observed view's OpenL() or Open()
1.181 +function. This adds the observer to the view's observer array: a view can
1.182 +have more than one observer. The observers receive notifications when the
1.183 +observed view becomes ready for use and when changes occur in it.
1.184 +
1.185 +Many contact view classes implement this interface to observe an underlying
1.186 +view. They in turn send notification to any objects observing them.
1.187 +
1.188 +@see CContactViewBase::NotifyObservers()
1.189 +@see CContactViewBase::NotifyObserverAsync()
1.190 +@publishedAll
1.191 +@released
1.192 +*/
1.193 + {
1.194 +public:
1.195 + /** Handles an event in an observed contact view.
1.196 +
1.197 + @param aView The contact view causing the notification.
1.198 + @param aEvent The event. */
1.199 + virtual void HandleContactViewEvent(const CContactViewBase& aView,const TContactViewEvent& aEvent)=0;
1.200 + };
1.201 +
1.202 +
1.203 +class RContactViewSortOrder
1.204 +/** Specifies the sort order for a contact view.
1.205 +
1.206 +It is implemented as an array of TFieldType UIDs, which define the fields
1.207 +whose contents are used to sort on, and their order.
1.208 +
1.209 +The sort order for all concrete contact view classes can be retrieved using
1.210 +their implementation of CContactViewBase::SortOrderL(). The sort order is
1.211 +set during construction of local and remote views.
1.212 +@publishedAll
1.213 +@released
1.214 +*/
1.215 + {
1.216 +public:
1.217 + IMPORT_C RContactViewSortOrder();
1.218 + IMPORT_C void Close();
1.219 + IMPORT_C void CopyL(const RContactViewSortOrder& aSortOrder);
1.220 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.221 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.222 + IMPORT_C TInt ExternalizedSize() const;
1.223 + IMPORT_C TBool operator==(const RContactViewSortOrder& aSortOrder) const;
1.224 + inline void AppendL(TFieldType aField);
1.225 + inline TFieldType operator[](TInt aIndex) const;
1.226 + inline TInt Count() const;
1.227 +private:
1.228 + RArray<TFieldType> iFields;
1.229 + TInt iSpare;
1.230 + TInt32 iSpare2;
1.231 + TInt32 iSpare3;
1.232 + };
1.233 +
1.234 +
1.235 +/**
1.236 +Wrapper around RArray, to container TTextFieldMinimal buffers.
1.237 +
1.238 +Features: minimum size 1, easy resize of array, persistent last counted total.
1.239 +
1.240 +@internalComponent
1.241 +@released
1.242 +*/
1.243 +class RFieldBufferArray : public RArray<CContactDatabase::TTextFieldMinimal>
1.244 + {
1.245 +public:
1.246 + explicit RFieldBufferArray();
1.247 +
1.248 + void ResizeL(TInt aNewSize);
1.249 + void ZeroAll();
1.250 + TInt NewTotal();
1.251 + TInt LastTotal() const;
1.252 +
1.253 +private:
1.254 + TInt iTotalLength;
1.255 + };
1.256 +
1.257 +
1.258 +
1.259 +class CViewContact : public CBase
1.260 +/** The representation of a contact item used in contact views.
1.261 +
1.262 +It stores the contact item ID and other information. This includes a buffer
1.263 +holding the contents of all the item's fields, an array of indexes into the
1.264 +buffer indicating the start position of each field and a hint bit field (a
1.265 +combination of CContactDatabase::TContactViewFilter values) which is used
1.266 +in filtered views.
1.267 +
1.268 +The fields are defined by the view's sort order (RContactViewSortOrder).
1.269 +@publishedAll
1.270 +@released
1.271 +*/
1.272 + {
1.273 +public:
1.274 + /** Defines whether the contact view item is a contact group. */
1.275 + enum TViewContactType
1.276 + {
1.277 + /** The contact view item is not a contact group. */
1.278 + EContactItem,
1.279 + /** The contact view item is a contact group (CContactGroup). */
1.280 + EGroup
1.281 + };
1.282 + IMPORT_C CViewContact(TContactItemId aId);
1.283 + IMPORT_C static CViewContact* NewL(const CViewContact& aContact);
1.284 + IMPORT_C static CViewContact* NewLC(TContactItemId aId);
1.285 + IMPORT_C static CViewContact* NewL(TContactItemId aId, TInt aLength);
1.286 + static CViewContact* NewLC(RReadStream& aStream);
1.287 +
1.288 + IMPORT_C ~CViewContact();
1.289 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.290 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.291 + IMPORT_C TInt ExternalizedSize() const;
1.292 + IMPORT_C TInt FieldCount() const;
1.293 + IMPORT_C TPtrC Field(TInt aPosition) const;
1.294 + IMPORT_C TBool ContactMatchesFilter(TInt aFilter) const;
1.295 + IMPORT_C void AddFieldL(const TDesC& aField);
1.296 + IMPORT_C TBool IsSortable() const;
1.297 + IMPORT_C void SetFirstFieldForBlankContactL(const TDesC& aFirstField);
1.298 + IMPORT_C void Reset();
1.299 + IMPORT_C TInt ContactHint() const;
1.300 + IMPORT_C void SetContactHint(TInt aHint);
1.301 + IMPORT_C TUid ContactTypeUid() const;
1.302 + IMPORT_C void SetContactTypeUid(TUid aUid);
1.303 +
1.304 + inline TContactItemId Id() const;
1.305 + inline TViewContactType ContactType() const;
1.306 +public:
1.307 + inline void SetId(TContactItemId aId);
1.308 + inline void SetContactType(CViewContact::TViewContactType aContactType);
1.309 + static TBool HintFieldMatchesFilter(TInt aHintField, TInt aFilter);
1.310 + TPtrC FindFirstPopulatedField(TInt aOffset, TInt& aFoundPosition) const;
1.311 +
1.312 +#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
1.313 + IMPORT_C void ChangeToLightweightObject();
1.314 + TBool IsLightweightObject() const;
1.315 + void CopyL(const CViewContact& aContact);
1.316 +#endif //__SYMBIAN_CNTMODEL_USE_SQLITE__
1.317 +
1.318 +private:
1.319 + void ConstructL(TInt aLength = 0);
1.320 + void ConstructL(const CViewContact& aContact);
1.321 + friend class CContactViewBase;
1.322 +private:
1.323 + TContactItemId iId;
1.324 + TViewContactType iContactType;
1.325 + CViewContactExtension* iExtension;
1.326 + RArray<TInt> iTextIndexes;
1.327 + };
1.328 +
1.329 +
1.330 +/*
1.331 + * A view can be named or un-named. An un-named view has a fixed sort order - the
1.332 + * only way to change this is by closing the object and creating a new one with a
1.333 + * different order. Named views may have their sort order changed. When this is
1.334 + * done, first all observers will be informed that the view is 'unavailable'. This
1.335 + * notification will be followed by 'sort order changed' and 'ready'. Only once
1.336 + * the 'ready' notification has been received may the view be used again.
1.337 + */
1.338 +class CContactViewBase : public CBase
1.339 +/** The abstract base class for all contact view classes.
1.340 +
1.341 +All contact views operate asynchronously, so users of the view must observe
1.342 +it, by implementing the MContactViewObserver interface. Immediately after
1.343 +construction, views are not in a usable state (the underlying data may be
1.344 +being sorted, for instance). Only after the user has received a TContactViewEvent::EReady
1.345 +event may the view be used.
1.346 +
1.347 +View observers are also notified when changes occur, for instance when the
1.348 +view's state changes (see TState), when an error occurs, or when an item is
1.349 +added or removed.
1.350 +@publishedAll
1.351 +@released
1.352 +*/
1.353 + {
1.354 +public:
1.355 + class CContactViewBaseExtension : public CBase
1.356 + /** An extension class that holds member data added in v7.0s.
1.357 +
1.358 + It was created for binary compatibility purposes.
1.359 + @internalComponent
1.360 + @released */
1.361 + {
1.362 + public:
1.363 + static CContactViewBaseExtension* NewL();
1.364 + ~CContactViewBaseExtension();
1.365 +
1.366 + private:
1.367 + CContactViewBaseExtension();
1.368 + void ConstructL();
1.369 +
1.370 + public:
1.371 + /** A standard error code that is passed to view observers by NotifyObservers()
1.372 + (unless its value is KErrNone). */
1.373 + TInt iError;
1.374 + /** The UID of the view's find configuration plug-in.
1.375 +
1.376 + On construction, this is initialised to KNullUid.
1.377 +
1.378 + The plug-in is loaded when ContactsMatchingCriteriaL(), ContactsMatchingPrefixL()
1.379 + or MatchesCriteriaL() is called. */
1.380 + TUid iFindPluginUid;
1.381 + /** The UID of the view's sort plug-in. */
1.382 + TUid iSortPluginUid;
1.383 + private:
1.384 + CContactViewFindConfigInterface* iFindPluginImpl;
1.385 + CViewContactSortPlugin* iSortPluginImpl;
1.386 + TCollationMethod iCollationMethod;
1.387 + friend class CContactViewBase;
1.388 + };
1.389 + class TVirtualFunction1Params
1.390 + /** Holds the two parameters passed to the helper method GetContactIdsL() from
1.391 + the reserved function CContactViewBase_Reserved_1(). It has an inline constructor
1.392 + to initialise the data members.
1.393 + @publishedAll
1.394 + @released */
1.395 + {
1.396 + public:
1.397 + /** Inline constructor to initialize member data
1.398 + @param aIndexes Pointer to an array of indexes in a view
1.399 + @param aIdArray Pointer to array of contact IDs */
1.400 + inline TVirtualFunction1Params(const CArrayFix<TInt>* aIndexes, CContactIdArray* aIdArray) :iIndexes(aIndexes), iIdArray(aIdArray){};
1.401 + /** Pointer to an array of indexes in a view */
1.402 + const CArrayFix<TInt>* iIndexes;
1.403 + /** Pointer to array of contact IDs */
1.404 + CContactIdArray* iIdArray;
1.405 + };
1.406 + class TVirtualFunction2Params
1.407 + /** Holds the two parameters passed to the method GetContactsMatchingFilterL()
1.408 + from the reserved function CContactViewBase_Reserved_1(). It has an inline
1.409 + constructor to initialise the data members.
1.410 + */
1.411 + {
1.412 + public:
1.413 + /** Inline constructor to initialize member data.
1.414 + @param aFilter Filter for the contacts
1.415 + @param aMatchingContacts Contacts matching a particular criterion */
1.416 + inline TVirtualFunction2Params(TInt aFilter, RArray<TContactIdWithMapping>& aMatchingContacts) : iFilter(aFilter), iMatchingContacts(aMatchingContacts){};
1.417 + public:
1.418 + /** Filter for the contacts. */
1.419 + TInt iFilter;
1.420 + /** List of contacts matching the criteria. */
1.421 + RArray<TContactIdWithMapping>& iMatchingContacts;
1.422 + };
1.423 + class TVirtualFunction3Params
1.424 + /** Holds the two parameters passed to the method InsertContactInView() from the
1.425 + reserved function CContactViewBase_Reserved_1(). It has an inline
1.426 + constructor to initialise the data members.
1.427 +
1.428 + @internalAll */
1.429 + {
1.430 + public:
1.431 + inline TVirtualFunction3Params(RPointerArray<CViewContact>& aContacts, const CViewContact* aNewContact) :iContacts(aContacts), iNewContact(aNewContact){};
1.432 + RPointerArray<CViewContact>& iContacts;
1.433 + const CViewContact* iNewContact;
1.434 + };
1.435 + /** Search type.
1.436 +
1.437 + This controls whether a search term can occur anywhere in a contact item field,
1.438 + or just at the beginning of the field. */
1.439 + enum TSearchType
1.440 + {
1.441 + /** The search uses full wildcard matching so that the search string can occur anywhere
1.442 + in the item's fields. */
1.443 + EFullSearch,
1.444 + /** The search uses partial wildcard matching so that the search string can only
1.445 + occur at the beginning of the item's fields. */
1.446 + EPrefixSearch
1.447 + };
1.448 + /** Identifies the functions that have been added to CContactViewBase, or that
1.449 + may be added in the future. This identifier is passed to the reserved virtual
1.450 + function CContactViewBase_Reserved_1() and enables the addition of new virtual
1.451 + methods without breaking binary compatibility. */
1.452 + enum TFunction
1.453 + {
1.454 + /** Identifies the function CContactViewBase::GetContactIdsL(). */
1.455 + ECContactViewBaseVirtualFunction1,
1.456 + /** Identifies the function CContactViewBase::GetContactsMatchingFilterL(). */
1.457 + ECContactViewBaseVirtualFunction2,
1.458 + // communication with Sort Plug-in
1.459 + /** Identifies the function CContactViewBase::InsertContactInView(). */
1.460 + ECContactViewBaseVirtualFunction3,
1.461 + };
1.462 +protected:
1.463 + /** Defines the contact view states. */
1.464 + enum TState
1.465 + {
1.466 + /** The view is initialising.
1.467 +
1.468 + This is the view's state immediately after construction or after a significant change
1.469 + (e.g CurrentDatabaseChanged or UnknownChanges), indicating that it can't be used yet. */
1.470 + EInitializing,
1.471 + /** The view is ready to be used. */
1.472 + EReady,
1.473 + /** The view is not ready to be used, for instance immediately after the sort order
1.474 + has changed, or after an error has occurred. */
1.475 + ENotReady
1.476 + };
1.477 +public:
1.478 + IMPORT_C void OpenL(MContactViewObserver& aObserver);
1.479 + IMPORT_C TInt Open(MContactViewObserver& aObserver);
1.480 + IMPORT_C TBool Close(const MContactViewObserver& aObserver);
1.481 + /** Returns the contact item ID at the specified index into the view.
1.482 +
1.483 + @capability ReadUserData
1.484 + @param aIndex Index of the contact item ID into the view.
1.485 + @return The contact item ID. */
1.486 + virtual TContactItemId AtL(TInt aIndex) const=0;
1.487 + /** Returns the contact item at the specified index into the view.
1.488 +
1.489 + @capability ReadUserData
1.490 + @param aIndex Index of the contact item into the view.
1.491 + @return The contact item. */
1.492 + virtual const CViewContact& ContactAtL(TInt aIndex) const =0;
1.493 + /** Returns the number of contact items in the view.
1.494 +
1.495 + @capability ReadUserData
1.496 + @return The number of contact items in the view. */
1.497 + virtual TInt CountL() const=0;
1.498 + /** Returns the index into the view of the specified contact item.
1.499 +
1.500 + @capability ReadUserData
1.501 + @param aId The contact item ID to search for.
1.502 + @return The index into the view of the contact item ID, or KErrNotFound if
1.503 + no matching ID can be found. */
1.504 + virtual TInt FindL(TContactItemId aId) const=0;
1.505 + /** Returns a descriptor containing the contents of all fields for an item in the view.
1.506 +
1.507 + The field separator is used to separate the contents of each field. It is
1.508 + not appended to the last field.
1.509 +
1.510 + @capability ReadUserData
1.511 + @param aIndex The index of the contact item into the view.
1.512 + @param aSeparator The string to use to separate the fields.
1.513 + @return Pointer to the contact item descriptor. */
1.514 + virtual HBufC* AllFieldsLC(TInt aIndex,const TDesC& aSeparator) const=0;
1.515 + IMPORT_C virtual void ContactsMatchingCriteriaL(const MDesCArray& aFindWords,RPointerArray<CViewContact>& aMatchedContacts);
1.516 + /** Gets the view preferences.
1.517 +
1.518 + @capability ReadUserData
1.519 + @return The view preferences. */
1.520 + virtual TContactViewPreferences ContactViewPreferences()=0;
1.521 + /** Gets the view's sort order.
1.522 +
1.523 + @capability ReadUserData
1.524 + @return The sort order. */
1.525 + virtual const RContactViewSortOrder& SortOrderL() const = 0;
1.526 + IMPORT_C virtual void ContactsMatchingPrefixL(const MDesCArray& aFindWords, RPointerArray<CViewContact>& aMatchedContacts);
1.527 + //This is a reserved virtual exported function that is used for BC proofing against present
1.528 + //and future additions of new exported virtual functions. Existing exported virtual methods
1.529 + //that broke BC are now non-virtual exported helper functions called from this method.
1.530 + //All derived classes of CContactViewBase that are public must mandatorily
1.531 + //implement this reserved exported virtual method.
1.532 + IMPORT_C virtual TAny* CContactViewBase_Reserved_1(TFunction aFunction,TAny* aParams);
1.533 + //New exported method to set the ECOM plug-in to be used
1.534 + IMPORT_C void SetViewFindConfigPlugin(TUid aUid);
1.535 + IMPORT_C TUid GetViewFindConfigPlugin();
1.536 + IMPORT_C virtual void GetContactIdsL(const CArrayFix<TInt>& aIndexes, CContactIdArray& aContactIds);
1.537 + IMPORT_C TInt Error() const;
1.538 + IMPORT_C TUid GetViewSortPluginImplUid() const;
1.539 +
1.540 +protected:
1.541 + IMPORT_C ~CContactViewBase();
1.542 + IMPORT_C void ConstructL();
1.543 +
1.544 + IMPORT_C CContactViewBase(const CContactDatabase& aDb);
1.545 + IMPORT_C void NotifyObservers(const TContactViewEvent& aEvent);
1.546 + IMPORT_C TInt NotifyObserverAsync(MContactViewObserver& aObserver,const TContactViewEvent& aEvent);
1.547 + IMPORT_C static TBool IdsMatch(const CViewContact& aFirst,const CViewContact& aSecond);
1.548 + IMPORT_C HBufC* FieldsWithSeparatorLC(const RPointerArray<CViewContact>& aContacts,TInt aIndex,const TDesC& aSeparator) const;
1.549 + //Find helper functions
1.550 + IMPORT_C virtual TBool MatchesCriteriaL(const CViewContact& aContact,const MDesCArray& aFindWords);
1.551 + IMPORT_C static TBool MatchesCriteriaL(const CViewContact& aContact,const MDesCArray& aFindWords, TSearchType aSearchType);
1.552 + IMPORT_C static TBool MatchesCriteriaL(const CViewContact& aContact,const MDesCArray& aFindWords, TSearchType aSearchType,CContactViewBase::CContactViewBaseExtension* aExtension);
1.553 + IMPORT_C static TBool IdsEqual(const TContactIdWithMapping& aFirst,const TContactIdWithMapping& aSecond);
1.554 + IMPORT_C static TBool IndexesEqual(const TContactIdWithMapping& aFirst,const TContactIdWithMapping& aSecond);
1.555 + IMPORT_C static TInt CompareFieldsL(const CViewContact& aFirst, const CViewContact& aSecond);
1.556 + // View Sort Plugin changes
1.557 + IMPORT_C static TInt CompareContactIds(const CViewContact& aFirst, const CViewContact& aSecond);
1.558 + IMPORT_C static TBool ContactIsSortable(const CViewContact& aContact);
1.559 + IMPORT_C TInt CompareContactsAndIdsL(const CViewContact& aFirst, const CViewContact& aSecond) const;
1.560 +protected: // these are needed by CContactLocalView only
1.561 + TInt InsertContactInView(RPointerArray<CViewContact>& aContacts, const CViewContact* aNewContact, TBool aSortByIdOnly, TInt* aIndex) const;
1.562 + TBool IsContactSortable(const CViewContact& aContact, TContactViewPreferences& aViewPreferences) const;
1.563 + CViewContactSortPlugin* SortPluginImpl() const;
1.564 + TUid FindSortPluginImplL (const TDesC8& aSortPluginName,TBool aWildCard=EFalse) const;
1.565 + TUid FindDefaultViewSortPluginImplL () const;
1.566 + void LoadViewSortPluginL (TUid aSortPluginUid,TContactViewPreferences& aViewPreferences);
1.567 +
1.568 +private:
1.569 + static TInt AsyncNotifyCallBack(TAny* aSelf);
1.570 + static CDesCArrayFlat* CreateFindWordArrayLC(const MDesCArray& aFindWords, TSearchType aSearchType);
1.571 + static TBool ContactMatchesCriteriaL(const CViewContact& aContact,const MDesCArray& aFindWords,CContactViewBase::CContactViewBaseExtension* aExtension);
1.572 + void MatchContactsL(const MDesCArray& aFindWords,RPointerArray<CViewContact>& aMatchedContacts, TSearchType aSearchType);
1.573 + static TInt CompareFieldsWithCollationLevel(const CViewContact& aFirst, const CViewContact& aSecond,
1.574 + TInt aCollationLevel, TCollationMethod* aCollateMethod);
1.575 + TInt GetErrorValueFromExtensionClass();
1.576 + void GetContactsMatchingFilterL(TInt aFilter, RArray<TContactIdWithMapping>& aMatchingContacts);
1.577 + TInt TextCompareFieldsL(const CViewContact& aFirst, const CViewContact& aSecond) const;
1.578 +
1.579 +
1.580 +private:
1.581 + struct TObserverAndEvent
1.582 + {
1.583 + TContactViewEvent iAsyncEvent;
1.584 + MContactViewObserver* iObserverToNotify;
1.585 + };
1.586 +protected:
1.587 + // Reference to CContactDatabase class.
1.588 + const CContactDatabase& iDb;
1.589 + // Different Contacts view states.
1.590 + TState iState;
1.591 + // The pointer to the ContactViewBase BC extension class.
1.592 + CContactViewBaseExtension* iExtension;
1.593 +private:
1.594 + RPointerArray<MContactViewObserver> iObserverArray;
1.595 + CIdle* iAsyncNotifier;
1.596 + RArray<TObserverAndEvent> iOutstandingNotifications;
1.597 + };
1.598 +
1.599 +inline TInt CContactViewBase::GetErrorValueFromExtensionClass()
1.600 + {
1.601 + return iExtension->iError;
1.602 + }
1.603 +
1.604 +class MLplPersistenceLayerFactory;
1.605 +
1.606 +#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
1.607 +
1.608 +class CViewContactManager;
1.609 +
1.610 +#else //__SYMBIAN_CNTMODEL_USE_SQLITE__
1.611 +
1.612 +class CViewIterator;
1.613 +
1.614 +#endif //__SYMBIAN_CNTMODEL_USE_SQLITE__
1.615 +
1.616 +class CContactLocalView : public CContactViewBase, public MContactDbObserver
1.617 +/** An instantiable base class for contact views.
1.618 +
1.619 +The data associated with a local view is allocated within the client's memory
1.620 +space; CContactRemoteView should be used in preference if the view is likely
1.621 +to be shared between multiple clients. It is kept up to date by receiving
1.622 +change events from the underlying CContactDatabase object which it observes.
1.623 +The view preferences and sort order are specified on construction.
1.624 +@publishedAll
1.625 +@released
1.626 +*/
1.627 + {
1.628 +public:
1.629 + IMPORT_C static CContactLocalView* NewL(MContactViewObserver& aObserver,const CContactDatabase& aDb,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes);
1.630 + IMPORT_C static CContactLocalView* NewL(MContactViewObserver& aObserver,const CContactDatabase& aDb,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes,
1.631 + const TDesC8& aSortPluginName);
1.632 + IMPORT_C static CContactLocalView* NewL(MContactViewObserver& aObserver,const CContactDatabase& aDb,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes,
1.633 + MLplPersistenceLayerFactory* aFactory,const TDesC8& aSortPluginName);
1.634 +
1.635 + IMPORT_C const RContactViewSortOrder& SortOrder() const;
1.636 +public: // From CContactViewBase.
1.637 + TContactItemId AtL(TInt aIndex) const;
1.638 + TInt CountL() const;
1.639 + TInt FindL(TContactItemId aId) const;
1.640 + HBufC* AllFieldsLC(TInt aIndex,const TDesC& aSeparator) const;
1.641 + const CViewContact& ContactAtL(TInt aIndex) const;
1.642 + TContactViewPreferences ContactViewPreferences();
1.643 + const RContactViewSortOrder& SortOrderL() const;
1.644 + void NotifySortError(TInt aError);
1.645 + //All derived classes of CContactViewBase that are public should mandatorily
1.646 + //implement this reserved exported virtual method.
1.647 + IMPORT_C TAny* CContactViewBase_Reserved_1(TFunction aFunction,TAny* aParams);
1.648 +protected:
1.649 + IMPORT_C ~CContactLocalView();
1.650 + IMPORT_C CContactLocalView(const CContactDatabase& aDb,TContactViewPreferences aContactTypes);
1.651 + CContactLocalView(const CContactDatabase& aDb,TContactViewPreferences aContactTypes,MLplPersistenceLayerFactory* aIterFactory);
1.652 + IMPORT_C void ConstructL(MContactViewObserver& aObserver,const RContactViewSortOrder& aSortOrder);
1.653 + void ConstructL(MContactViewObserver& aObserver,const RContactViewSortOrder& aSortOrder, const TBool aUseNamedPlugin, const TDesC8& aSortPluginName);
1.654 + IMPORT_C virtual void SortL(const RContactViewSortOrder& aSortOrder);
1.655 + IMPORT_C virtual TInt InsertL(TContactItemId aId);
1.656 + IMPORT_C virtual TInt RemoveL(TContactItemId aId);
1.657 +protected:
1.658 + void SetState(TState aState);
1.659 +private: // From MContactDbObserver.
1.660 + virtual void HandleDatabaseEventL(TContactDbObserverEvent aEvent);
1.661 +
1.662 +private:
1.663 +
1.664 +#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
1.665 + void SortComplete(TInt aSortErr);
1.666 + void SetSortOrderL(const RContactViewSortOrder& aSortOrder);
1.667 + void SortL();
1.668 + void SafeResort();
1.669 + friend class CViewContactManager;
1.670 +#else //__SYMBIAN_CNTMODEL_USE_SQLITE__
1.671 + TInt SortCallBack();
1.672 + TInt DoReadIncrementL();
1.673 + void ResetSortL();
1.674 + void InitialiseSortL(const RContactViewSortOrder& aSortOrder, TBool aChangingSortOrder);
1.675 + void SortL();
1.676 + void SafeResort();
1.677 + void ContactsArraySortL();
1.678 + TBool ContactCorrectType(TUid aType,TContactViewPreferences aTypeToInclude);
1.679 +#endif //__SYMBIAN_CNTMODEL_USE_SQLITE__
1.680 +
1.681 +private: // Metheds for event handling
1.682 + void HandleOutstandingEvents();
1.683 + void HandleOutstandingEventL();
1.684 + friend class CIdleContactSorter;
1.685 +protected:
1.686 + /** The sort order.
1.687 + This is set during construction or when SortL() is called. */
1.688 + RContactViewSortOrder iSortOrder ;
1.689 +private:
1.690 + IMPORT_C virtual void CContactLocalView_Reserved_1();
1.691 + IMPORT_C virtual void CContactLocalView_Reserved_2();
1.692 +
1.693 +private:
1.694 + MLplPersistenceLayerFactory* iFactory;
1.695 + RPointerArray<CViewContact> iContacts;
1.696 + RPointerArray<CViewContact> iUnSortedContacts;
1.697 + RArray<TContactDbObserverEvent> iOutstandingEvents;
1.698 + CIdleContactSorter* iAsyncSorter;
1.699 +
1.700 +#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
1.701 + CViewContactManager* iViewCntMgr;
1.702 +#else //__SYMBIAN_CNTMODEL_USE_SQLITE__
1.703 + CViewIterator* iViewIterator;
1.704 +#endif //__SYMBIAN_CNTMODEL_USE_SQLITE__
1.705 +
1.706 + CContactTextDef* iTextDef;
1.707 + TContactViewPreferences iViewPreferences;
1.708 + TBool iSpare0;
1.709 + TInt iSpare;
1.710 + };
1.711 +
1.712 +class RContactRemoteView : public RSubSessionBase
1.713 +/** This class is used internally by remote contact views as the handle to the
1.714 +server side view object.
1.715 +
1.716 +@see CContactRemoteViewBase
1.717 +@internalComponent
1.718 +@released
1.719 +*/
1.720 + {
1.721 +public:
1.722 + void OpenL(const CContactDatabase& aDb,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes,const TUid& aSortPluginImplUid,const TDesC8& aSortPluginName);
1.723 + void OpenL(const CContactDatabase& aDb,const TDesC& aName,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes,const TUid& aSortPluginImplUid,const TDesC8& aSortPluginName);
1.724 + void Close();
1.725 +public: // From CContactViewBase
1.726 + TContactItemId AtL(TInt aIndex) const;
1.727 + CViewContact* ContactAtL(TInt aIndex);
1.728 + TInt CountL() const;
1.729 + TInt FindL(TContactItemId aId) const;
1.730 + HBufC* AllFieldsLC(TInt aIndex,const TDesC& aSeparator) const;
1.731 + const RContactViewSortOrder& SortOrderL();
1.732 +public:
1.733 + void ContactsMatchingCriteriaL(const MDesCArray& aFindWords,RPointerArray<CViewContact>& aMatchedContacts, TBool aPrefixSearch,TUid aUid);
1.734 + void ChangeSortOrderL(const RContactViewSortOrder& aSortOrder);
1.735 + void GetSortOrderL(RContactViewSortOrder& aSortOrder);
1.736 + TContactViewPreferences ContactViewPreferencesL();
1.737 +
1.738 + void RequestViewEvent(TPckgBuf<TContactViewEvent>& aEvent,TRequestStatus& aStatus);
1.739 + TInt CancelRequestViewEvent();
1.740 + void GetContactIdsL(const CArrayFix<TInt>& aIndexes, CContactIdArray& aContactIds);
1.741 + void GetContactsMatchingFilterL(TInt aFilter, RArray<TContactIdWithMapping>& aMatchingContacts);
1.742 + TUid GetViewSortPluginImplUidL() const;
1.743 +private:
1.744 + HBufC8* PackageSortOrderLC(const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes) const;
1.745 + HBufC8* PackageSortOrderAndPluginDetailsLC(const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes,const TUid& aSortPluginImplUid,const TDesC8& aSortPluginName) const;
1.746 +private:
1.747 + CViewContact* iContact;
1.748 + RContactViewSortOrder iSortOrder ;
1.749 + };
1.750 +
1.751 +
1.752 +NONSHARABLE_CLASS(CContactRemoteViewBase) : public CContactViewBase
1.753 +/** Base class for all remote contact view classes.
1.754 +
1.755 +It implements all the pure virtual functions in CContactViewBase and additionally
1.756 +it handles remote view notifications. The data associated with remote views
1.757 +is allocated within the memory space of the contacts server. This means that
1.758 +multiple clients can share the same server side view object, thereby reducing
1.759 +the overhead associated with initial sorting of the view data and keeping
1.760 +it in sync with the underlying data. Remote views should therefore be used
1.761 +when the same view is likely to be needed by more than one client.
1.762 +@internalComponent
1.763 +@released
1.764 +*/
1.765 + {
1.766 +public: // From CContactViewBase.
1.767 + TContactItemId AtL(TInt aIndex) const;
1.768 + TInt CountL() const;
1.769 + TInt FindL(TContactItemId aId) const;
1.770 + HBufC* AllFieldsLC(TInt aIndex,const TDesC& aSeparator) const;
1.771 + const CViewContact& ContactAtL(TInt aIndex) const;
1.772 + TContactViewPreferences ContactViewPreferences();
1.773 + void ContactsMatchingCriteriaL(const MDesCArray& aFindWords,RPointerArray<CViewContact>& aMatchedContacts);
1.774 + void ContactsMatchingPrefixL(const MDesCArray& aFindWords, RPointerArray<CViewContact>& aMatchedContacts);
1.775 + const RContactViewSortOrder& SortOrderL() const;
1.776 + //All derived classes of CContactViewBase that are public should mandatorily
1.777 + //implement this reserved exported virtual method.
1.778 + TAny* CContactViewBase_Reserved_1(TFunction aFunction,TAny* aParams);
1.779 + //This function was virtual in a previous release, if you still need to use it
1.780 + //in a virtual way then you can call it via the Reserved function.
1.781 + //The functionality of this function ,however,remains the same.
1.782 + void GetContactIdsL(const CArrayFix<TInt>& aIndexes, CContactIdArray& aContactIds);
1.783 + void GetContactsMatchingFilterL(TInt aFilter, RArray<TContactIdWithMapping>& aMatchingContacts);
1.784 +protected:
1.785 + ~CContactRemoteViewBase();
1.786 + CContactRemoteViewBase(const CContactDatabase& aDb);
1.787 + void ConstructL(MContactViewObserver& aObserver);
1.788 +private:
1.789 + static TInt NotifierCallBack(TAny* aSelf);
1.790 + void HandleContactViewEvent(const TContactViewEvent& aEvent);
1.791 +protected:
1.792 + /** A handle to the server side view. */
1.793 + RContactRemoteView iView;
1.794 +private:
1.795 + CContactRemoteViewNotifier* iNotifier;
1.796 + /** Cached copy of the count of the local view in the contacts server.
1.797 + If this is KCachedItemCountInvalid then next time CountL is called
1.798 + the current count is retrieved from the contacts server. */
1.799 + mutable TInt iCount;
1.800 + };
1.801 +
1.802 +
1.803 +class CContactRemoteView : public CContactRemoteViewBase
1.804 +/** An instantiable remote contact view class.
1.805 +
1.806 +Remote views are associated with a CContactLocalView object held in the contacts
1.807 +server. They provide an efficient means for multiple clients to share the
1.808 +same underlying view.
1.809 +
1.810 +The view preferences and sort order are specified on construction.
1.811 +@publishedAll
1.812 +@released
1.813 +*/
1.814 + {
1.815 +public:
1.816 + IMPORT_C static CContactRemoteView* NewL(MContactViewObserver& aObserver,const CContactDatabase& aDb,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes);
1.817 + IMPORT_C static CContactRemoteView* NewL(MContactViewObserver& aObserver,const CContactDatabase& aDb,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes,
1.818 + const TDesC8& aSortPluginName);
1.819 + IMPORT_C void GetSortOrderL(RContactViewSortOrder& aSortOrder);
1.820 + //All derived classes of CContactViewBase that are public should mandatorily
1.821 + //implement this reserved exported virtual method.
1.822 + TAny* CContactViewBase_Reserved_1(TFunction aFunction,TAny* aParams);
1.823 +protected:
1.824 + ~CContactRemoteView();
1.825 + CContactRemoteView(const CContactDatabase& aDb);
1.826 +private:
1.827 + void ConstructL(MContactViewObserver& aObserver,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes);
1.828 + void ConstructL(MContactViewObserver& aObserver,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypesconst, const TDesC8& aSortPluginName);
1.829 + };
1.830 +
1.831 +
1.832 +class CContactNamedRemoteView : public CContactRemoteView
1.833 +/** A named remote contact view.
1.834 +
1.835 +This class enables multiple clients to share a named server side view. It
1.836 +also provides a function to change the sort order. If the sort order is changed,
1.837 +a notification is sent to all users of the named view.
1.838 +@publishedAll
1.839 +@released
1.840 +*/
1.841 + {
1.842 +public:
1.843 + IMPORT_C static CContactNamedRemoteView* NewL(MContactViewObserver& aObserver,const TDesC& aName,const CContactDatabase& aDb,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes);
1.844 + IMPORT_C static CContactNamedRemoteView* NewL(MContactViewObserver& aObserver,const TDesC& aName,const CContactDatabase& aDb,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes,
1.845 + const TDesC8& aSortPluginName);
1.846 + IMPORT_C void ChangeSortOrderL(const RContactViewSortOrder& aSortOrder);
1.847 + //All derived classes of CContactViewBase that are public should mandatorily
1.848 + //implement this reserved exported virtual method.
1.849 + TAny* CContactViewBase_Reserved_1(TFunction aFunction,TAny* aParams);
1.850 +private:
1.851 + ~CContactNamedRemoteView();
1.852 + CContactNamedRemoteView(const CContactDatabase& aDb);
1.853 + void ConstructL(MContactViewObserver& aObserver,const TDesC& aName,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes);
1.854 + void ConstructL(MContactViewObserver& aObserver,const TDesC& aName,const RContactViewSortOrder& aSortOrder,TContactViewPreferences aContactTypes, const TDesC8& aSortPluginName);
1.855 + };
1.856 +
1.857 +inline TContactViewEvent::TContactViewEvent()
1.858 +/** Empty default constructor. */
1.859 + {};
1.860 +
1.861 +inline TContactViewEvent::TContactViewEvent(TEventType aEventType,TInt aInt,TContactItemId aContactId) : iEventType(aEventType),iInt(aInt),iContactId(aContactId)
1.862 +/** Constructor with an event type and an optional error code and contact item ID.
1.863 +
1.864 +@param aEventType The event type.
1.865 +@param aInt Optional standard error code.
1.866 +@param aContactId Optional contact item ID. */
1.867 + {};
1.868 +
1.869 +inline void RContactViewSortOrder::AppendL(TFieldType aField)
1.870 +/** Appends a field type to the sort order object.
1.871 +
1.872 +@param aField The field type to append. */
1.873 + { User::LeaveIfError(iFields.Append(aField)); }
1.874 +
1.875 +inline TFieldType RContactViewSortOrder::operator[](TInt aIndex) const
1.876 +/** Gets an indexed field type.
1.877 +
1.878 +@param aIndex Index of the required field type. A panic occurs if this is
1.879 +invalid.
1.880 +@return The field type located at the indexed position in the array. */
1.881 + { return iFields[aIndex]; }
1.882 +
1.883 +inline TInt RContactViewSortOrder::Count() const
1.884 +/** Gets the number of field types in the sort order array.
1.885 +
1.886 +@return The number of field types in the array. */
1.887 + { return iFields.Count(); }
1.888 +
1.889 +inline TContactItemId CViewContact::Id() const
1.890 +/** Gets the view item's ID.
1.891 +
1.892 +@return The view item's ID. */
1.893 + {return iId;}
1.894 +
1.895 +inline CViewContact::TViewContactType CViewContact::ContactType() const
1.896 +/** Gets the view item's type.
1.897 +
1.898 +@return The view item's type. */
1.899 + {return iContactType;}
1.900 +
1.901 +inline void CViewContact::SetId(TContactItemId aId)
1.902 +/** Sets the view item's ID.
1.903 +
1.904 +@param aId The contact item ID. */
1.905 + {iId=aId;}
1.906 +
1.907 +inline void CViewContact::SetContactType(CViewContact::TViewContactType aContactType)
1.908 +/** Sets the view item's type.
1.909 +
1.910 +@param aContactType The view item's type. */
1.911 + {iContactType=aContactType;}
1.912 +#endif