Virtual
Phonebook Migration Support API Specification Document
Changes
in Virtual Phonebook Migration Support documentation
Changes
in Virtual Phonebook Migration Support
Purpose
The purpose of Virtual Phonebook
Migration Support API is to provide utility services for converting between
Contacts Model contact IDs and Virtual Phonebook contact links.
API description
Virtual Phonebook Migration
Support API can be categorized as a plug-in API with a normal method call
interface. The concrete services of this API are provided by a plug-in implementation.
From API user's point of view, this only means that sometimes creating the
API class might fail.
This API is meant for applications that need to
migrate code using the Contacts Model into code that uses Virtual Phonebook
Engine.
Use cases
The
most common use cases of Migration Support API are the following:
-
Converting
between Contacts Model contact ID and Virtual Phonebook contact link
-
Getting
a Phonebook Engine field index for a Virtual Phonebook field
-
Converting
a given Virtual Phonebook link into a new Phonebook contact item
API class structure
The classes of Virtual
Phonebook Migration Support API are shown in
Figure
1.
The
class
CVPbkContactIdConverter is derived from CBase and
defines an ECOM plug-in interface.
Related APIs
CBaseCVPbkContactIdConverter
Using
Virtual Phonebook Migration Support API
As this API is only
used for migrating code using Contacts Model APIs, the constructor
CVPbkContactIdConverter*
NewL(MVPbkContactStore& aContactStore) only accepts a contact
store from the cntdb domain as its parameter.
Converting
between Contacts Model contact ID and Virtual Phonebook contact link
The
following code snippet demonstrates how to convert between Contacts Model
contact ID and Virtual Phonebook contact link.
//
Initialize virtual phonebook Contact Manager // CVPbkContactManager* contactManager
= ... // Get and open the contact store from cntdb domain // MVPbkContactStore*
contactStore = ... // Instantiate CVPbkContactIdConverter // The object creation
fails if the plug-in is not available // CVPbkContactIdConverter* idConverter
= CVPbkContactIdConverter::NewL( contactStore ); CleanupStack::PushL( idConverter
); // Convert Virtual Phonebook contact link to Contacts Model id // MVPbkContactLink*
link = ... TInt32 idFromLink = idConverter.LinkToIdentifier( *link ); delete
link; link = NULL; // Use the id // ... // Convert Contacts Model ID to
Virtual Phonebook contact link // TInt32 id = ... MVPbkContactLink* linkFromId
= idConverter.IdentifierToLinkLC( id ); ... // Use the link ... // Clean
up // CleanupStack::PopAndDestroy( linkFromId ); CleanupStack::PopAndDestroy(
idConverter ); CleanupStack::PopAndDestroy( contactStore ); CleanupStack::PopAndDestroy(
contactManager );
Getting
a Phonebook Engine field index for a Virtual Phonebook field
The
following code snippet demonstrates how to get a Phonebook Engine field index
for a Virtual Phonebook field
// Initialize virtual
phonebook Contact Manager // CVPbkContactManager* contactManager = ... //
Get and open the contact store from cntdb domain // MVPbkContactStore* contactStore
= ... // Instantiate CVPbkContactIdConverter // The object creation fails
if the plug-in is not available // CVPbkContactIdConverter* idConverter =
CVPbkContactIdConverter::NewL( contactStore ); CleanupStack::PushL( idConverter
); // Get the field and convert it into an index // MVPbkStoreContactField*
field = ... TInt fieldIndex = idConverter->PbkEngFieldIndexL( *field ); //
Use the field index // ... // Clean up // CleanupStack::PopAndDestroy( field
); CleanupStack::PopAndDestroy( idConverter ); CleanupStack::PopAndDestroy(
contactStore ); CleanupStack::PopAndDestroy( contactManager );
Converting a given Virtual Phonebook link into a new
Phonebook contact item
The following code snippet demonstrates
how to convert a given link into a new Phonebook contact item and commit the
contact item after modifications.
// Initialize
virtual phonebook Contact Manager // CVPbkContactManager* contactManager =
... // Get and open the contact store from cntdb domain // MVPbkContactStore*
contactStore = ... // Instantiate CVPbkContactIdConverter // The object creation
fails if the plug-in is not available // CVPbkContactIdConverter* idConverter
= CVPbkContactIdConverter::NewL( contactStore ); CleanupStack::PushL( idConverter
); // Virtual Phonebook contact link // MVPbkContactLink* link = ... //
Converting the link to Phonebook contact item // If want to open and lock
the contact item, use the method below // CPbkContactItem* contactItem = idConverter->LinkToOpenPbkContactItemLCX(
link ); // Otherwise, open the contact item as follows // CPbkContactItem*
contactItem = idConverter->LinkToPbkContactItemLC( link ); // Modify the
contact item and commit it // contactItem = ... idConverter->CommitOpenContactItemL(
*contactItem ); // If use LinkToOpenPbkContactItemLCX, clean up as the following
// CleanupStack::PopAndDestroy( 2 ); // contactItem, lock CleanupStack::PopAndDestroy(
link ); CleanupStack::PopAndDestroy( idConverter ); CleanupStack::PopAndDestroy(
contactStore ); CleanupStack::PopAndDestroy( contactManager ); // If use
LinkToOpenPbkContactItemLC, clean up as the following // CleanupStack::PopAndDestroy(
contactItem ); CleanupStack::PopAndDestroy( link ); CleanupStack::PopAndDestroy(
idConverter ); CleanupStack::PopAndDestroy( contactStore ); CleanupStack::PopAndDestroy(
contactManager );
Error
handling
Some methods leave in case of an error situation.
Normal error handling practises should be used, e.g. using cleanup stack and
trap harness.
Extensions to
the API
Virtual Phonebook Migration Support API is an ECOM
plug-in interface class, but it only provides a constructor instantiating
the default implementation so it does not explicitly support any kinds of
extensions.