Virtual Phonebook Engine API Specification Document
Changes in Virtual Phonebook Engine documentation
| Version |
Date |
Status |
Description |
|
1.0
|
15.01.2007
|
Approved
|
|
Changes in Virtual Phonebook Engine API
| Version |
Description |
|
1.0
|
First
version.
|
|
|
|
PurposeThe 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 descriptionVirtual 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 casesThe 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 structureThe main class of Virtual Phonebook Engine
API are shown in
Figure 1. The
class
CVPbkContactManager is derived from CBase.
Related APIs
Related APIs
Using Virtual Phonebook Engine APIThe
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 storesThe 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
MVPbkContactStoreMVPbkContactStoreListVPbkContManagerEx
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
CVPbkContactViewDefinitionVPbkViewDefEx
Managing contact attributesVirtual 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 attributesClient 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
Editing the attributesUsers 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; //Perform the required steps 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
MVPbkSetAttributeObserverMVPbkSetAttributeObserver::AttributeOperationComplete()MVPbkSetAttributeObserver::AttributeOperationFailed()VPbkAttrManagerEx
Finding all contacts by the specified attribute conditionIn
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
MVPbkContactFindObserverMVPbkContactFindObserver::FindCompleteL()MVPbkContactFindObserver::FindFailed()VPbkAttrManagerEx
Related APIs
MVPbkContactAttributeManager
Finding contactsVirtual 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( ¶m ); //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()CVPbkPhoneNumberMatchStrategyFindFromStoreFailedFindFromStoreSucceedFindLMVPbkContactFindFromStoresObserverMVPbkContactFindFromStoresObserver::FindFromStoreFailedMVPbkContactFindFromStoresObserver::FindFromStoreSucceededLMVPbkContactFindFromStoresObserver::FindFromStoresOperationCompleteMVPbkContactFindObserverMVPbkContactFindObserver::FindCompleteL()MVPbkContactOperationBaseVPbkContManagerEx
Creating contact field type listA 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
CVPbkFieldTypeRefsListCVPbkSortOrderVPbkContManagerExVPbkViewDefEx
Manipulating contact dataVirtual 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()MVPbkContactOperationBaseMVPbkStoreContact::CommitLVPbkContManagerEx
Retrieving contact dataThe
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()MVPbkContactLinkMVPbkContactOperationBaseVPbkContManagerEx
Copying contactsThere 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
CVPbkContactCopierCVPbkContactManager::CopyContactsL()EVPbkSimpleContactCopyEVPbkUsePlatformSpecificDuplicatePolicyEVPbkUseStoreSpecificCopyPolicyMVPbkBatchOperationObserverMVPbkBatchOperationObserver::OperationComplete()MVPbkBatchOperationObserver::StepComplete()MVPbkBatchOperationObserver::StepFailed()MVPbkContactOperationBase
Deleting contactsThe
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()MVPbkBatchOperationObserverMVPbkBatchOperationObserver::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
CVPbkFieldFilterCVPbkFieldFilter::TConfigCVPbkFieldTypeSelectorMVPbkContactFieldOrderingMVPbkStoreContactFieldCollection
Error handlingAll methods leave in case
of an error situation. Normal Symbian error handling practices should be used,
e.g. using cleanup stack and
TRAP harness.
Related APIs
Extensions to the APIVirtual 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
MVPbkContactStoreMVPbkContactStore2MVPbkContactStore::ContactStoreExtension()MVPbkContactStorePropertiesMVPbkContactStoreProperties.hMVPbkContactStoreProperties2MVPbkStoreContactMVPbkStoreContact.hMVPbkStoreContact2
Related APIs
References
|
/1/ Virtual Phonebook
View Definition API Specification Document
|
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|