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