Defining and creating different types of contact views
The
example below demonstrates how to define contact views.
//
An example contacts view definition // RESOURCE VPBK_CONTACT_VIEW r_contact_view
{ uri = "cntdb://c:contacts.cdb"; type = EVPbkContactsView; subViews
= {}; } // An example contact groups view definition // RESOURCE VPBK_CONTACT_VIEW
r_group_view { uri = "cntdb://c:contacts.cdb"; type = EVPbkGroupsView;
subViews = {}; } // An example folding view definition // RESOURCE VPBK_CONTACT_VIEW
r_folding_contact_view { name = "Folding view demo"; type = EVPbkFoldingView;
subViews = { VPBK_CONTACT_VIEW { uri = "cntdb://c:contacts.cdb";
} }; } // An example composite view definition // This view combines
contacts from C-drive and SIM card into the same view // RESOURCE VPBK_CONTACT_VIEW
r_composite_contact_view { type = EVPbkCompositeView; sortPolicy = EVPbkSortedContactView;
subViews = { VPBK_CONTACT_VIEW { uri = "cntdb://c:contacts.cdb";
}, VPBK_CONTACT_VIEW { uri = "sim://global_on";
} }; }
After defining the contents
of the view, the sorting order is needed. An instance of
MVPbkFieldTypeList is
needed for the sorting. The following example resource definition could be
used to instantiate the MVPbkFieldTypeList implementation.
The example
selects three contacts fields as an input for the sorting. For more information
about view sorting, see reference document
/1/.
RESOURCE
ARRAY r_sortorder_example { items = { VPBK_FIELD_TYPE_MAPPING
{ versitProperty = VBK_FIELD_VERSIT_PROPERTY
{ name = EVPbkVersitNameN; subField
= EVPbkVersitSubFieldGivenName; }; },
VPBK_FIELD_TYPE_MAPPING { versitProperty = VBK_FIELD_VERSIT_PROPERTY
{ name = EVPbkVersitNameN;
subField = EVPbkVersitSubFieldFamilyName; };
}, VPBK_FIELD_TYPE_MAPPING { versitProperty
= VBK_FIELD_VERSIT_PROPERTY { name = EVPbkVersitNameTEL;
parameters = { EVPbkVersitParamHOME, EVPbkVersitParamCELL
}; }; } }; }
Finally,
when the preparations have been made, the view can be created. The following
code snippet demonstrates how to create a contact view according to the specified
view definition.
Please note that these code clips only highlight the
steps needed in the operation. For a more detailed example, see the example
application VPbkViewDef.
// Client class implements
MVPbkContactStoreListObserver and MVPbkContactViewObserver // MVPbkContactStoreListObserver
is used to observe the contact store opening // MVPbkContactViewObserver is
used to observe the contact view creation // Define three class members: //
CVPbkContactManager* iContactManager; // MVPbkContactViewBase* iView;
// RFs& iRfs; // Resource file path // Assumption: the definitions
shown above are found from ViewDefDemo.rss // _LIT( KResFile, "z:\\resource\\apps\\ViewDefDemo.rsc"
); // Constants for the contacts database URI // _LIT( KCntDbUri, "cntdb://c:contacts.cdb"
); _LIT( KSimDbUri, "sim://global_onb" ); // Create an URI list // CVPbkContactStoreUriArray*
uriList = CVPbkContactStoreUriArray::NewLC(); uriList->AppendL( TVPbkContactStoreUriPtr(
KCntDbUri ) ); uriList->AppendL( TVPbkContactStoreUriPtr( KSimDbUri ) );
// Instantiate CVPbkContactManager. Use a File Server session asked e.g. from
the // Control Environment (CONE). If there is no File Server session parameter
available, // the contact manager will create a new one. // iRFs = CCoeEnv::Static()->FsSession();
iContactManager = CVPbkContactManager::NewL( *uriList, &iRFs ); // Open
the contact stores asynchronously that used by the view // Use MVPbkContactStoreListObserver
to observe the process // MVPbkContactStoreList& stores = iContactManager->ContactStoresL();
stores.OpenAllL( *this ); // Clean up temporary variables // CleanupStack::PopAndDestroy(
uriList ); // Read the View Definition from resource file // RResourceFile
resFile; CleanupClosePushL( resFile ); resFile.OpenL( iRFs, KResFile ); TResourceReader
reader; // Read the required view definition resource, such as R_CONTACT_VIEW
// R_GROUP_VIEW, R_FOLDING_CONTACT_VIEW or R_COMPOSITE_CONTACT_VIEW // HBufC8*
buffer = resFile.AllocReadLC( R_CONTACT_VIEW ); reader.SetBuffer( buffer );
// Instantiate the View Definition CVPbkContactViewDefinition* def = CVPbkContactViewDefinition::NewL(
reader ); CleanupStack::Pop( buffer ); delete buffer; buffer = NULL; CleanupStack::PushL(
def ); // Read the Sort Order definition from resource file // buffer = resFile.AllocReadLC(
R_SORTORDER_DEMO ); reader.SetBuffer( buffer ); // Instantiate the CVPbkSortOrder
// CVPbkSortOrder* sortOrder = CVPbkSortOrder::NewL( reader, iContactManager->FieldTypes()
); CleanupStack::PushL( sortOrder ); // Create the contact view asynchronously
when all contact stores are opened // Use MVPbkContactViewObserver to observe
the process // MVPbkContactViewBase* view = iContactManager->CreateContactViewLC(
*this, *def, *sortOrder ); CleanupStack::Pop(); // Note: Using CleanupStack::Pop(view)
will leave // Clean up // CleanupStack::PopAndDestroy( sortOrder ); CleanupStack::PopAndDestroy(
buffer ); CleanupStack::PopAndDestroy( def ); CleanupStack::PopAndDestroy(
&resFile ); // The view cannot be used before it has notified the observer
that the view is ready. // In the callback MVPbkContactViewObserver::ContactViewReady(
MVPbkContactViewBase& aView ), // get the contact view // iView = &aView;
Related APIs
Creating
filters for the contact view definition
A field type filter
is used to filter the contents in the view. If the filter is set to the view
definition, the view will contain only contacts having the fields defined
by the filter.
The following code snippet demonstrates how to create
a filter for the contact view definition. Please note that these code clips
only highlight the steps needed in the operation. For more detailed example,
see the example application VPbkViewDef.
#include
<VPbkContactView.hrh> // Make preparations // ... // Instantiate the
View Definition // CVPbkContactViewDefinition* def = CVPbkContactViewDefinition::NewL(
reader ); CleanupStack::PushL( def ); // Construct an empty filter // CVPbkFieldTypeSelector*
filter = CVPbkFieldTypeSelector::NewL( iContactManager->FieldTypes()
); CleanupStack::PushL( filter ); // Build the contact view filter // There
are some pre-defined filters in file "VPbkContactView.hrh", such as // EVPbkContactViewFilterMobileNumber,
EVPbkContactViewFilterPhoneNumber etc. // VPbkContactViewFilterBuilder::BuildContactViewFilterL
( *filter, EVPbkContactViewFilterMobileNumber, *iContactManager );
// Set the filter for View Definition // def->SetFieldTypeFilterL( filter
); // If the View is defined as EVPbkCompositeView, // every sub view
should set the filter respectively // const TInt subViewCount = def->SubViewCount();
for ( TInt i = 0; i < subViewCount; ++i ) { ( def->SubViewAt( i
) ).SetFieldTypeFilterL( filter ); } // Clean up // CleanupStack::PopAndDestroy(
filter ); // Creating the contact view // The view that is created by using
this View Definition will contain only // the contacts having the field R_VPBK_MOBILE_NUMBER_SELECTOR
// ...
Error
handling
CVPbkContactViewDefinition::AddSubViewL(),
CVPbkContactViewDefinition::SetUriL(), CVPbkContactViewDefinition::SetNameL(),
CVPbkContactViewDefinition::SetFieldTypeFilterL() and VPbkContactViewFilterBuilder::BuildContactViewFilterL()
leave in case of an error situation. Normal error handling practices should
be used, e.g. cleanup stack and TRAP harness.
Related APIs
CVPbkContactViewDefinition::AddSubViewL()CVPbkContactViewDefinition::SetFieldTypeFilterL()CVPbkContactViewDefinition::SetNameL()CVPbkContactViewDefinition::SetUriL()TRAPVPbkContactViewFilterBuilder::BuildContactViewFilterL()