Class CContactLocalView

class CContactLocalView : public CContactViewBase, public MContactDbObserver;

Description

An instantiable base class for contact views.

The data associated with a local view is allocated within the client's memory space; CContactRemoteView should be used in preference if the view is likely to be shared between multiple clients. It is kept up to date by receiving change events from the underlying CContactDatabase object which it observes. The view preferences and sort order are specified on construction.

Derivation

• MContactDbObserver - The interface for an observer that handles changes to a contact database

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

• CContactViewBase - The abstract base class for all contact view classes

• CContactLocalView - An instantiable base class for contact views

Members

Defined in CContactLocalView:
AllFieldsLC(), AtL(), CContactLocalView(), CContactLocalView_Reserved_1(), CContactLocalView_Reserved_2(), CContactViewBase_Reserved_1(), ConstructL(), ContactAtL(), ContactViewPreferences(), CountL(), FindL(), HandleDatabaseEventL(), InsertL(), NewL(), NewL(), RemoveL(), SortL(), SortOrder(), SortOrderL(), iSortOrder, ~CContactLocalView()

Inherited from CBase:
Delete(), Extension_(), operator new()

Inherited from CContactViewBase:
Close(), CompareFieldsL(), ContactsMatchingCriteriaL(), ContactsMatchingPrefixL(), ECContactViewBaseVirtualFunction1, ECContactViewBaseVirtualFunction2, ECContactViewBaseVirtualFunction3, EFullSearch, EInitializing, ENotReady, EPrefixSearch, EReady, Error(), FieldsWithSeparatorLC(), GetContactIdsL(), GetViewFindConfigPlugin(), IdsEqual(), IdsMatch(), IndexesEqual(), MatchesCriteriaL(), NotifyObserverAsync(), NotifyObservers(), Open(), OpenL(), SetViewFindConfigPlugin(), TFunction, TSearchType, TState, TVirtualFunction1Params, TVirtualFunction2Params, iDb, iExtension, iState

See also

• ContactViews: Using contact database views

static IMPORT_C CContactLocalView *NewL(MContactViewObserver &aObserver, const CContactDatabase &aDb, const RContactViewSortOrder &aSortOrder, TContactViewPreferences aContactTypes);

Description

Allocates and constructs the local view object.

The view is sorted according to the sort order and view preferences specified, using a low priority idle time active object. The specified view observer is notified when the view is sorted and ready for use.

Parameters

MContactViewObserver &aObserver An observer that receives notifications when this view is ready for use and when changes take place in it. The observer receives a TContactViewEvent::EReady event when the view is ready. Any attempt to use the view before this notification will Leave with KErrNotReady const CContactDatabase &aDb The underlying database that contains the contact items. The view observes the database, so that it handles change events sent from the database. const RContactViewSortOrder &aSortOrder Specifies the fields to use to sort the items in the view. TContactViewPreferences aContactTypes Specifies which types of contact items should be included in the view and the behaviour for items that do not have content in any of the fields specified in the sort order.

Return value

CContactLocalView * The newly constructed local view object.

static IMPORT_C CContactLocalView *NewL(MContactViewObserver &aObserver, const CContactDatabase &aDb, const RContactViewSortOrder &aSortOrder, TContactViewPreferences aContactTypes, const TDesC8 &aSortPluginName);

Description

Allocates and constructs the local view object.

The view is sorted according to the sort order and view preferences specified, using a low priority idle time active object. The specified view observer is notified when the view is sorted and ready for use.

Parameters

MContactViewObserver &aObserver An observer that receives notifications when this view is ready for use and when changes take place in it. The observer receives a TContactViewEvent::EReady event when the view is ready. Any attempt to use the view before this notification will Leave with KErrNotReady const CContactDatabase &aDb The underlying database that contains the contact items. The view observes the database, so that it handles change events sent from the database. const RContactViewSortOrder &aSortOrder Specifies the fields to use to sort the items in the view. TContactViewPreferences aContactTypes Specifies which types of contact items should be included in the view and the behaviour for items that do not have content in any of the fields specified in the sort order. const TDesC8 &aSortPluginName Specifies a plug-in that will be used to compare view contacts when the the view is sorted. This name is used by ECOM to select the plugin, and is matched with the "default_data" of all ECOM plugins that support the required interface.

Return value

CContactLocalView * The newly constructed local view object.

protected: IMPORT_C ~CContactLocalView();

Description

Destructor.

Deletes all resources owned by the object, and removes itself as the contact database observer.

protected: IMPORT_C CContactLocalView(const CContactDatabase &aDb, TContactViewPreferences aContactTypes);

Description

Protected C++ constructor.

Called by NewL().

Parameters

const CContactDatabase &aDb The underlying database that contains the contact items. TContactViewPreferences aContactTypes Specifies which types of contact items should be included in the view and the behaviour for items that do not have content in any of the fields specified in the sort order.

protected: IMPORT_C void ConstructL(MContactViewObserver &aObserver, const RContactViewSortOrder &aSortOrder);

Description

Protected second phase constructor.

The view is sorted according to the sort order and view preferences specified, using a low priority idle time active object. The specified view observer is notified when the view is sorted and ready for use.

Called by NewL().

Parameters

MContactViewObserver &aObserver An observer that receives notifications when this view is ready for use and when changes take place in it. The observer receives a TContactViewEvent::EReady event when the view is ready. Any attempt to use the view before this notification will Leave with KErrNotReady. const RContactViewSortOrder &aSortOrder Specifies the fields to use to sort the items in the view.

IMPORT_C const RContactViewSortOrder &SortOrder() const;

Description

Gets the sort order, as set during construction.

Return value

const RContactViewSortOrder & The sort order.

virtual TContactItemId AtL(TInt aIndex) const;

Description

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

Parameters

TInt aIndex An index into the view.

Return value

TContactItemId The ID of the contact item at the specified index.

Leave codes

KErrNotFound The index is out of bounds. KErrNotReady The view is not ready for use.

virtual TInt CountL() const;

Description

Gets the total number of contact items in the view.

Return value

TInt The number of contact items in the view. This includes both sorted and unsorted items.

Leave codes

KErrNotReady The view is not ready for use.

virtual TInt FindL(TContactItemId aId) const;

Description

Searches for a contact item in the view with the specified ID.

Parameters

TContactItemId aId The ID of the contact item to search for.

Return value

TInt If found, the index into the view of the matching item. Otherwise, KErrNotFound.

Leave codes

KErrNotReady The view is not ready for use.

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

Description

Gets a descriptor containing the contents of all fields specified in the view's sort order 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.

virtual const CViewContact &ContactAtL(TInt aIndex) const;

Description

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

Parameters

TInt aIndex An index into the view.

Return value

const CViewContact & The contact item at the specified index.

Leave codes

KErrNotFound The index is out of bounds. KErrNotReady The view is not ready for use.

virtual TContactViewPreferences ContactViewPreferences();

Description

Gets the view preferences, as set during construction.

Return value

TContactViewPreferences The view preferences.

virtual const RContactViewSortOrder &SortOrderL() const;

Description

Gets the sort order, as set during construction.

This function cannot leave.

Return value

const RContactViewSortOrder & The sort order.

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.

protected: virtual IMPORT_C void SortL(const RContactViewSortOrder &aSortOrder);

Description

Sorts the view using the specified sort order, using a low priority idle time active object.

This function is called during view construction and on receipt of certain change events from the underlying database.

Parameters

const RContactViewSortOrder &aSortOrder Specifies the fields to use to sort the items in the view.

protected: virtual IMPORT_C TInt InsertL(TContactItemId aId);

Description

Inserts a contact item into the view, maintaining the view's sort order.

For the item to be inserted, it must exist in the underlying database, and it must be of the correct type according to the view preferences.

This function is called when a contact item or group is added to or changed in the underlying database.

Parameters

TContactItemId aId The ID of a contact item that exists in the underlying database.

Return value

TInt The index at which the item was inserted into the view, or KErrNotFound if the contact item was not found in the underlying database, or it already exists in the view.

protected: virtual IMPORT_C TInt RemoveL(TContactItemId aId);

Description

Removes a contact item from the view.

This function is called when a contact item or group is deleted from or changed in the underlying database.

Parameters

TContactItemId aId The ID of the contact item to remove from the view.

Return value

TInt The index of the removed item into the view's list of sorted or unsorted contact items, or KErrNotFound if the item was not found in the view.

private: virtual void HandleDatabaseEventL(TContactDbObserverEvent aEvent);

Description

Tests the contact database observer event type and handles it. The ID of a contact affected by the change event, if relevant, can be retrieved via TContactDbObserverEvent::iContactId.

Parameters

TContactDbObserverEvent aEvent Provides information about the change event.

private: virtual IMPORT_C void CContactLocalView_Reserved_1();

Description

private: virtual IMPORT_C void CContactLocalView_Reserved_2();

Description

protected: RContactViewSortOrder iSortOrder;

Description

The sort order.

This is set during construction.