Purpose

The purpose of Virtual Phonebook vCard API is to provide vCard import and export functions for Virtual Phonebook Engine. This API also provides functions for ensuring the validity of a contact against the vCard 2.1 standard.

API description

Virtual Phonebook vCard API can be categorized as a library API. It offers vCard import and export, Compact Business Card import and vCard field type checking functions.

The type of this API is a normal method call interface. This API needs a reference to CVPbkContactManager in order to provide the services. All import and export functions need the context of Active Object Framework, i.e. the thread using this API must have an instance of the CActiveScheduler

This API is meant for applications that need to import or export contacts in vCard or Compact Business Card format.

Use cases

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

  • Importing a contact in vCard format

  • Importing a contact in Compact Business Card format

  • Exporting a contact in vCard format

  • Checking whether a field type is supported by the vCard format

API class structure

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

Class diagram of Virtual Phonebook vCard...


Class diagram of Virtual Phonebook vCard API

The class CVPbkVCardEng is derived from CBase.

Related APIs
  • CBase
  • CVPbkVCardEng
Related APIs
  • CActiveScheduler
  • CVPbkContactManager

Using Virtual Phonebook vCard API

Virtual Phonebook vCard API needs a reference to CVPbkContactManager, so an instance of CVPbkContactManager must be constructed before using this API.

The sequence diagram in Figure 2 and code snippet demonstrate how to instantiate CVPbkContactManager and CVPbkVCardEng.

Sequence diagram of instantiating Virtua...


Sequence diagram of instantiating Virtual Phonebook Engine

 //
Client application class defines three class members: //     CVPbkContactManager*
iContactManager; //     CVPbkVCardEng* iVCardEngine; //     RFs iRfs;  //
Define a constant for the contacts database URI // _LIT( KCntDbUri, "cntdb://c:contacts.cdb"
);  // Create an URI list // CVPbkContactStoreUriArray* uriList = CVPbkContactStoreUriArray::NewLC();
uriList->AppendL( TVPbkContactStoreUriPtr( KCntDbUri ) );  // 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 );  // Instantiate CVPbkVCardEng // CVPbkVCardEng* iVCardEngine
= CVPbkVCardEng::NewL( *iContactManager );  // Clean up temporary variables
// CleanupStack::PopAndDestroy( uriList );  

As import and export functions need to read contact from or write contact to a contact store, the following sequence diagram Figure 3 and code snippet demonstrate how to open a contact store.

Sequence diagram of opening contact stor...


Sequence diagram of opening contact store

 // Client application class implements MVPbkContactStoreObserver
// Define one class member: //     MVPbkContactStore* iContactStore;  // Get
the contact store // MVPbkContactStoreList& stores = iContactManager->ContactStoresL();
MVPbkContactStore* iContactStore = &stores.At( 0 );  // Open the contact
store asynchronously // The operation status is reported via MVPbkContactStoreObserver.
// contactStore->ReplaceL( *this );  

Importing contact in vCard format

There are two methods that can import a contact in vCard format. The difference between these methods is that one commits the imported vCard contact object into target store while the other returns the imported contact to the client and the client should handle committing the contact.

These two methods are all asynchronous calls and can be cancelled by deleting the MVPbkContactOperationBase that is returned by the import method.

The following sequence diagram Figure 4 illustrates the general process of importing contact.

Sequence diagram of importing
contact


Sequence diagram of importing contact

The usage of the method that automatically commits is shown below. This method uses MVPbkContactCopyObserver to observe the completion of contact import. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application about vCards.

 // Client application class implements
MVPbkContactCopyObserver // Define two class members: //     MVPbkContactOperationBase*
iOp; //     RFileReadStream iSource;  // vCard file name // _LIT( KVCardFileName,
"c:\\somedir\\imported.vcf" );  // Open a RFileReadStream that holds the vCard
content // User::LeaveIfError( iSource.Open( iRfs, KVCardFileName, EFileRead
) );  // Import the contact from RFileReadStream asynchronously // The operation
status is reported via MVPbkContactCopyObserver. // iOp = vCardEngine->ImportVCardL(
*iContactStore, iSource, *this );  // In the callback MVPbkContactCopyObserver::ContactsSaved(
MVPbkContactOperationBase& aOperation, MVPbkContactLinkArray* aResults),
 // get the links to the created contacts from the parameter aResults of callback
// and do cleaning up. // delete iOp; iSource.Close();  // In the callback
MVPbkContactCopyObserver::ContactsSavingFailed, do cleaning up.  

The usage of the method that returns the imported contact to the client is as shown below. This method uses MVPbkSingleContactOperationObserver to observe the completion of contact import. Since it returns the imported contact to the client, the parameter aResults is always NULL in the callback MVPbkSingleContactOperationObserver::VPbkSingleContactOperationComplete(MVPbkContactOperationBase& aOperation,MVPbkStoreContact* aResults). Please note that these code clips only highlight the steps needed in the operation. For a more detailed example, see the example application about vCards.

 //
Client application class implements MVPbkSingleContactOperationObserver //
Define three class members: //     MVPbkContactOperationBase* iOp; //    
RFileReadStream iSource; //     RPointerArray< MVPbkStoreContact > iImportedContacts;
 // vCard file name // _LIT( KVCardFileName, "c:\\somedir\\imported.vcf" );
 // Open the RFileReadStream that holds the vCard content // User::LeaveIfError(
iSource.Open( iRfs, KVCardFileName, EFileRead ) );  // Import the contact
from RFileReadStream asynchronously // The operation status is reported via
MVPbkSingleContactOperationObserver. // MVPbkContactOperationBase* iOp = 
    vCardEngine->ImportVCardL( iImportedContacts, *contactStore, iSource,
*this );   // In the callback MVPbkSingleContactOperationObserver::VPbkSingleContactOperationComplete
and MVPbkSingleContactOperationObserver::VPbkSingleContactOperationFailed,
do cleaning up. // delete iOp; iSource.Close();  // Manipulate and commit
the imported contacts // iImportedContacts...  // Close iImportedContacts
// iImportedContacts.ResetAndDestroy(); iImportedContacts.Close();  

Related APIs
  • MVPbkContactCopyObserver
  • MVPbkContactOperationBase
  • MVPbkSingleContactOperationObserver
  • aResults

Importing contact in Compact Business Card format

There are two methods that can import contact in Compact Business Card format. The difference between these methods is same as the difference between the methods of importing contact in vCard format. One method commits the imported Compact Business Card contact object to target store while the other returns the imported contact to client and client handles committing the contact.

These two methods are all asynchronous calls and can be cancelled by deleting the MVPbkContactOperationBase that returned by the import method.

The usage of importing contact in Compact Business Card format is similar as importing contact in vCard format. Please note that those code clips only highlight the steps needed in the operation. For more detailed example, see the example application about vCards.

Related APIs
  • MVPbkContactOperationBase

Exporting contact in vCard format

There are two methods that can export contact in vCard format. One method exports the contact from MVPbkStoreContact while the other exports the contact from MVPbkContactLink.

These two methods are both asynchronous calls and use MVPbkSingleContactOperationObserver to observe the completion of the export operation. Both operations can be cancelled by deleting MVPbkContactOperationBase that is returned by the export method.

The following sequence diagram Figure 5 illustrates the general process of exporting contact.

Sequence diagram of exporting
contact


Sequence diagram of exporting contact

The following code snippet demonstrates how to export a contact in vCard format. Please note that these code clips only highlight the steps needed in the operation. For more detailed example, see the example application about vCards.

 //
Client application class implements MVPbkSingleContactOperationObserver //
Define five class members: //     MVPbkContactOperationBase* iOp; //     RDesWriteStream
iDestStream; //     HBufC8* iBuffer; //     MVPbkStoreContact* iSourceItem;
//     MVPbkContactLink* iContactLink;  // Create the buffer to store the
contact // iBuffer = HBufC8::NewL( 1024 ); TPtr8 bufferPtr( buffer->Des()
); iDestStream.Open( bufferPtr );  // Use MVPbkSingleContactOperationObserver
to observe the export // Export the contact from MVPbkStoreContact //  iSourceItem
= ... iOp = vCardEngine->ExportVCardL( iDestStream, *iSourceItem, *this );
 // Or export the contact from MVPbkContactLink //  iContactLink = ... iOp
= vCardEngine->ExportVCardL( iDestStream, *iContactLink, *this );  // In the
callback method MVPbkSingleContactOperationObserver::VPbkSingleContactOperationComplete,
 // commit the RDesWriteStream and do cleaning up. // iDestStream.CommitL();
delete iOp; if( iDestStream )     {     iDestStream.Close();     } delete
iBuffer; delete iSourceItem; delete iContactLink;  // In the callback method
MVPbkSingleContactOperationObserver::VPbkSingleContactOperationFailed,  //
do cleaning up.  

Related APIs
  • MVPbkContactLink
  • MVPbkContactOperationBase
  • MVPbkSingleContactOperationObserver
  • MVPbkStoreContact

Checking the field type supported by vCard engine

This API provides functions for returning all field types supported by vCard format and to check whether a specific field type is supported.

The following code snippet demonstrates how to check whether a given field type is supported by vCard format.

 // Define the field type mapping in resource
file vCardUtil.rss, such as // RESOURCE VPBK_FIELD_TYPE_MAPPING r_fname_type
//    { //    versitProperty = VBK_FIELD_VERSIT_PROPERTY //        { //  
     name = EVPbkVersitNameN; //        subField = EVPbkVersitSubFieldGivenName;
//        }; //    }  //  Resource file name LIT( KResFile, "c:\\somedir\\vCardUtil.rsc"
);  // 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 ); MVPbkFieldType*
fieldType = typeMapping.FindMatch( iContactManager->FieldTypes() );  // Clean
up // CleanupStack::PopAndDestroy( buffer ); CleanupStack::PopAndDestroy(
&resFile );  // Check whether the field type supported or not by vCard
engine // TBool supported = iVCardEngine->SupportsFieldType( *fieldType );
 

Error handling

Import and export 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 vCard API is an engine class and does not explicitly support any kinds of extensions to it.

Related APIs
  • CVPbkContactManager
  • CVPbkVCardEng

Glossary

Abbreviations

None.

Definitions

Compact Business Card

Compact Business Card is a business card containing typical contact information that can be transmitted over the air using compact business card format.

References