CContactViewBase in Application Engines CNTMODEL

class CContactViewBase : public CBase;

Description

The abstract base class for all contact view classes.

All contact views operate asynchronously, so users of the view must observe it, by implementing the MContactViewObserver interface. Immediately after construction, views are not in a usable state (the underlying data may be being sorted, for instance). Only after the user has received a TContactViewEvent::EReady event may the view be used.

View observers are also notified when changes occur, for instance when the view's state changes (see TState), when an error occurs, or when an item is added or removed.

Derivation

CBase - Base class for all classes to be instantiated on the heap

CContactViewBase - The abstract base class for all contact view classes

Members

Defined in CContactViewBase:

AllFieldsLC()Returns a descriptor containing the contents of all fields for an item in the view
AtL()Returns the contact item ID at the specified index into the view
CContactViewBase()Protected C++ constructor
CContactViewBase_Reserved_1()This is a reserved virtual exported function that is used for BC proofing against addition of new exported virtual functions
Close()Removes an observer from the view's observer array
CompareFieldsL()Collates two contact items' field contents
ConstructL()Protected second phase constructor
ContactAtL()Returns the contact item at the specified index into the view
ContactViewPreferences()Gets the view preferences
ContactsMatchingCriteriaL()Searches all contact items in the view for fields that contain all of the search strings specified
ContactsMatchingPrefixL()Searches all contact items in the view for fields that contain all of the search strings specified
CountL()Returns the number of contact items in the view
ECContactViewBaseVirtualFunction1Identifies the function CContactViewBase::GetContactIdsL()
ECContactViewBaseVirtualFunction2Identifies the function CContactViewBase::GetContactsMatchingFilterL()
ECContactViewBaseVirtualFunction3Identifies the function CContactViewBase::InsertContactInView()
EFullSearchThe search uses full wildcard matching so that the search string can occur anywhere in the item's fields
EInitializingThe view is initialising
ENotReadyThe view is not ready to be used, for instance immediately after the sort order has changed, or after an error has occurred
EPrefixSearchThe search uses partial wildcard matching so that the search string can only occur at the beginning of the item's fields
EReadyThe view is ready to be used
Error()Gets the recorded error value
FieldsWithSeparatorLC()Allocates and returns a descriptor filled with the contents of all the fields in a contact item
FindL()Returns the index into the view of the specified contact item
GetContactIdsL()Gets an array containing the IDs of the contact items at the specified view indexes
GetViewFindConfigPlugin()Gets the UID of the view's find configuration plug-in, as set by SetViewFindConfigPlugin()
IdsEqual()Tests whether the IDs of two contact items are the same
IdsMatch()Tests whether the IDs of two contact items are the same
IndexesEqual()Tests whether the view indexes of two contact items are the same
MatchesCriteriaL()Searches a single contact item for fields that contain one or more search strings
MatchesCriteriaL()Searches a single contact item for fields that contain one or more search strings
MatchesCriteriaL()Searches a single contact item for fields that contain one or more search strings
NotifyObserverAsync()Called to notify a single view observer asynchronously of an event
NotifyObservers()Called by derived view classes to notify their observers synchronously of an event, by calling their HandleContactViewEvent() function
Open()Appends an observer to the view's observer array
OpenL()Appends an observer to the view's observer array
SetViewFindConfigPlugin()Sets the UID of the view's find configuration plug-in to use in calls to ContactsMatchingCriteriaL(), ContactsMatchingPrefixL() and MatchesCriteriaL()
SortOrderL()Gets the view's sort order
TFunctionIdentifies the functions that have been added to CContactViewBase, or that may be added in the future
TSearchTypeSearch type
TStateDefines the contact view states
TVirtualFunction1ParamsHolds the two parameters passed to the helper method GetContactIdsL() from the reserved function CContactViewBase_Reserved_1()
TVirtualFunction2ParamsHolds the two parameters passed to the method GetContactsMatchingFilterL() from the reserved function CContactViewBase_Reserved_1()
iDb
iExtension
iState
~CContactViewBase()Destructor

Inherited from CBase:

Delete()Deletes the specified object
Extension_()Extension function
operator new()Initialises the object to binary zeroes

protected: IMPORT_C ~CContactViewBase();

Description

Destructor.

Cancels all outstanding notifications and deletes all resources owned by the object.

protected: IMPORT_C void ConstructL();

Description

Protected second phase constructor.

Called from a derived class's ConstructL(). Creates the view's asynchronous notifier and adds it to the active scheduler.

protected: IMPORT_C CContactViewBase(const CContactDatabase &aDb);

Description

Protected C++ constructor.

Initialises the view's state to EInitializing.

Parameters

const CContactDatabase &aDb

The database that contains the contact items.

IMPORT_C void OpenL(MContactViewObserver &aObserver);

Description

Appends an observer to the view's observer array.

If the view's state is EReady, the observer is notified asynchronously that the view is ready.

An error causes the function to leave.

Parameters


                                 						MContactViewObserver &aObserver

The contact view observer to be added.

IMPORT_C TInt Open(MContactViewObserver &aObserver);

Description

Appends an observer to the view's observer array.

If the view's state is EReady, the observer is notified asynchronously that the view is ready.

This function does not leave; an error code is returned instead.

Parameters


                                 						MContactViewObserver &aObserver

The contact view observer to add.

Return value

TInt

A standard error code, or KErrNone if the function completed without an error.

Capability:

Illegal

IMPORT_C TBool Close(const MContactViewObserver &aObserver);

Description

Removes an observer from the view's observer array.

Any outstanding notifications for aObserver are first cancelled.

Parameters

const MContactViewObserver &aObserver

The contact view observer to be removed.

Return value

TBool

ETrue if the view's observer array is empty as a result of the removal; EFalse if it is not empty or if aObserver could not be found in the observer array.

Capability:

ReadUserData

virtual TContactItemId AtL(TInt aIndex) const=0;

Description

Returns the contact item ID at the specified index into the view.

Parameters


                                 						TInt aIndex

Index of the contact item ID into the view.

Return value

TContactItemId

The contact item ID.

Capability:

ReadUserData

virtual const CViewContact &ContactAtL(TInt aIndex) const=0;

Description

Returns the contact item at the specified index into the view.

Parameters


                                 						TInt aIndex

Index of the contact item into the view.

Return value

const CViewContact &

The contact item.

Capability:

ReadUserData

virtual TInt CountL() const=0;

Description

Returns the number of contact items in the view.

Return value

TInt

The number of contact items in the view.

Capability:

ReadUserData

virtual TInt FindL(TContactItemId aId) const=0;

Description

Returns the index into the view of the specified contact item.

Parameters


                                 						TContactItemId aId

The contact item ID to search for.

Return value

TInt

The index into the view of the contact item ID, or KErrNotFound if no matching ID can be found.

Capability:

ReadUserData

virtual HBufC *AllFieldsLC(TInt aIndex, const TDesC &aSeparator) const=0;

Description

Returns a descriptor containing the contents of all fields for an item in the view.

The field separator is used to separate the contents of each field. It is not appended to the last field.

Parameters

`TInt aIndex`	The index of the contact item into the view.
`const TDesC &aSeparator`	The string to use to separate the fields.

Return value

HBufC *

Pointer to the contact item descriptor.

Capability:

ReadUserData

virtual IMPORT_C void ContactsMatchingCriteriaL(const MDesC16Array &aFindWords, RPointerArray< CViewContact > &aMatchedContacts);

Description

Searches all contact items in the view for fields that contain all of the search strings specified.

The search uses wildcard matching so that the search strings can occur anywhere in the item's fields. For a match to occur, all of the search strings must be found in a contact item.

Parameters

`const MDesC16Array &aFindWords`	A descriptor array containing one or more search strings.
`RPointerArray< CViewContact > &aMatchedContacts`	On return, an array of matching contact items.

Capability:

ReadUserData

virtual TContactViewPreferences ContactViewPreferences()=0;

Description

Gets the view preferences.

Return value

TContactViewPreferences

The view preferences.

Capability:

ReadUserData

virtual const RContactViewSortOrder &SortOrderL() const=0;

Description

Gets the view's sort order.

Return value

const RContactViewSortOrder &

The sort order.

Capability:

ReadUserData

virtual IMPORT_C void ContactsMatchingPrefixL(const MDesC16Array &aFindWords, RPointerArray< CViewContact > &aMatchedContacts);

Description

Searches all contact items in the view for fields that contain all of the search strings specified.

Unlike ContactsMatchingCriteriaL(), the search term can only occur at the beginning of a field.

Parameters

`const MDesC16Array &aFindWords`	A descriptor array containing one or more search strings.
`RPointerArray< CViewContact > &aMatchedContacts`	On return, an array of matching contact items.

Capability:

ReadUserData

virtual IMPORT_C TAny *CContactViewBase_Reserved_1(TFunction aFunction, TAny *aParams);

Description

This is a reserved virtual exported function that is used for BC proofing against addition of new exported virtual functions. This function now aids addition of new exported virtual methods without having to break BC,by simply having those virtual methods as non-virtual and helper methods, called from this one and only reserved virtual exported method.A public enumeration type that is defined in the base class CContactViewBase identifies which of the helper 'virtual' methods are being called. All derived classes of CContactViewBase that are public should mandatorily implement this method.

Returns any return values of the helper methods called from this function.

Parameters

`TFunction aFunction`	an enum value that identifies which helper method is called.
`TAny *aParams`	parameters to the helper method being called.

Return value

TAny *

Any return values of the helper methods called from this function or NULL.

IMPORT_C void SetViewFindConfigPlugin(TUid aUid);

Description

Sets the UID of the view's find configuration plug-in to use in calls to ContactsMatchingCriteriaL(), ContactsMatchingPrefixL() and MatchesCriteriaL().

Parameters


                                 						TUid aUid

The UID of the view's find configuration plug-in.

IMPORT_C TUid GetViewFindConfigPlugin();

Description

Gets the UID of the view's find configuration plug-in, as set by SetViewFindConfigPlugin().

Return value

TUid

The UID of the view's find configuration plug-in. KNullUid if none has been set.

Capability:

ReadUserData

virtual IMPORT_C void GetContactIdsL(const CArrayFix< TInt > &aIndexes, CContactIdArray &aContactIds);

Description

Gets an array containing the IDs of the contact items at the specified view indexes.

The IDs are appended to the array.

Parameters

`const CArrayFix< TInt > &aIndexes`	An array of indexes into this view.
`CContactIdArray &aContactIds`	On return, an array to which the contact item IDs of each of the indexed items are appended.

IMPORT_C TInt Error() const;

Description

Gets the recorded error value. If an error occurs within the view, before each of the views observers are notified, then the view records the error code internally. This function provides access to a copy of that error code.

Return value

TInt

The recorded error value. If this does not equal KErrNone, then something is wrong with the view.

protected: IMPORT_C void NotifyObservers(const TContactViewEvent &aEvent);

Description

Called by derived view classes to notify their observers synchronously of an event, by calling their HandleContactViewEvent() function.

Parameters

const TContactViewEvent &aEvent

Identifies the event that occurred.

protected: IMPORT_C TInt NotifyObserverAsync(MContactViewObserver &aObserver, const TContactViewEvent &aEvent);

Description

Called to notify a single view observer asynchronously of an event.

If other notifications are outstanding, this notification is appended to the queue.

If the view's asynchronous notifier is not active, it is started as a background task.

This function is called by OpenL() and Open() to notify the observer that the view is ready.

Parameters

`MContactViewObserver &aObserver`	The contact view observer to notify. This must have previously been added to the view's observer array.
`const TContactViewEvent &aEvent`	Identifies the event that occurred.

Return value

TInt

KErrNone if the function completed without error, otherwise one of the standard error codes.

protected: static IMPORT_C TBool IdsMatch(const CViewContact &aFirst, const CViewContact &aSecond);

Description

Tests whether the IDs of two contact items are the same.

Parameters

`const CViewContact &aFirst`	The first contact item.
`const CViewContact &aSecond`	The second contact item.

Return value

TBool

True if the IDs match, otherwise false.

protected: IMPORT_C HBufC *FieldsWithSeparatorLC(const RPointerArray< CViewContact > &aContacts, TInt aIndex, const TDesC &aSeparator) const;

Description

Allocates and returns a descriptor filled with the contents of all the fields in a contact item.

The fields are separated by the specified separator.

Parameters

`const RPointerArray< CViewContact > &aContacts`	An array of contact items.
`TInt aIndex`	An index into the specified array.
`const TDesC &aSeparator`	The text to use to separate the fields.

Return value

HBufC *

A pointer to a heap descriptor containing the contents of each of the contact item's fields. The field separator is appended to each field except the last one. The pointer is left on the cleanup stack.

protected: virtual IMPORT_C TBool MatchesCriteriaL(const CViewContact &aContact, const MDesC16Array &aFindWords);

Description

Searches a single contact item for fields that contain one or more search strings.

The search uses wildcard matching so that the search strings can occur anywhere in any of the item's fields. For a match to occur, all of the search strings must be found in the contact item.

Any find configuration plug-in that has been set (by calling SetViewFindConfigPlugin()) will be used.

Parameters

`const CViewContact &aContact`	The contact item to search.
`const MDesC16Array &aFindWords`	A descriptor array containing one or more search strings.

Return value

TBool

True if all of the search strings were present in the contact item's fields. False if not.

protected: static IMPORT_C TBool MatchesCriteriaL(const CViewContact &aContact, const MDesC16Array &aFindWords, TSearchType aSearchType);

Description

Searches a single contact item for fields that contain one or more search strings.

The search type indicates whether the search strings can occur anywhere in a field, or must occur at the start of a field only. For a match to occur, all of the search strings must be found in the contact item.

This function does not use any find configuration plug-in that has been set (by calling SetViewFindConfigPlugin()), so new code should use one of the other overloads instead. This function has been maintained for binary compatibility with previous OS versions.

Parameters

`const CViewContact &aContact`	The contact item to search.
`const MDesC16Array &aFindWords`	A descriptor array containing one or more search strings.
`TSearchType aSearchType`	The search type. This controls whether a search term can occur anywhere in a contact item field, or just at the beginning of a field.

Return value

TBool

True if all of the search strings were present in the contact item's fields. False if not.

protected: static IMPORT_C TBool MatchesCriteriaL(const CViewContact &aContact, const MDesC16Array &aFindWords, TSearchType aSearchType, CContactViewBase::CContactViewBaseExtension *aExtension);

Description

Searches a single contact item for fields that contain one or more search strings.

The search type indicates whether the search strings can occur anywhere in a field, or must occur at the start of a field only. For a match to occur, all of the search strings must be found in the contact item.

If a find configuration plug-in UID is specified in the fourth parameter, this overload uses it, loading it first if necessary. This overrides any plug-in that had previously been set by a call to SetViewFindConfigPlugin().

Parameters

`const CViewContact &aContact`	The contact item to search.
`const MDesC16Array &aFindWords`	A descriptor array containing one or more search strings.
`TSearchType aSearchType`	The search type. This controls whether a search term can occur anywhere in a contact item field, or just at the beginning of a field.
`CContactViewBase::CContactViewBaseExtension *aExtension`	Optionally, this can be used to specify the UID of a find configuration plug-in, overriding any that has previously been set by a call to `SetViewFindConfigPlugin()`.

Return value

TBool

True if all of the search strings were present in the contact item's fields. False if not.

protected: static IMPORT_C TBool IdsEqual(const TContactIdWithMapping &aFirst, const TContactIdWithMapping &aSecond);

Description

Tests whether the IDs of two contact items are the same.

Parameters

`const TContactIdWithMapping &aFirst`	The contact ID/view index struct representing the first item.
`const TContactIdWithMapping &aSecond`	The contact ID/view index struct representing the second item.

Return value

TBool

True if the IDs match, false if not.

protected: static IMPORT_C TBool IndexesEqual(const TContactIdWithMapping &aFirst, const TContactIdWithMapping &aSecond);

Description

Tests whether the view indexes of two contact items are the same.

Parameters

`const TContactIdWithMapping &aFirst`	The contact ID/view index struct representing the first item.
`const TContactIdWithMapping &aSecond`	The contact ID/view index struct representing the second item.

Return value

TBool

True if the indexes match, false if not.

protected: static IMPORT_C TInt CompareFieldsL(const CViewContact &aFirst, const CViewContact &aSecond);

Description

Collates two contact items' field contents.

This is done by comparing each contact item on a field by field basis starting with the loosest collation level initially, and then progressing to tighter collation levels only if the items are considered the same at the looser level. This is required so that items differing by case only are sorted correctly. If a field isn't present, then the comparison is done using the first field that is present.

Parameters

`const CViewContact &aFirst`	The first contact item.
`const CViewContact &aSecond`	The second contact item.

Return value

TInt

A positive value indicates that aFirst's field contents are greater than aSecond's (so that aFirst would occur after aSecond in a sort order). A negative value indicates that aFirst's field contents are less than aSecond's (so that aFirst would occur before aSecond in a sort order). Zero indicates that aFirst and aSecond have identical field contents.

class TVirtualFunction1Params;

Description

Holds the two parameters passed to the helper method GetContactIdsL() from the reserved function CContactViewBase_Reserved_1(). It has an inline constructor to initialise the data members.

Members

Defined in CContactViewBase::TVirtualFunction1Params:

TVirtualFunction1Params()Inline constructor to initialize member data
iIdArrayPointer to array of contact IDs
iIndexesPointer to an array of indexes in a view

Construction and destruction

`TVirtualFunction1Params()`

inline TVirtualFunction1Params(const CArrayFix< TInt > *aIndexes, CContactIdArray *aIdArray);

Description

Inline constructor to initialize member data

Parameters

`const CArrayFix< TInt > *aIndexes`	Pointer to an array of indexes in a view
`CContactIdArray *aIdArray`	Pointer to array of contact IDs

Member data

`iIndexes`

const CArrayFix< TInt > * iIndexes;

Description

Pointer to an array of indexes in a view

`iIdArray`

CContactIdArray * iIdArray;

Description

Pointer to array of contact IDs

class TVirtualFunction2Params;

Description

Holds the two parameters passed to the method GetContactsMatchingFilterL() from the reserved function CContactViewBase_Reserved_1(). It has an inline constructor to initialise the data members.

Members

Defined in CContactViewBase::TVirtualFunction2Params:

TVirtualFunction2Params()Inline constructor to initialize member data
iFilterFilter for the contacts
iMatchingContactsList of contacts matching the criteria

Construction and destruction

`TVirtualFunction2Params()`

inline TVirtualFunction2Params(TInt aFilter, RArray< TContactIdWithMapping > &aMatchingContacts);

Description

Inline constructor to initialize member data.

Parameters

`TInt aFilter`	Filter for the contacts
`RArray< TContactIdWithMapping > &aMatchingContacts`	Contacts matching a particular criterion

Member data

`iFilter`

TInt iFilter;

Description

Filter for the contacts.

`iMatchingContacts`

RArray< TContactIdWithMapping > & iMatchingContacts;

Description

List of contacts matching the criteria.

TSearchType

Description

Search type.

This controls whether a search term can occur anywhere in a contact item field, or just at the beginning of the field.

`EFullSearch`	The search uses full wildcard matching so that the search string can occur anywhere in the item's fields.
`EPrefixSearch`	The search uses partial wildcard matching so that the search string can only occur at the beginning of the item's fields.

TFunction

Description

Identifies the functions that have been added to CContactViewBase, or that may be added in the future. This identifier is passed to the reserved virtual function CContactViewBase_Reserved_1() and enables the addition of new virtual methods without breaking binary compatibility.

`ECContactViewBaseVirtualFunction1`	Identifies the function `CContactViewBase::GetContactIdsL()`.
`ECContactViewBaseVirtualFunction2`	Identifies the function `CContactViewBase::GetContactsMatchingFilterL()`.
`ECContactViewBaseVirtualFunction3`	Identifies the function `CContactViewBase::InsertContactInView()`.

protected: TState

Description

Defines the contact view states.

EInitializing

The view is initialising.

This is the view's state immediately after construction or after a significant change (e.g CurrentDatabaseChanged or UnknownChanges), indicating that it can't be used yet.

EReady

The view is ready to be used.

ENotReady

The view is not ready to be used, for instance immediately after the sort order has changed, or after an error has occurred.

protected: const CContactDatabase & iDb;

Description

protected: TState iState;

Description

protected: CContactViewBaseExtension * iExtension;

Class CContactViewBase

Description

Derivation

Members

Construction and destruction