Virtual Phonebook View Definition API Specification Document

Changes in Virtual Phonebook View Definition documentation

Version Date Status Description

1.0

04.01.2007

Approved

Changes in Virtual Phonebook View Definition API

Version Description

1.0

First version

Purpose

The purpose of Virtual Phonebook View Definition API is to provide services for defining details of a contact view. The details include view name, type, URI, sorting policy and possible subviews. The API also supports creating a filter for the contact view definition.

A contact view is a sorted collection of contacts. The URI of a view identifies the contact database used for getting the view data.

API description

Virtual Phonebook View Definition API can be categorized as a library API with a normal method call interface.

After creating the view definition, the CVPbkContactManager (the root access point to the Virtual Phonebook Engine functionality) can create the contact view by using the view definition.

There are four types of views: the contacts view, groups view, folding view and composite view. The views are represented by the four enumerations as EVPbkContactsView, EVPbkGroupsView, EVPbkFoldingView and EVPbkCompositeView. The first two types of view cannot have subviews while the other two types of view can have subviews.

This API is meant for applications that need to view and modify contact data.

Use cases

The most common use cases of the View Definition API are the following:

  • Defining and creating different types of contact views

  • Creating filters for the contact view definition

API class structure

The classes of Virtual Phonebook View Definition API are shown in Figure 1.

Class diagram of Virtual Phonebook View...


Class diagram of Virtual Phonebook View Definition API

The class CVPbkContactViewDefinition is derived from CBase and the class VPbkContactViewFilterBuilder only defines one static method.

Related APIs
  • CBase
  • CVPbkContactViewDefinition
  • VPbkContactViewFilterBuilder
Related APIs
  • CVPbkContactManager
  • EVPbkCompositeView
  • EVPbkContactsView
  • EVPbkFoldingView
  • EVPbkGroupsView

Using Virtual Phonebook View Definition API

The class CVPbkContactViewDefinition has three constructors from which the commonly used version is reading the view definition structure VPBK_CONTACT_VIEW from the resource file. The two other versions are used for creating an empty class or a copy of an existing class.

See VPbkContactView.hrh for more information about VPBK_CONTACT_VIEW.

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
  • MVPbkFieldTypeList

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()
  • TRAP
  • VPbkContactViewFilterBuilder::BuildContactViewFilterL()

Extensions to the API

Virtual Phonebook View Definition API does not explicitly support any kinds of extensions.

Related APIs
  • CVPbkContactViewDefinition
  • VPBK_CONTACT_VIEW
  • VPbkContactView.hrh

Glossary

Abbreviations

None.

Definitions

None.

References

[1] Phonebook 2 Presentation API Specification