CContactViewBase Class Reference

#include <app/cntviewbase.h>

class CContactViewBase : public CBase, public CBase

Inherits from

Protected Attributes
const CContactDatabase &iDb
CContactViewBaseExtension *iExtension
TState iState
Public Member Enumerations
enumTFunction { ECContactViewBaseVirtualFunction1, ECContactViewBaseVirtualFunction2, ECContactViewBaseVirtualFunction3 }
enumTSearchType { EFullSearch, EPrefixSearch }
Protected Member Enumerations
enumTState { EInitializing, EReady, ENotReady }
Public Member Functions
pure virtual HBufC *AllFieldsLC(TInt, const TDesC &)
pure virtual TContactItemId AtL(TInt)
virtual IMPORT_C TAny *CContactViewBase_Reserved_1(TFunction, TAny *)
IMPORT_C TBoolClose(const MContactViewObserver &)
pure virtual const CViewContact &ContactAtL(TInt)
pure virtual TContactViewPreferences ContactViewPreferences()
virtual IMPORT_C voidContactsMatchingCriteriaL(const MDesCArray &, RPointerArray< CViewContact > &)
virtual IMPORT_C voidContactsMatchingCriteriaL(const MDesC16Array &, RPointerArray< CViewContact > &)
virtual IMPORT_C voidContactsMatchingPrefixL(const MDesCArray &, RPointerArray< CViewContact > &)
virtual IMPORT_C voidContactsMatchingPrefixL(const MDesC16Array &, RPointerArray< CViewContact > &)
pure virtual TInt CountL()
IMPORT_C TIntError()
pure virtual TInt FindL(TContactItemId)
virtual IMPORT_C voidGetContactIdsL(const CArrayFix< TInt > &, CContactIdArray &)
IMPORT_C TUidGetViewFindConfigPlugin()
IMPORT_C TUidGetViewSortPluginImplUid()
IMPORT_C TIntOpen(MContactViewObserver &)
IMPORT_C voidOpenL(MContactViewObserver &)
IMPORT_C voidSetViewFindConfigPlugin(TUid)
pure virtual const RContactViewSortOrder &SortOrderL()
Protected Member Functions
CContactViewBase(const CContactDatabase &)
~CContactViewBase()
IMPORT_C TIntCompareContactIds(const CViewContact &, const CViewContact &)
IMPORT_C TIntCompareContactsAndIdsL(const CViewContact &, const CViewContact &)
IMPORT_C TIntCompareFieldsL(const CViewContact &, const CViewContact &)
IMPORT_C voidConstructL()
IMPORT_C TBoolContactIsSortable(const CViewContact &)
IMPORT_C HBufC *FieldsWithSeparatorLC(const RPointerArray< CViewContact > &, TInt, const TDesC &)
TUid FindDefaultViewSortPluginImplL()
TUid FindSortPluginImplL(const TDesC8 &, TBool)
IMPORT_C TBoolIdsEqual(const TContactIdWithMapping &, const TContactIdWithMapping &)
IMPORT_C TBoolIdsMatch(const CViewContact &, const CViewContact &)
IMPORT_C TBoolIndexesEqual(const TContactIdWithMapping &, const TContactIdWithMapping &)
TInt InsertContactInView(RPointerArray< CViewContact > &, const CViewContact *, TBool, TInt *)
TBool IsContactSortable(const CViewContact &, TContactViewPreferences &)
voidLoadViewSortPluginL(TUid, TContactViewPreferences &)
virtual IMPORT_C TBoolMatchesCriteriaL(const CViewContact &, const MDesCArray &)
virtual IMPORT_C TBoolMatchesCriteriaL(const CViewContact &, const MDesC16Array &)
IMPORT_C TBoolMatchesCriteriaL(const CViewContact &, const MDesCArray &, TSearchType)
IMPORT_C TBoolMatchesCriteriaL(const CViewContact &, const MDesC16Array &, TSearchType)
IMPORT_C TBoolMatchesCriteriaL(const CViewContact &, const MDesCArray &, TSearchType, CContactViewBase::CContactViewBaseExtension *)
IMPORT_C TBoolMatchesCriteriaL(const CViewContact &, const MDesC16Array &, TSearchType, CContactViewBase::CContactViewBaseExtension *)
IMPORT_C TIntNotifyObserverAsync(MContactViewObserver &, const TContactViewEvent &)
IMPORT_C voidNotifyObservers(const TContactViewEvent &)
CViewContactSortPlugin *SortPluginImpl()
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()

Detailed 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.

Member Attribute Documentation

iDb

const CContactDatabase &iDb[protected]

iExtension

CContactViewBaseExtension *iExtension[protected]

iState

TState iState[protected]

Member Enumeration Documentation

Enum TFunction

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.

EnumeratorValueDescription
ECContactViewBaseVirtualFunction1

Identifies the function CContactViewBase::GetContactIdsL().

ECContactViewBaseVirtualFunction2

Identifies the function CContactViewBase::GetContactsMatchingFilterL().

ECContactViewBaseVirtualFunction3

Identifies the function CContactViewBase::InsertContactInView().

Enum TSearchType

Search type.

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

EnumeratorValueDescription
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.

Enum TState

Defines the contact view states.

EnumeratorValueDescription
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.

Constructor & Destructor Documentation

CContactViewBase ( const CContactDatabase & )

IMPORT_CCContactViewBase(const CContactDatabase &aDb)[protected]

Protected C++ constructor.

Initialises the view's state to EInitializing.

Parameters
aDbThe database that contains the contact items.

~CContactViewBase ( )

IMPORT_C~CContactViewBase()[protected]

Destructor.

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

Member Function Documentation

AllFieldsLC ( TInt, const TDesC & )

HBufC *AllFieldsLC(TIntaIndex,
const TDesC &aSeparator
)const [pure virtual]

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
aIndexThe index of the contact item into the view.
aSeparatorThe string to use to separate the fields.
Return Value
Pointer to the contact item descriptor.
Capability
ReadUserData

AtL ( TInt )

TContactItemId AtL(TIntaIndex)const [pure virtual]

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

Parameters
aIndexIndex of the contact item ID into the view.
Return Value
The contact item ID.
Capability
ReadUserData

CContactViewBase_Reserved_1 ( TFunction, TAny * )

IMPORT_C TAny *CContactViewBase_Reserved_1(TFunctionaFunction,
TAny *aParams
)[virtual]

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
aFunctionan enum value that identifies which helper method is called.
aParamsparameters to the helper method being called.
Return Value
Any return values of the helper methods called from this function or NULL.
Capability
ReadUserData

Close ( const MContactViewObserver & )

IMPORT_C TBoolClose(const MContactViewObserver &aObserver)

Removes an observer from the view's observer array.

Any outstanding notifications for aObserver are first cancelled.

Parameters
aObserverThe contact view observer to be removed.
Return Value
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
None

CompareContactIds ( const CViewContact &, const CViewContact & )

IMPORT_C TIntCompareContactIds(const CViewContact &aFirst,
const CViewContact &aSecond
)[protected, static]

CompareContactsAndIdsL ( const CViewContact &, const CViewContact & )

IMPORT_C TIntCompareContactsAndIdsL(const CViewContact &aFirst,
const CViewContact &aSecond
)const [protected]

Used for view sorting and insersion. In order to give a stable result if contact details match, it falls back to comparing contact IDs. If a contact view sort plugin is loaded it uses its SortCompareViewContactsL() method.

CompareFieldsL ( const CViewContact &, const CViewContact & )

IMPORT_C TIntCompareFieldsL(const CViewContact &aFirst,
const CViewContact &aSecond
)[protected, static]

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
aFirstThe first contact item.
aSecondThe second contact item.
Return Value
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.

ConstructL ( )

IMPORT_C voidConstructL()[protected]

Protected second phase constructor.

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

ContactAtL ( TInt )

const CViewContact &ContactAtL(TIntaIndex)const [pure virtual]

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

Parameters
aIndexIndex of the contact item into the view.
Return Value
The contact item.
Capability
ReadUserData

ContactIsSortable ( const CViewContact & )

IMPORT_C TBoolContactIsSortable(const CViewContact &aContact)[protected, static]

Asks the contact if it is sortable. 'static' function used by Sort Plugin.

ContactViewPreferences ( )

TContactViewPreferences ContactViewPreferences()[pure virtual]

Gets the view preferences.

Return Value
The view preferences.
Capability
ReadUserData

ContactsMatchingCriteriaL ( const MDesCArray &, RPointerArray< CViewContact > & )

IMPORT_C voidContactsMatchingCriteriaL(const MDesCArray &aFindWords,
RPointerArray< CViewContact > &aMatchedContacts
)[virtual]

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
aFindWordsA descriptor array containing one or more search strings.
aMatchedContactsOn return, an array of matching contact items.
Capability
ReadUserData

ContactsMatchingCriteriaL ( const MDesC16Array &, RPointerArray< CViewContact > & )

IMPORT_C voidContactsMatchingCriteriaL(const MDesC16Array &aFindWords,
RPointerArray< CViewContact > &aMatchedContacts
)[virtual]

ContactsMatchingPrefixL ( const MDesCArray &, RPointerArray< CViewContact > & )

IMPORT_C voidContactsMatchingPrefixL(const MDesCArray &aFindWords,
RPointerArray< CViewContact > &aMatchedContacts
)[virtual]

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
aFindWordsA descriptor array containing one or more search strings.
aMatchedContactsOn return, an array of matching contact items.
Capability
ReadUserData

ContactsMatchingPrefixL ( const MDesC16Array &, RPointerArray< CViewContact > & )

IMPORT_C voidContactsMatchingPrefixL(const MDesC16Array &aFindWords,
RPointerArray< CViewContact > &aMatchedContacts
)[virtual]

CountL ( )

TInt CountL()const [pure virtual]

Returns the number of contact items in the view.

Return Value
The number of contact items in the view.
Capability
ReadUserData

Error ( )

IMPORT_C TIntError()const

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
The recorded error value. If this does not equal KErrNone, then something is wrong with the view.

FieldsWithSeparatorLC ( const RPointerArray< CViewContact > &, TInt, const TDesC & )

IMPORT_C HBufC *FieldsWithSeparatorLC(const RPointerArray< CViewContact > &aContacts,
TIntaIndex,
const TDesC &aSeparator
)const [protected]

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
aContactsAn array of contact items.
aIndexAn index into the specified array.
aSeparatorThe text to use to separate the fields.
Return Value
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.

FindDefaultViewSortPluginImplL ( )

TUid FindDefaultViewSortPluginImplL()const [protected]

FindL ( TContactItemId )

TInt FindL(TContactItemIdaId)const [pure virtual]

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

Parameters
aIdThe contact item ID to search for.
Return Value
The index into the view of the contact item ID, or KErrNotFound if no matching ID can be found.
Capability
ReadUserData

FindSortPluginImplL ( const TDesC8 &, TBool )

TUid FindSortPluginImplL(const TDesC8 &aSortPluginName,
TBoolaWildCard = EFalse
)const [protected]

GetContactIdsL ( const CArrayFix< TInt > &, CContactIdArray & )

IMPORT_C voidGetContactIdsL(const CArrayFix< TInt > &aIndexes,
CContactIdArray &aContactIds
)[virtual]

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

The IDs are appended to the array.

Parameters
aIndexesAn array of indexes into this view.
aContactIdsOn return, an array to which the contact item IDs of each of the indexed items are appended.
Capability
ReadUserData

GetViewFindConfigPlugin ( )

IMPORT_C TUidGetViewFindConfigPlugin()

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

See also: CContactViewFindConfigInterface

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

GetViewSortPluginImplUid ( )

IMPORT_C TUidGetViewSortPluginImplUid()const

IdsEqual ( const TContactIdWithMapping &, const TContactIdWithMapping & )

IMPORT_C TBoolIdsEqual(const TContactIdWithMapping &aFirst,
const TContactIdWithMapping &aSecond
)[protected, static]

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

Parameters
aFirstThe contact ID/view index struct representing the first item.
aSecondThe contact ID/view index struct representing the second item.
Return Value
True if the IDs match, false if not.

IdsMatch ( const CViewContact &, const CViewContact & )

IMPORT_C TBoolIdsMatch(const CViewContact &aFirst,
const CViewContact &aSecond
)[protected, static]

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

Parameters
aFirstThe first contact item.
aSecondThe second contact item.
Return Value
True if the IDs match, otherwise false.

IndexesEqual ( const TContactIdWithMapping &, const TContactIdWithMapping & )

IMPORT_C TBoolIndexesEqual(const TContactIdWithMapping &aFirst,
const TContactIdWithMapping &aSecond
)[protected, static]

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

Parameters
aFirstThe contact ID/view index struct representing the first item.
aSecondThe contact ID/view index struct representing the second item.
Return Value
True if the indexes match, false if not.

InsertContactInView ( RPointerArray< CViewContact > &, const CViewContact *, TBool, TInt * )

TInt InsertContactInView(RPointerArray< CViewContact > &aContacts,
const CViewContact *aNewContact,
TBoolaSortByIdOnly,
TInt *aIndex
)const [protected]

Does a binary search of the contacts array, and inserts a new contact. Uses the current sort plugin, if any.

IsContactSortable ( const CViewContact &, TContactViewPreferences & )

TBool IsContactSortable(const CViewContact &aContact,
TContactViewPreferences &aViewPreferences
)const [protected]

This function determines whether a contact should be added to the normal sorted array (iContacts) or put into the alternative iUnSortedContacts array. Depending on the view preferences, these "unsorted" contacts are either ignored (deleted), or added to the beginning or end of the iContacts sorted list by At(), Find() etc... methods.

LoadViewSortPluginL ( TUid, TContactViewPreferences & )

voidLoadViewSortPluginL(TUidaSortPluginUid,
TContactViewPreferences &aViewPreferences
)[protected]

MatchesCriteriaL ( const CViewContact &, const MDesCArray & )

IMPORT_C TBoolMatchesCriteriaL(const CViewContact &aContact,
const MDesCArray &aFindWords
)[protected, virtual]

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
aContactThe contact item to search.
aFindWordsA descriptor array containing one or more search strings.
Return Value
True if all of the search strings were present in the contact item's fields. False if not.

MatchesCriteriaL ( const CViewContact &, const MDesC16Array & )

IMPORT_C TBoolMatchesCriteriaL(const CViewContact &aContact,
const MDesC16Array &aFindWords
)[protected, virtual]

MatchesCriteriaL ( const CViewContact &, const MDesCArray &, TSearchType )

IMPORT_C TBoolMatchesCriteriaL(const CViewContact &aContact,
const MDesCArray &aFindWords,
TSearchTypeaSearchType
)[protected, static]

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
aContactThe contact item to search.
aFindWordsA descriptor array containing one or more search strings.
aSearchTypeThe 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
True if all of the search strings were present in the contact item's fields. False if not.

MatchesCriteriaL ( const CViewContact &, const MDesC16Array &, TSearchType )

IMPORT_C TBoolMatchesCriteriaL(const CViewContact &aContact,
const MDesC16Array &aFindWords,
TSearchTypeaSearchType
)[protected, static]

MatchesCriteriaL ( const CViewContact &, const MDesCArray &, TSearchType, CContactViewBase::CContactViewBaseExtension * )

IMPORT_C TBoolMatchesCriteriaL(const CViewContact &aContact,
const MDesCArray &aFindWords,
TSearchTypeaSearchType,
CContactViewBase::CContactViewBaseExtension *aExtension
)[protected, static]

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
aContactThe contact item to search.
aFindWordsA descriptor array containing one or more search strings.
aSearchTypeThe search type. This controls whether a search term can occur anywhere in a contact item field, or just at the beginning of a field.
aExtensionOptionally, 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
True if all of the search strings were present in the contact item's fields. False if not.

MatchesCriteriaL ( const CViewContact &, const MDesC16Array &, TSearchType, CContactViewBase::CContactViewBaseExtension * )

IMPORT_C TBoolMatchesCriteriaL(const CViewContact &aContact,
const MDesC16Array &aFindWords,
TSearchTypeaSearchType,
CContactViewBase::CContactViewBaseExtension *aExtension
)[protected, static]

NotifyObserverAsync ( MContactViewObserver &, const TContactViewEvent & )

IMPORT_C TIntNotifyObserverAsync(MContactViewObserver &aObserver,
const TContactViewEvent &aEvent
)[protected]

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
aObserverThe contact view observer to notify. This must have previously been added to the view's observer array.
aEventIdentifies the event that occurred.
Return Value
KErrNone if the function completed without error, otherwise one of the standard error codes.

NotifyObservers ( const TContactViewEvent & )

IMPORT_C voidNotifyObservers(const TContactViewEvent &aEvent)[protected]

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

Parameters
aEventIdentifies the event that occurred.

Open ( MContactViewObserver & )

IMPORT_C TIntOpen(MContactViewObserver &aObserver)

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
aObserverThe contact view observer to add.
Return Value
A standard error code, or KErrNone if the function completed without an error.

OpenL ( MContactViewObserver & )

IMPORT_C voidOpenL(MContactViewObserver &aObserver)

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
aObserverThe contact view observer to be added.

SetViewFindConfigPlugin ( TUid )

IMPORT_C voidSetViewFindConfigPlugin(TUidaUid)

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

See also: CContactViewFindConfigInterface

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

SortOrderL ( )

const RContactViewSortOrder &SortOrderL()const [pure virtual]

Gets the view's sort order.

Return Value
The sort order.
Capability
ReadUserData

SortPluginImpl ( )

CViewContactSortPlugin *SortPluginImpl()const [protected]