Purpose

The purpose of Virtual Phonebook Engine API is to provide functions for accessing the essential Virtual Phonebook functionality, including opening contact stores, creating contact views, managing the contact attributes and finding contacts against the search criteria.

Virtual Phonebook Engine API also supports functions for manipulating contact field and contact data.

In order to use those functions easily, Virtual Phonebook Engine API also provides a lot of helper classes, such as contact store URI classes which help to create the URI list for opening the contact store, contact attributes classes which help to set a different attribute to the contact field, contact field type classes which help to creating contact fields, contact links and contact fields classes which help to manipulating the contact data, etc.

The API also provides some utility classes.

API description

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

The core class of this API is CVPbkContactManager, which is the root access point to Virtual Phonebook Engine functionality.

This API is meant for applications that need to manipulate contact data.

Use cases

The most common use cases of Virtual Phonebook Engine API are the following:

  • Opening contact stores

  • Creating contact views

  • Managing contact attributes

    • Managing the existing contact attributes

    • Editing the contact attributes

    • Finding all contacts by the specified attribute condition

  • Finding contacts

  • Creating contact field type list

  • Manipulating contact data

    • Creating contacts

    • Retrieving contact data

    • Copying contacts

    • Deleting contacts

    • Filtering contacts

  • Managing top contacts

  • Managing xsp IDs

API class structure

The main class of Virtual Phonebook Engine API are shown in Figure 1.

Class diagram of CVPbkContactManager


Class diagram of CVPbkContactManager

The class CVPbkContactManager is derived from CBase.

Related APIs
  • CBase
  • CVPbkContactManager
Related APIs
  • CVPbkContactManager

Using Virtual Phonebook Engine API

The class CVPbkContactManager supports the fundamental functions for Virtual Phonebook Engine, such as opening the contact store. It is almost the necessary step for all the other use cases.

Opening contact stores

The following code snippet demonstrates how to open the Contact Model store and SIM Contact store. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

 //
Client application class implements MVPbkContactStoreListObserver // MVPbkContactStoreListObserver
is used to observe the contact store opening // Define four class members:
//     CVPbkContactManager* iContactManager; //     RFs iRfs; //     MVPbkContactStoreList*
iStores; //     MVPbkContactStore* iStore;  // 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’s no File Server session parameter
available,  // the contact manager will create a new one. // iRFs = CCoeEnv::Static()->FsSession();
CVPbkContactManager* iContactManager = CVPbkContactManager::NewL( *uriList,
&iRFs );  // Clean up temporary variable // CleanupStack::PopAndDestroy(
uriList );  // Get all contact store list //  iStores = &iContactManager->ContactStoresL();
 // If open all contact stores asynchronously,doing as below // Use MVPbkContactStoreListObserver
to observe the process // iStores->OpenAllL( *this );  // If open one contact
store, such as cntdb://c:contacts.cdb, doing as below // Find the contact
store // iStore = iStores->Find( TVPbkContactStoreUriPtr( KCntDbUri ) ); 
// Open this contact store asynchronously // Use MVPbkContactStoreListObserver
to observe the process // iStore->Open( *this );   

The following code snippet demonstrates how to replace an existing contact store and opens it asynchronously. Using this method, if the store does not exist, the contact store is created if possible.

 // Replace
an existing store and opens it asynchronously // Use MVPbkContactStoreListObserver
to observe the process // iStore->Replace( *this );  

When shutting down the application, MVPbkContactStoreList and MVPbkContactStore should be closed properly.

// Use MVPbkContactStoreListObserver
to observe the process // if( iContactManager )     {         TRAP_IGNORE(
iContactManager->ContactStoresL().CloseAll( *this ) );     } delete iStore;
delete iStores delete iContactManager;   

Related APIs
  • MVPbkContactStore
  • MVPbkContactStoreList
  • VPbkContManagerEx

Creating contact views

CVPbkContactManager::CreateContactViewLC( MVPbkContactViewObserver& aObserver, const CVPbkContactViewDefinition& aViewDefinition, const MVPbkFieldTypeList& aSortOrder) can create a different type of contact view by reading the view definition from the CVPbkContactViewDefinition instance. Please refer to Virtual Phonebook View Definition API specification and example application VPbkViewDefEx for details about how to create contact view.

Related APIs
  • CVPbkContactViewDefinition
  • VPbkViewDefEx

Managing contact attributes

Virtual Phonebook Engine API provides an abstract interface class MVPbkContactAttributeManager to manage the attributes of the contact: Default Attribute, Speed Dial Attribute and Voice Tag Attribute.

Managing the existing attributes

Client can do something with the existing attributes of a contact or a field, e.g. to check if a contact has an attribute matching the given attribute, or to search a field with a given attribute in a contact. The following code snippet demonstrates how to check if a contact has been assigned a speed dial attribute. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkAttrManagerEx.

 //
Define two class members: //     CVPbkContactManager* iContactManager; //
    MVPbkStoreContact* iStoreContact; // Assumption: CVPbkContactManager have
been initialized as section "Opening contact stores"; //             iStoreContact
holds a specified contact  // Get contact attribute manager // MVPbkContactAttributeManager
attrManager =     iContactManager->ContactAttributeManagerL();      // Check
if a contact has been assigned a speed dial index // TBool hasSpeedDial =
attManage.HasContactAttributeL(     CVPbkSpeedDialAttribute::Uid(),     *iStoreContact
);  

Below is another example code for finding the field which has a default attribute.

 // Define
three class members: //     CVPbkContactManager* iContactManager; //     MVPbkStoreContact*
iStoreContact; //     TVPbkDefaultType  iType; // Assumption: CVPbkContactManager
have been initialized as section "Opening contact stores"; //            
iStoreContact holds a specified contact; //             iType holds a given
default attribute type  // Create a default attribute of the given type //
CVPbkDefaultAttribute* attr = CVPbkDefaultAttribute::NewL( iType );  // Get
contact attribute manage // MVPbkContactAttributeManager attrManager =   
 iContactManager->ContactAttributeManagerL();  // Get the fields // MVPbkStoreContactFieldCollection*
typeFields =     attrManager.FindFieldsWithAttributeLC( *attr, *iStoreContact
);  if ( typeFields && ( typeFields->FieldCount() > 0 ) )     {  
  // Handle the found fields.     ...     }  CleanupStack::PopAndDestroy();
// typeFields 

Related APIs
  • VPbkAttrManagerEx

Editing the attributes

Users can also edit the attribute of a contact or a field, e.g. to set the contact attribute for a given contact, or to remove the given attribute from a given contact.

The editing methods are all asynchronous calls. These operations are observed by MVPbkSetAttributeObserver. The result of the attribute operation will be passed to the MVPbkSetAttributeObserver::AttributeOperationComplete() method if the operation succeeded. If the operation failed, the reason can be got from the MVPbkSetAttributeObserver::AttributeOperationFailed() method.

The following code snippet demonstrates how to remove the speed dial attribute of a field. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkAttrManagerEx.

 //
Client application class implements MVPbkSetAttributeObserver // Define three
class members: //     CVPbkContactManager* iContactManager; //     MVPbkStoreContactField*
iField; //     MVPbkContactOperationBase* iOp; // Assumption: CVPbkContactManager
have been initialized as section "Opening contact stores"; //            
iField holds a specified field  // Get contact attribute manager // MVPbkContactAttributeManager
attrManager =      iContactManager->ContactAttributeManagerL();  //Remove
the field attribute // iOp = attrManager.RemoveFieldAttributeL( *iField, 
    CVPbkSpeedDialAttribute::Uid(), *this ) 

When the remove operation finished successfully, the callback method MVPbkSetAttributeObserver::AttributeOperationComplete( MVPbkContactOperationBase& aOperation ) will be invoked. The following code snippet demonstrates some typical operations in this method.

 If
( &aOperation != iOp )     return; // Do cleaning up // delete iOp; iOp
= NULL;  //Do something after removing the attribute. ... 

If the remove operation failed, the callback method MVPbkSetAttributeObserver::AttributeOperationFailed( MVPbkContactOperationBase& aOperation, TIne aError ) will be invoked. The following code snippet demonstrates some typical operations in this method.

 If ( &aOperation != iOp )    
return; // Do cleaning up // delete iOp; iOp = NULL;    // Get error code.
// TInt errCode = aError; 

Related APIs
  • MVPbkSetAttributeObserver
  • MVPbkSetAttributeObserver::AttributeOperationComplete()
  • MVPbkSetAttributeObserver::AttributeOperationFailed()
  • VPbkAttrManagerEx

Finding all contacts by the specified attribute condition

In this use case, users can find all contacts having the given attribute or having the given requested type of attribute.

Finding methods are all asynchronous calls and the operations are observed by MVPbkContactFindObserver. The matching contact links will be passed to MVPbkContactFindObserver::FindCompleteL() method if the operation succeeds. If the operation failed, the reason can be got from MVPbkContactFindObserver::FindFailed() method.

The following code snippet demonstrates how to find all contacts which have the speed dial attribute. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkAttrManagerEx.

 //
Client application class implements MVPbkContactFindObserver // Define two
class members: //     CVPbkContactManager* iContactManager; //     MVPbkContactOperationBase*
iOp; // Assumption: CVPbkContactManager have been initialized as section "Opening
contact stores"  // Get contact attribute manager // MVPbkContactAttributeManager
attrManager =      iContactManager->ContactAttributeManagerL();  //Find the
contacts // iOp = attrManager.ListContactsL ( CVPbkSpeedDialAttribute::Uid(),
*this ) 

When the above operation finished successfully, the callback method MVPbkContactFindObserver::FindCompleteL( MVPbkContactLinkArray* aResults) will be invoked. The following code snippet demonstrates some typical operations in this method.

 // Do cleaning
up. // delete iOp; iOp = NULL;  // Handle the found contact link array. ... 

When the above operation failed, the callback method MVPbkContactFindObserver::FindFailed(TInt aError) will be invoked. The following code snippet demonstrates some typical operations in this method.

 // Do cleaning
up. // delete iOp; iOp = NULL;  // Get error code. // TInt errCode = aError; 

Related APIs
  • MVPbkContactFindObserver
  • MVPbkContactFindObserver::FindCompleteL()
  • MVPbkContactFindObserver::FindFailed()
  • VPbkAttrManagerEx
Related APIs
  • MVPbkContactAttributeManager

Finding contacts

Virtual Phonebook Engine API provides two types of contact finding. One is searching the contact stores for a phone number using defined amount of digits from the end of the number, the other is searching the contact stores for contacts that contain the given string in one of the field defined by the given field type list.

Finding methods are all asynchronous calls. The finding operation can be cancelled either by deleting the MVPbkContactOperationBase object returned by finding methods or by deleting CVPbkPhoneNumberMatchStrategy instance.

For finding contacts by matching phone number, the API supports two ways for this function. The simpler way is using CVPbkContactManager::MatchPhoneNumberL(), the other and more functional way is using class CVPbkPhoneNumberMatchStrategy which supports more complicated matching mechanism. Finding operation is observed by MVPbkContactFindObserver. The matching contact links will be passed to MVPbkContactFindObserver::FindCompleteL() method if the operation succeeds. If the operation failed, the reason can be got from MVPbkContactFindObserver:: FindFailed() method.

The following code snippet demonstrates how to find contacts by using CVPbkContactManager::MatchPhoneNumberL(). Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

 //
Client application class implements MVPbkContactFindObserver // CVPbkContactManager
and MVPbkContactStore have been initialized  // as section "Opening contact
stores" // Define two class members: //     MVPbkContactLinkArray* iFindResults;
//     MVPbkContactOperationBase* iOp;  // Phone number to be searched for
// _LIT( KMatchNo, "123456" );  // Create find operation iOp = iContactManager->MatchPhoneNumberL(
    KMatchNo, KMatchNo().Length(), *this );  // In the callback MVPbkContactFindObserver::FindCompleteL
// ( MVPbkContactLinkArray* aResults), get the found contact links // and
do cleaning up. //  delete iFindResults; iFindResults = NULL; iFindResults
= aResults; delete iOp; iOp = NULL;  // In the callback MVPbkContactFindObserver::FindFailed(TInt
aError), // get the reason of operation failure and do cleaning up. // delete
iOp; iOp = NULL;  

The following code snippet demonstrates how to find contacts by using CVPbkPhoneNumberMatchStrategy. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

 //
Client application class implements MVPbkContactFindObserver // CVPbkContactManager
and MVPbkContactStore have been initialized  // as Section "Opening contact
stores" // Define two class members: //     MVPbkContactLinkArray* iFindResults;
//     CVPbkPhoneNumberMatchStrategy* iPhoneNumberMatchStrategy;  // Maximum
number of digits used in matching // const TInt KMatchDigits = 6;  // 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 ) ); 
// Create configuration for CVPbkPhoneNumberMatchStrategy // The created configuration
ensures to perform sequentially search for each store  // and guarantees that
only contacts with an exact match are included in the result set. // CVPbkPhoneNumberMatchStrategy::TConfig
config( KMatchDigits, *uriList,      CVPbkPhoneNumberMatchStrategy::EVPbkSequentialMatch,
    CVPbkPhoneNumberMatchStrategy::EVPbkExactMatchFlag );   // Instantiate
the CVPbkPhoneNumberMatchStrategy // For the reason of reusing CVPbkPhoneNumberMatchStrategy
instance,  // the instantiation is always done in constructor of client application
class. // iPhoneNumberMatchStrategy = CVPbkPhoneNumberMatchStrategy::NewL
    ( config, *iContactManager, *this );  // Clean up the CVPbkContactStoreUriArray
// The cleanup can not be done before initiating the CVPbkPhoneNumberMatchStrategy
// CleanupStack::PopAndDestroy( uriList );  

After instantiating CVPbkPhoneNumberMatchStrategy, it can be used to find the contacts.

 // Phone number to be searched
for // _LIT( KMatchNo, "123456" );  // Find contacts iPhoneNumberMatchStrategy->MatchL(
KMatchNo );  // In the callback MVPbkContactFindObserver::FindCompleteL //
( MVPbkContactLinkArray* aResults), get the found contact link. //  delete
iFindResults; iFindResults = NULL; iFindResults = aResults;  

For the reason of reusing the CVPbkPhoneNumberMatchStrategy instance, the cleanup is always done in the destructor of the client application class.

There are two methods supported by the API for finding contacts by matching given string: CVPbkContactManager::FindL(const TDesC& aSearchString, const MVPbkFieldTypeList& aFieldTypes, MVPbkContactFindObserver& aObserver) and CVPbkContactManager::FindL(const MDesC16Array& aSearchStrings, const MVPbkFieldTypeList& aFieldTypes, MVPbkContactFindFromStoresObserver& aObserver, const TCallBack& aWordParserCallBack). The second method performs finding multiple find words that are stored in one or more fields and the client should implement a word parser that separates the field data into words.

The following code snippet demonstrates how to find contacts by using CVPbkContactManager::FindL(const TDesC& aSearchString, const MVPbkFieldTypeList& aFieldTypes, MVPbkContactFindObserver& aObserver). This method uses MVPbkContactFindObserver to observe the finding operation. The matching contact links will be passed to the MVPbkContactFindObserver::FindCompleteL() method if the operation succeeds. If the operation failed, the reason can be got from the MVPbkContactFindObserver:: FindFailed() method. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

 #include
<VPbkEng.rsg>  // the resource file that contains all the field type definition
 // Client application class implements MVPbkContactFindObserver // CVPbkContactManager
and MVPbkContactStore have been initialized  // as section "Opening contact
stores" // Define two class members: //     MVPbkContactLinkArray* iFindResult;
//     MVPbkContactOperationBase* iOp;  // String to be searched for // _LIT(
KMatchTxt, "TestName" );  // Find from last, first and company names field
// FieldTypeList is created by selecting Field Type definition from  // Virtual
Phonebook Engine resource. // CVPbkFieldTypeRefsList* fieldTypeRefList = CVPbkFieldTypeRefsList::NewL();
fieldTypeRefList->AppendL(      *iContactManager->FieldTypes().Find( R_VPBK_FIELD_TYPE_LASTNAME
) ); fieldTypeRefList->AppendL(      *iContactManager->FieldTypes().Find(
R_VPBK_FIELD_TYPE_FIRSTNAME ) ); fieldTypeRefList->AppendL(      *iContactManager->FieldTypes().Find(
R_VPBK_FIELD_TYPE_COMPANYNAME ) );      // Create the find operation // iOp
= iContactManager->FindL( KMatchTxt, *fieldTypeRefList, *this );  // Clean
up temporary variable // delete fieldTypeRefList;  // In the callback MVPbkContactFindObserver::FindCompleteL
// ( MVPbkContactLinkArray* aResults), get the found contact links // and
do cleaning up. //  delete iFindResults; iFindResults = NULL; iFindResult
= aResults; delete iOp;  // In the callback MVPbkContactFindObserver::FindFailed(TInt
aError), // get the reason of operation failure and do cleaning up. // delete
iOp; iOp = NULL;  

The following code snippet demonstrates how to find contacts by using CVPbkContactManager::FindL(const MDesC16Array& aSearchStrings, const MVPbkFieldTypeList& aFieldTypes, MVPbkContactFindFromStoresObserver& aObserver, const TCallBack& aWordParserCallBack). Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

Define a word parser function that separates the field data into words.

 //
This parser assumes Other characters than alpha digit are separators // TInt
VPbkParseDataL( TAny* aParam ) {     TVPbkWordParserCallbackParam* param =
         static_cast<TVPbkWordParserCallbackParam*>( aParam );     const
TText* ptr = param->iStringToParse->Ptr();     const TText* end = ptr + param->iStringToParse->Length();
    const TText* startOfWord = NULL;     FOREVER     {     // Other than alpha
digit are separators     if (ptr==end || !TChar(*ptr).IsAlphaDigit())    
    {         if (startOfWord)             {             TPtrC addWord(startOfWord,ptr-startOfWord);
            param->iWordArray->AppendL(addWord);             startOfWord=NULL;
            }         if (ptr==end)             break;         }     else
if (!startOfWord)         startOfWord=ptr;     ptr++;     }     return KErrNone;
}  

After defining the parser, FindL can use that to search the contact store. This method uses MVPbkContactFindFromStoresObserver to observe the find operation. MVPbkContactFindFromStoresObserver::FindFromStoreSucceededL is called when one store completes its find. MVPbkContactFindFromStoresObserver::FindFromStoreFailed is called when a find operation of one store fails, but the find operation from other stores continues in the case there are multiple stores. MVPbkContactFindFromStoresObserver::FindFromStoresOperationComplete is called after all stores have called either FindFromStoreSucceed or FindFromStoreFailed.

 #include <VPbkEng.rsg> // the resource file that contains all the field
type definition  // Client application class implements MVPbkContactFindFromStoresObserver
// CVPbkContactManager and MVPbkContactStore have been initialized  // as
section "Opening contact stores" // Define two class members: //     CVPbkContactLinkArray*
iFindResults; //     MVPbkContactOperationBase* iOp;  // String to be searched
for // _LIT( KMatchTxt, "FirstName LastName" );  // Create an array for search
strings // TInt granularity = 2; CDesCArrayFlat*  searchStrings = new( ELeave
) CDesCArrayFlat( granularity );  // Separate find words using the same parser
that is given to store  // for field data parsing // TVPbkWordParserCallbackParam
param( &KMatchTxt, searchStrings ); VPbkParseDataL( &param );  //
Find from last, first and company names field // FieldTypeList is created
by selecting Field Type definition from  // Virtual Phonebook Engine resource.
// CVPbkFieldTypeRefsList* fieldTypeRefList = CVPbkFieldTypeRefsList::NewL();
fieldTypeRefList->AppendL(      *iContactManager->FieldTypes().Find( R_VPBK_FIELD_TYPE_LASTNAME
) ); fieldTypeRefList->AppendL(      *iContactManager->FieldTypes().Find(
R_VPBK_FIELD_TYPE_FIRSTNAME ) ); fieldTypeRefList->AppendL(      *iContactManager->FieldTypes().Find(
R_VPBK_FIELD_TYPE_COMPANYNAME ) );      // Create the find operation // iOp
= iContactManager->FindL( *searchStrings, *fieldTypeRefList, *this,      
  TCallBack( VPbkParseDataL ) );  // Clean up temporary variables // delete
searchStrings; delete fieldTypeRefList;  // In the callback MVPbkContactFindFromStoresObserver::FindFromStoreSucceededL
// ( MVPbkContactStore& aStore, MVPbkContactLinkArray* aResultsFromStore
),  // get the found contact links. //  CleanupDeletePushL( aResults ); const
TInt count = aResults->Count(); for ( TInt i = 0; i < count; ++i )    
{     iFindResults->AppendL( aResults->At( i ).CloneLC() );     CleanupStack::Pop();
// cloned link } CleanupStack::PopAndDestroy(); // aResults  // In the callback
MVPbkContactFindFromStoresObserver::FindFromStoreFailed // ( MVPbkContactStore&
aStore, TInt aError ), get the reason of operation failure.  // In the callback
MVPbkContactFindFromStoresObserver::FindFromStoresOperationComplete(), //
do cleaning up. // delete iOp; iOp = NULL;  

Related APIs
  • CVPbkContactManager::MatchPhoneNumberL()
  • CVPbkPhoneNumberMatchStrategy
  • FindFromStoreFailed
  • FindFromStoreSucceed
  • FindL
  • MVPbkContactFindFromStoresObserver
  • MVPbkContactFindFromStoresObserver::FindFromStoreFailed
  • MVPbkContactFindFromStoresObserver::FindFromStoreSucceededL
  • MVPbkContactFindFromStoresObserver::FindFromStoresOperationComplete
  • MVPbkContactFindObserver
  • MVPbkContactFindObserver::FindCompleteL()
  • MVPbkContactOperationBase
  • VPbkContManagerEx

Creating contact field type list

A field type list instance is a collection of Virtual Phonebook field types. It is used when manipulating contact data or creating contact views.

CVPbkSortOrder is a field type list and usually used in creating contact views to determine the field sort order in the view. Please refer to Virtual Phonebook View Definition API specification and example application VPbkViewDefEx for details on how to instantiate CVPbkSortOrder instance.

CVPbkFieldTypeRefsList is a collection of referenced Virtual Phonebook field types and usually used in creating contact data or find contacts. The following code snippets demonstrate how to instantiate CVPbkFieldTypeRefsList. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

Define the resource for creating the contact field:

//
type for the first name field RESOURCE VPBK_FIELD_TYPE_MAPPING r_fname_type
    {     versitProperty = VBK_FIELD_VERSIT_PROPERTY         {         name
= EVPbkVersitNameN;         subField = EVPbkVersitSubFieldGivenName;     
   };     }  // type for the last name field RESOURCE VPBK_FIELD_TYPE_MAPPING
r_lname_type     {     versitProperty = VBK_FIELD_VERSIT_PROPERTY        
{         name = EVPbkVersitNameN;         subField = EVPbkVersitSubFieldFamilyName;
        };     }  //type for the cell phone number field RESOURCE VPBK_FIELD_TYPE_MAPPING
r_tel_cell_type     {     versitProperty = VBK_FIELD_VERSIT_PROPERTY     
   {         name = EVPbkVersitNameTEL;         parameters = { EVPbkVersitParamCELL
};         };                     }   

Reading the resource and creating the contact field type list:

 //
Resource file path // Assumption: the definitions shown above are found from
VPbkEngineEx.rss // _LIT( KResFile, "z:\\resource\\apps\\VPbkEngineEx.rsc"
);  // Instance of CVPbkFieldTypeRefsList // CVPbkFieldTypeRefsList* fieldTypeRefList
= CVPbkFieldTypeRefsList::NewL();  // Read the field type mapping from resource
file // RResourceFile resFile; CleanupClosePushL(resFile); resFile.OpenL(iRFs,
KResFile); TResourceReader reader; HBufC8* buffer = resFile.AllocReadLC( R_FNAME_TYPE
); reader.SetBuffer(buffer);  // Get the field type   TVPbkFieldTypeMapping
typeMapping( reader ); const MVPbkFieldType* fieldType = typeMapping.FindMatch(
iContactManager->FieldTypes() );  // Append to field type list fieldTypeRefList->AppendL(
*fieldType );       CleanupStack::PopAndDestroy( buffer );  // Create another
two field type and append to the field type list // ..  // Clean up temporary
variable // CleanupStack::PopAndDestroy( &resFile ); 

There is another way to creating the contact field type list.

 #include
<VPbkEng.rsg> // the resource file that contains all the field type definition
 // CVPbkFieldTypeRefsList is created by selecting Field Type definition 
// from Virtual Phonebook Engine resource. // CVPbkFieldTypeRefsList* fieldTypeRefList
= CVPbkFieldTypeRefsList::NewL(); fieldTypeRefList->AppendL(      *iContactManager->FieldTypes().Find(
R_VPBK_FIELD_TYPE_FIRSTNAME ) ); fieldTypeRefList->AppendL(      *iContactManager->FieldTypes().Find(
R_VPBK_FIELD_TYPE_LASTNAME ) ); fieldTypeRefList->AppendL(      *iContactManager->FieldTypes().Find(
R_VPBK_FIELD_TYPE_MOBILEPHONEGEN ) );  

Related APIs
  • CVPbkFieldTypeRefsList
  • CVPbkSortOrder
  • VPbkContManagerEx
  • VPbkViewDefEx

Manipulating contact data

Virtual Phonebook Engine API supports functions for creating contacts, copying contacts between two contact stores, modifying contact data, deleting contacts and filtering contacts, etc.

Creating contacts

CVPbkContactManager::CommitContactsL() method supports committing a collection of newly created or modified store contacts to contact stores. It is an asynchronous call and can be cancelled by deleting the MVPbkContactOperationBase object returned by committing methods.

Another way is to commit the store contact one by one by using MVPbkStoreContact::CommitL

The following code snippet demonstrates how to creating one contact and commit it by using MVPbkStoreContact::CommitL. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

 //
Client application class implements MVPbkContactObserver // CVPbkContactManager
and MVPbkContactStore have been initialized  // as section "Opening contact
stores" // Define one class member: //     MVPbkStoreContact* iStoreContact;
//  // Assumption: CVPbkFieldTypeRefsList instance fieldTypeRefList has been
 //             created as section "Creating contact field type list".  //
Create the new contact // iStoreContact = iStore->CreateNewContactLC();  //
Create contact field for contact // MVPbkStoreContactField* field = iStoreContact->CreateFieldLC(
fieldTypeRefList->FieldTypeAt( 0 ) );  // Set contact field data // _LIT(KFirstName,"FirstName");
 (MVPbkContactFieldTextData::Cast(field->FieldData())).SetTextL( KFirstName
);  // Add the contact field to contact // iStoreContact->AddFieldL( field
); CleanupStack::Pop(); // field  // Create other two contact fields and add
to the contact // ...  // Commit the new created contact to contact store
// The operation is observed by MVPbkContactObserver // iStoreContact->CommitL(
*this );    CleanupStack::Pop(); // iStoreContact  // In the callback MVPbkContactObserver::ContactOperationCompleted
// ( TContactOpResult aResult ), do cleaning up // delete iStoreContact; iStoreContact
= NULL;  // In the callback MVPbkContactObserver::ContactOperationFailed(TContactOp
aOpCode,  // TInt aErrorCode, TBool aErrorNotified), get the reason of operation
failure  // and do cleaning up.  

Related APIs
  • CVPbkContactManager::CommitContactsL()
  • MVPbkContactOperationBase
  • MVPbkStoreContact::CommitL
  • VPbkContManagerEx

Retrieving contact data

The CVPbkContactManager::RetrieveContactL() method supports retrieving a store contact against MVPbkContactLink. It is an asynchronous call and can be cancelled by deleting the MVPbkContactOperationBase object returned by retrieving methods.

The following code snippet demonstrates how to retrieve contact from contact store. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

 //
Client application class implements MVPbkSingleContactOperationObserver //
CVPbkContactManager and MVPbkContactStore have been initialized  // as section
"Opening contact stores" // Define three class member: //     MVPbkContactLink*
iContactLink; //     MVPbkStoreContact* iStoreContact; //     MVPbkContactOperationBase*
iOp;  // Create the instance of MVPbkContactLink implementation, such as creating
// MVPbkContactLink from MVPbkViewContact.  // Assumption: MVPbkContactViewBase*
iView has been created and the view is not empty //             The view is
a contact view. // iContactLink = iView->ContactAtL( 0 )->CreateLinkLC();
 // Create the retrieve operation // iOp = iContactManager->RetrieveContactL(
*iContactLink, *this );  // In the callback MVPbkSingleContactOperationObserver::VPbkSingleContactOperationComplete(
// MVPbkContactOperationBase& aOperation, MVPbkStoreContact* aContact),
 // get the retrieved store contact and do cleaning up. // delete iStoreContact;
iStoreContact = NULL; iStoreContact = &aContact; if( iOp = &aOperation
) {     delete iOp;     iOp = NULL; }  // In the callback MVPbkSingleContactOperationObserver::VPbkSingleContactOperationFailed(
// MVPbkContactOperationBase& aOperation, TInt aError), get the reason
of operation failure and do cleaning up.  

Related APIs
  • CVPbkContactManager::RetrieveContactL()
  • MVPbkContactLink
  • MVPbkContactOperationBase
  • VPbkContManagerEx

Copying contacts

There are two ways to copy contacts to another contact store or to duplicate the contacts in the same store. CVPbkContactManager::CopyContactsL() is same as CVPbkContactCopier when CVPbkContactCopier is working in EVPbkSimpleContactCopy mode. CVPbkContactCopier also supports EVPbkUseStoreSpecificCopyPolicy and EVPbkUsePlatformSpecificDuplicatePolicy copying modes.

Copying methods are all asynchronous calls. They can be cancelled by deleting the MVPbkContactOperationBase object returned by copying methods.

The copying operation is observed by MVPbkBatchOperationObserver. MVPbkBatchOperationObserver::StepComplete() is called when one step of the operation is complete. MVPbkBatchOperationObserver::StepFailed() is called when one step of the operation fails. MVPbkBatchOperationObserver::OperationComplete() is called when all operations are completed.

The following code snippet demonstrates how to copy contacts by using CVPbkContactManager::CopyContactsL(). Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

 //
Client application class implements MVPbkBatchOperationObserver // CVPbkContactManager
and MVPbkContactStore have been initialized  // as section "Opening contact
stores" // Define three class member: //     CVPbkContactLinkArray* iContactCopySource;
//     MVPbkContactStore* iTargetStore; //     MVPbkContactOperationBase*
iOp;  // Constants for the contacts database URI // _LIT( KSimDbUri, "sim://global_onb"
);  // Create the CVPbkContactLinkArray instance which holds the  // contact
link for copying // iContactCopySource = CVPbkContactLinkArray::NewL();  //
Create the instance of MVPbkContactLink implementation, such as creating //
MVPbkContactLink from MVPbkViewContact. // Assumption: MVPbkContactViewBase*
iView has been created and the view is not empty //             The view is
a contact view. // MVPbkContactLink* link = iView->ContactAtL( 0 )->CreateLinkLC();
 // Add the link to link array // iContactCopySource->AppendL( link ); CleanupStack::Pop();
// link  // Add other contact link to link array // ...  // Use SIM contact
store as target store // iTargetStore = iStores->Find( TVPbkContactStoreUriPtr(
KSimDbUri ) );  // Create the copy operation // iOp = iContactManager->CopyContactsL(
*iContactCopySource, iTargetStore, *this );  // In the callback MVPbkBatchOperationObserver::OperationComplete
// ( MVPbkContactOperationBase& aOperation ), do cleaning up. // if( iOp
= &aOperation ) {     delete iOp;     iOp = NULL; } delete iContactCopySource;
iContactCopySource = NULL; delete iTargetStore; iTargetStore = NULL;  // In
the callback MVPbkBatchOperationObserver::StepFailed(  // MVPbkContactOperationBase&
aOperation, TInt aStepSize, TInt aError),  // get the reason of operation
failure.  

The following code snippet demonstrates how to copy contacts by using CVPbkContactCopier. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

 //
Client application class implements MVPbkBatchOperationObserver // CVPbkContactManager
and MVPbkContactStore have been initialized  // as section "Opening contact
stores" // Define five class member: //     CVPbkContactLinkArray* iContactCopySource;
//     MVPbkContactStore* iTargetStore; //     CVPbkContactCopier* iContactCopier;
//     CVPbkContactLinkArray* iCopiedContactLinks, //     MVPbkContactOperationBase*
iOp;  // Constants for the contacts database URI // _LIT( KSimDbUri, "sim://global_onb"
);  // Assumption: CVPbkContactLinkArray* iContactCopySource has been instantiated
 //             as the code snippet above.  // Use SIM contact store as target
store // iTargetStore = iStores->Find( TVPbkContactStoreUriPtr( KSimDbUri
) );  // Instantiate CVPbkContactCopier // iContactCopier = CVPbkContactCopier::NewL();
 // Instantiate the CVPbkContactLinkArray that will hold the results of  //
the copy operation // if( iCopiedContactLinks ) {     delete iCopiedContactLinks;
    iCopiedContactLinks = NULL; } iCopiedContactLinks = CVPbkContactLinkArray::NewL();
 // Create copy operation // Copy operation uses a store specific copy policy
if found for  // the target store. // iOp = iContactCopier->CopyContactsL(
EVPbkUseStoreSpecificCopyPolicy,      *iContactCopySource, iTargetStore, 
    *iCopiedContactLinks, *this );  // In the callback MVPbkBatchOperationObserver::OperationComplete
// ( MVPbkContactOperationBase& aOperation ), do cleaning up. // if( iOp
= &aOperation ) {     delete iOp;     iOp = NULL; } delete iContactCopySource;
iContactCopySource = NULL; delete iContactCopier; iContactCopier = NULL; delete
iTargetStore; iTargetStore = NULL;  // In the callback MVPbkBatchOperationObserver::StepFailed(
 // MVPbkContactOperationBase& aOperation, TInt aStepSize, TInt aError),
 // get the reason of operation failure.  

If the target store parameter for copying method is NULL, contacts are copied to the store where they already are i.e. the contacts are duplicated

Related APIs
  • CVPbkContactCopier
  • CVPbkContactManager::CopyContactsL()
  • EVPbkSimpleContactCopy
  • EVPbkUsePlatformSpecificDuplicatePolicy
  • EVPbkUseStoreSpecificCopyPolicy
  • MVPbkBatchOperationObserver
  • MVPbkBatchOperationObserver::OperationComplete()
  • MVPbkBatchOperationObserver::StepComplete()
  • MVPbkBatchOperationObserver::StepFailed()
  • MVPbkContactOperationBase

Deleting contacts

The CVPbkContactManager::DeleteContactsL() method supports deleting a collection of contacts. It is an asynchronous call and can be cancelled by deleting the MVPbkContactOperationBase object returned by deleting methods.

The deleting operation is observed by MVPbkBatchOperationObserver. MVPbkBatchOperationObserver::StepComplete() is called when one step of the operation is complete. MVPbkBatchOperationObserver::StepFailed() is called when one step of the operation fails. MVPbkBatchOperationObserver::OperationComplete() is called when all operations are completed.

The following code snippet demonstrates how to delete contacts by using CVPbkContactManager::DeleteContactsL(). Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application VPbkContManagerEx.

 //
Client application class implements MVPbkBatchOperationObserver // CVPbkContactManager
and MVPbkContactStore have been initialized  // as section "Opening contact
stores" // Define two class member: //     CVPbkContactLinkArray* iContactToDelete;
//     MVPbkContactOperationBase* iOp;  // Create the CVPbkContactLinkArray
instance which holds the  // contact link to delete // iContactToDelete =
CVPbkContactLinkArray::NewL();  // Create the instance of MVPbkContactLink
implementation, such as creating // MVPbkContactLink from MVPbkViewContact.
// Assumption: MVPbkContactViewBase* iView has been created and the view is
not empty //             The view is a contact view.. // MVPbkContactLink*
link = iView->ContactAtL( 0 )->CreateLinkLC();  // Add the link to link array
// iContactToDelete->AppendL( link ); CleanupStack::Pop(); // link  // Add
other contact link to link array // ...  // Create the delete operation //
iOp = iContactManager->DeleteContactsL( *iContactCopySource, *this );  //
In the callback MVPbkBatchOperationObserver::OperationComplete // ( MVPbkContactOperationBase&
aOperation ), do cleaning up. // if( iOp = &aOperation ) {     delete
iOp;     iOp = NULL; } delete iContactToDelete; iContactToDelete = NULL; 
// In the callback MVPbkBatchOperationObserver::StepFailed(  // MVPbkContactOperationBase&
aOperation, TInt aStepSize, TInt aError),  // get the reason of operation
failure.  

Related APIs
  • CVPbkContactManager::DeleteContactsL()
  • MVPbkBatchOperationObserver
  • MVPbkBatchOperationObserver::OperationComplete()
  • MVPbkBatchOperationObserver::StepComplete()
  • MVPbkBatchOperationObserver::StepFailed()
  • MVPbkContactOperationBase

Filtering contacts

CVPbkFieldTypeSelector is a field type selector. It is usually used in filtering contact data or creating filtered contact views. Please refer to Virtual Phonebook View Definition API Specification and example application VPbkViewDefEx for details on how to create filtering contact views by using the filter.

The following code snippets demonstrate how to filter contact data by using CVPbkFieldTypeSelector and CVPbkFieldFilter. CVPbkFieldFilter is a filtered and sorted collection of Virtual Phonebook contact fields.

Define the resource for creating the contact field type selector:

//filter,
all result contact must have telephone number field RESOURCE VPBK_FIELD_TYPE_SELECTOR
r_vpbk_phone_number_selector     {     versitProperties =          {     
   VBK_FIELD_VERSIT_PROPERTY             {             name = EVPbkVersitNameTEL;
            }         };     } 

Reading the resource and instantiating the CVPbkFieldTypeSelector:

 //
Resource file path // Assumption: the definitions shown above are found from
VPbkEngineEx.rss // _LIT( KResFile, "z:\\resource\\apps\\VPbkEngineEx.rsc"
);   // Read the VPBK_FIELD_TYPE_SELECTOR from resource file // RResourceFile
resFile; CleanupClosePushL(resFile); resFile.OpenL(iRFs, KResFile); TResourceReader
reader; HBufC8* buffer = resFile.AllocReadLC( R_VPBK_PHONE_NUMBER_SELECTOR
); reader.SetBuffer(buffer);  // Instantiate CVPbkFieldTypeSelector // CVPbkFieldTypeSelector*
fieldTypeSelector = CVPbkFieldTypeSelector::NewL(     reader, iContactManager->FieldTypes()
);  // Clean up temporary variable // CleanupStack::PopAndDestroy( buffer
); CleanupStack::PopAndDestroy( &resFile );  

After instantiating the CVPbkFieldTypeSelector, it can be used by CVPbkFieldFilter to filter the MVPbkStoreContactFieldCollection.

 //
Assumption: MVPbkStoreContact* contact holds the one contact data // MVPbkStoreContact*
contact = ... CVPbkFieldFilter::TConfig config(contact->Fields(), fieldTypeSelector,
NULL); CVPbkFieldFilter* fieldFilter = CVPbkFieldFilter::NewL( config ); 
// Through fieldFilter->FieldAt(TInt aIndex), client can get the field  //
that matches the filter.  

The third parameter of CVPbkFieldFilter::TConfig constructor is a point to MVPbkContactFieldOrdering. It is an interface for field ordering. Client should implement this interface if wants the contact fields in customized order.

Related APIs
  • CVPbkFieldFilter
  • CVPbkFieldFilter::TConfig
  • CVPbkFieldTypeSelector
  • MVPbkContactFieldOrdering
  • MVPbkStoreContactFieldCollection

Managing top contacts

Managing xsp IDs

Error handling

All methods leave in case of an error situation. Normal error handling practices should be used, e.g. using cleanup stack and TRAP harness.

Related APIs
  • TRAP

Extensions to the API

Virtual Phonebook Engine API provides 3 extensions: MVPbkContactStore2 is an extension for MVPbkContactStore, MVPbkStoreContact2 is an extension for MVPbkStoreContact, MVPbkContactStoreProperties2 is an extension for MVPbkContactStoreProperties. MVPbkContactStore2 extensions can be accessed through extension method MVPbkContactStore::ContactStoreExtension():

 
MVPbkContactStore2* contactStoreExtension = reinterpret_cast<MVPbkContactStore2*>
    ( iContactStore.ContactStoreExtension( KMVPbkContactStoreExtension2Uid )
); 

MVPbkStoreContact2 and MVPbkContactStoreProperties2 are accessed in a similar way, see extension method and extension UIDs documentation in headers MVPbkStoreContact.h and MVPbkContactStoreProperties.h.

Related APIs
  • MVPbkContactStore
  • MVPbkContactStore2
  • MVPbkContactStore::ContactStoreExtension()
  • MVPbkContactStoreProperties
  • MVPbkContactStoreProperties.h
  • MVPbkContactStoreProperties2
  • MVPbkStoreContact
  • MVPbkStoreContact.h
  • MVPbkStoreContact2
Related APIs
  • CVPbkContactManager

Glossary

Abbreviations

None.

Definitions

None.

References