How to Add Email Type Values

Purpose and Scope

This document describes how to use the contact model for adding an Email field to a contact item using the Contacts API. The Email field can be further described through the use of field types. This document shows how to add the field types representing CELL, HOME and WORK. It also describes the role of the INTERNET type in the Email field.

Overview

The cntmodel provides the data engine for creating contact items that can contain fields. New fields can be added which can have fieldtypes and a mapping. The contact items can be import vCards and also export vCards. The cntvcard library provides the functionality to import and export vCards. The contact item mapping is associated with the properties of a vCard. The field type is typically associated with the type parameters of the property.

How to add an Email field with a CELL type

The following code snippet describes how to add a contact item with an email field and a CELL field type. The corresponding EMAIL property, if the contact item is exported, is also shown.

Add contact item

// Adds a contact item to the contact database. The important lines are in bold.

LOCAL_C void AddEntryL()
    {
    _LIT(KForename,"John"); 
    _LIT(KSurname,"Smith"); 
    _LIT(KPhoneNumber,"+441617779700"); 
    _LIT(KEmailAddress,"john.smith@symbian.com"); 
    
    // Create a  contact card to contain the data
    CContactCard* newCard = CContactCard::NewLC();
    
    // Create the firstName field and add the data to it
    CContactItemField* firstName = CContactItemField::NewLC(KStorageTypeText, KUidContactFieldGivenName);
    firstName->TextStorage()->SetTextL(KForename);
    newCard->AddFieldL(*firstName);
      CleanupStack::Pop(firstName);
      
    // Create the lastName field and add the data to it
     CContactItemField* lastName= CContactItemField::NewLC(KStorageTypeText, KUidContactFieldFamilyName);
      lastName ->TextStorage()->SetTextL(KSurname);
      newCard->AddFieldL(*lastName);
      CleanupStack::Pop(lastName);
      
    // Create the emailAddress field and add the data to it
    +++CContactItemField* emailAddr = CContactItemField::NewLC(KStorageTypeText, KUidContactFieldEMail);
    +++emailAddr-> AddFieldTypeL(KUidContactFieldVCardMapCELL);
    +++emailAddr->SetMapping(KUidContactFieldVCardMapEMAILINTERNET);
      emailAddr ->TextStorage()->SetTextL(KEmailAddress);
      newCard->AddFieldL(*emailAddr);
      CleanupStack::Pop(emailAddr);
        
    // Create the phoneNo field and add the data to it
      CContactItemField* phoneNumber = CContactItemField::NewLC(KStorageTypeText, KUidContactFieldPhoneNumber);
    phoneNumber->SetMapping(KUidContactFieldVCardMapTEL);
    phoneNumber ->TextStorage()->SetTextL(KPhoneNumber);
    newCard->AddFieldL(*phoneNumber);
      CleanupStack::Pop(phoneNumber);
    
    // Add newCard to the database
    const TContactItemId contactId = db->AddNewContactL(*newCard);
      CleanupStack::PopAndDestroy(newCard);
    }

Exported EMAIL property

EMAIL;CELL;ENCODING=QUOTED-PRINTABLE:john.smith=40symbian.com

Add a contact item with an email field and HOME type

The following code snippet describes how to add an email field and a HOME field type. The corresponding EMAIL property, if the contact item is exported, is also shown.

Creating an email field

// Create the emailAddress field and add the data to it
    CContactItemField* emailAddr = CContactItemField::NewLC(KStorageTypeText, KUidContactFieldEMail);
    emailAddr-> AddFieldTypeL(KUidContactFieldVCardMapHOME);
    emailAddr->SetMapping(KUidContactFieldVCardMapEMAILINTERNET);
    emailAddr ->TextStorage()->SetTextL(KEmailAddress);
    newCard->AddFieldL(*emailAddr);
    CleanupStack::Pop(emailAddr);

Exported EMAIL property

EMAIL;HOME;ENCODING=QUOTED-PRINTABLE:john.smith=40symbian.com

Add a contact item with an email field and WORK type

The following code snippet describes how to add an email field and a WORK field type. The corresponding EMAIL property, if the contact item is exported, is also shown.

Creating an email field

 // Create the emailAddress field and add the data to it
    CContactItemField* emailAddr = CContactItemField::NewLC(KStorageTypeText, KUidContactFieldEMail);
    emailAddr-> AddFieldTypeL(KUidContactFieldVCardMapWORK);
    emailAddr->SetMapping(KUidContactFieldVCardMapEMAILINTERNET);
    emailAddr ->TextStorage()->SetTextL(KEmailAddress);
    newCard->AddFieldL(*emailAddr);
    CleanupStack::Pop(emailAddr);

Exported EMAIL property

EMAIL;WORK;ENCODING=QUOTED-PRINTABLE:john.smith=40symbian.com

Add a contact item with an email field and INTERNET type

The following code snippet describes how to add an email field and an INTERNET field type. The corresponding EMAIL property, if the contact item is exported, is also shown. There are two ways of creating an email field with an internet type.

Creating an email field

The first one is:
// Create the emailAddress field and add the data to it
    CContactItemField* emailAddr = CContactItemField::NewLC(KStorageTypeText, KUidContactFieldEMail);
    // Do not add another fieldtype!
    emailAddr->SetMapping(KUidContactFieldVCardMapEMAILINTERNET);
    emailAddr ->TextStorage()->SetTextL(KEmailAddress);
    newCard->AddFieldL(*emailAddr);
    CleanupStack::Pop(emailAddr);
This would have the effect of adding an INTERNET field type by default. 

The second method is to explicitly add:
// Create the emailAddress field and add the data to it
    CContactItemField* emailAddr = CContactItemField::NewLC(KStorageTypeText, KUidContactFieldEMail);
    emailAddr-> AddFieldTypeL(KUidContactFieldVCardMapINTERNET);
    emailAddr->SetMapping(KUidContactFieldVCardMapEMAILINTERNET);
    emailAddr ->TextStorage()->SetTextL(KEmailAddress);
    newCard->AddFieldL(*emailAddr);
    CleanupStack::Pop(emailAddr);

Exported EMAIL property

EMAIL;INTERNET;ENCODING=QUOTED-PRINTABLE:john.smith=40symbian.com