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.

Class diagram of Virtual Phonebook Migra...


Class diagram of Virtual Phonebook Migration Support API

The class CVPbkContactIdConverter is derived from CBase and defines an ECOM plug-in interface.

Related APIs
  • CBase
  • CVPbkContactIdConverter

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.

Glossary

Abbreviations

None.

Definitions

None.

References

None.