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.
The
class
CVPbkVCardEng is derived from CBase.
Related APIs
Related APIs
CActiveSchedulerCVPbkContactManager
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.
//
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.
// 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.
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
MVPbkContactCopyObserverMVPbkContactOperationBaseMVPbkSingleContactOperationObserveraResults
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.
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
MVPbkContactLinkMVPbkContactOperationBaseMVPbkSingleContactOperationObserverMVPbkStoreContact
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
CVPbkContactManagerCVPbkVCardEng