Symbian OS應用開發學習筆記之通訊錄（電話薄Contacts）

 

Symbian OS通訊錄模型

Symbian OS手機的通訊錄采用文件方式存儲，用symbian自己的說法就是通訊錄數據庫。每個Symbian OS手機都有一個默認的通訊錄數據庫，這個通訊錄數據庫在2nd和3rd兩個版本手機中的位置是不同的，前者是c：\ system\data\Contacts.cdb，后者是c：\private\100012a5\DBS_100065FF_Contacts.cdb。不管怎么說兩者都在內部閃存中，也就是跟優盤差不多的介質，由于symbian OS的文件系統暫時還沒有仔細拜讀過，所以具體差別暫不知，總之掉電不會失去就是了。

Symbian OS的手機通訊錄在開發上的操作依靠Symbian OS通訊錄模型（Contacts Model）來實現。通訊錄模型由通訊錄數據庫、通訊錄條目（項）和通信錄域三者組成，他們之間的關系是：一個手機除了系統自帶的默認通訊錄數據庫外還可以帶多個通訊錄數據庫；一個通訊錄數據庫有多個通訊錄條目組成，這里每個條目就是每個聯系人，具體數量限制各個手機應該不一樣；而一個通訊錄條目又有多個通訊錄域組成，好比有姓名、工作手機號碼、家庭手機號碼等等，每個項就是一個域。

在這里Symbian為了統一通訊錄格式，所以將通訊錄條目采用vCard格式MIME規范（RFC 1521）所定義的明碼文本來定義域，具體的vCard簡單介紹見附錄。

 

Symbian OS通訊錄操作API類

知道了Contacts Model的概念，Symbian OS將很多系統API操作封裝為幾個類：

CContactDatabase（數據庫類）：負責新建、打開、關閉等基本數據庫操作外，還負責數據庫更新（通訊錄條目的新建、修改、刪除需要通過CContactDatabase類的操作才能實現）、排序和查找，另外還有一些建立快速撥號之類的操作也是通過它來實現。

CContactItem（通訊錄條目類）：由唯一的一個TContactItemId（一個TInt32類型的宏定義）標識，負責具體一個通訊錄條目的創建、修改，其直接管理每一個通訊錄域

CContactItemField（域類）：每一個域就是一個真實單一的數據，該數據的類型具有存儲類型（TStorageType）和域類型（TFieldType）同時決定，具體的四種存儲類型和多種域類型定義見系統頭文件cntdef.h內的定義。

當然還有很多其它的類，比如CContactItemFieldSet（域集類）、CContactFieldStorage（與存儲基類）、CContactTextFields（文本存儲域類）、MContactDbObserver（通訊數據庫觀察類）等等，涉及面太大，具體也不能憑空說清楚，代碼中出現就知道了。

 

Symbian OS通訊錄操作實例

例1、       打開和關閉數據庫

CContactDatabase::OpenL()函數有兩個重載函數。如果該函數沒有給出一個參數，就打開默認的數據庫。另一種情況是，應用軟件設計師也可以傳遞一個有關數據庫的路徑和文件名，規定打開一個指定數據庫。

//打開默認數據庫

CContactDatabase* contactsDb = CContactDatabase::OpenL();

CleanupStack::PushL(contactsDb);

//取得當前數據庫所有通訊條目數

TInt numberOfContacts = contactsDb->CountL();

//釋放數據庫

CleanupStack::PopAndDestroy(contactsDb);

要注意的是：某個通信錄數據庫并不具有Close()函數或類似的函數，否則我們壓入清除棧時就得用CleanupClosePushL（）函數了。

 

例2、       創建數據庫

CContactDatabase::CreateL()函數與CContactDatabase::ReplaceL()函數之間的唯一差別就是：如果該數據庫已經存在，前者會以KErrAlreadyExists退出。如前所述，如果沒有定義參數，這些函數將創建一個默認的數據庫。CContactDatabase::FindContactFile()函數給出了一個描述符，如果不存在默認數據庫的話，該描述符就會返回該默認數據庫的位置。

// If one is found, replace it with a new empty default database.

// If no default database is found, create a new one.

TFileName contactDbFilePath;

CContactDatabase* newDefaultContactDb;

//是否存在默認數據庫

if(CContactDatabase::FindContactFile(contactDbFilePath))

{

 newDefaultContactDb = CContactDatabase::ReplaceL();

}

else

{

 newDefaultContactDb = CContactDatabase::CreateL();

}

CleanupStack::PushL(newDefaultContactDb);

// 添加自己功能代碼

CleanupStack::PopAndDestroy(newDefaultContactDb);

注：以上代碼負責創建一個空的默認數據庫。

 

例3、       讀取（遍歷）通訊錄條目

可以用TContactIter類（該類起到數據庫操作中類似游標的作用）來遍歷一個通信錄數據庫。這個類提供了一整套的函數，用于遍歷所有的通信錄項。所有的函數都用通信錄項ID (TContactItemId) 進行操作，該ID 用于訪問某個特定的通信錄項。

// Open the default contacts database:

CContactDatabase* contactsDb = CContactDatabase::OpenL();

CleanupStack::PushL(contactsDb);

TContactIter iter(*contactsDb);

TContactItemId cardId;

//循環遍歷

while( ( cardId = iter.NextL() ) != KNullContactId )

{

//讀取相應項，這里之所以稱其card，就是其實際相當于讀一個完整的vCard條目

CContactItem* card = contactsDb->ReadContactL(cardId);

CleanupStack::PushL(card);

 

//添加自己功能代碼

//……

contactsDb->CloseContactL(card->Id());

CleanupStack::PopAndDestroy(); // card

}

CleanupStack::PopAndDestroy(); // contactsDb

 

 

例4、       新建通訊錄條目

// 字符串聲明

_LIT(KForenameLabel,"Forename");//中文“名”

_LIT(KSurnameLabel,"Surname"); //中文“姓”

_LIT(KWorkPhoneLabel,"Work Phone");

_LIT(KForename,"Steve");

_LIT(KOtherForename,"Bob");

_LIT(KSurname,"Wilkinson");

_LIT(KWorkPhone,"+441617779700");

//以上定義的字符串，在以后例子中將直接使用，不再重新進行定義了

//打開默認數據庫

CContactDatabase* contactsDb = CContactDatabase::OpenL();

CleanupStack::PushL(contactsDb);

// 建立一個新條目

CContactItem* contact = CContactCard::NewLC();

//創建一個新的文本存儲類型的姓域

CContactItemField* field =

CContactItemField::NewLC(KStorageTypeText, KUidContactFieldFamilyName);

//將姓域建立與vCard的映射

field->SetMapping(KUidContactFieldVCardMapUnusedN);

//設置域標簽

field->SetLabelL(KSurnameLabel);

//設置域值

field->TextStorage()->SetTextL(KSurname);

//把該域加入到新建的條目中

contact->AddFieldL(*field);    

CleanupStack::Pop();

 

//添加文本存儲類型的名域

field=CContactItemField::NewLC(KStorageTypeText, KUidContactFieldGivenName);

field->SetMapping(KUidContactFieldVCardMapUnusedN);

field->SetLabelL(KForenameLabel);

field->TextStorage()->SetTextL(KForename);

contact->AddFieldL(*field); 

CleanupStack::Pop();

 

//添加文本存儲類型的手機號碼域

field=CContactItemField::NewLC(KStorageTypeText, KUidContactFieldPhoneNumber);

field->SetMapping(KUidContactFieldVCardMapTEL);

field->SetLabelL(KWorkPhoneLabel);

field->TextStorage()->SetTextL(KWorkPhone);

contact->AddFieldL(*field); 

CleanupStack::Pop();

 

//把建立的新記錄添加到數據庫中

contactsDb->AddNewContactL(*contact);

contactsDb->SetOwnCardL(*contact);

CleanupStack::PopAndDestroy(2); // contact contactsDb

 

例5、       查找并更新通訊錄條目

這個例子比較復雜，涉及的查找函數為FindAsyncL，該類函數實例有：

CContactIdArray * CContactDatabase::FindLC(const TDesC &aText, const CContactItemFieldDef *aFieldDef);

CIdleFinder * CContactDatabase::FindAsyncL(const TDesC &aText, const CContactItemFieldDef *aFieldDef, MIdleFindObserver *aObserver);

還有對應的FindInTextDefLC()和FindInTextDefAsyncL()各兩組，具體參見sdk

下面是具體代碼實例：

CContactDatabase*  iContactsDb = CContactDatabase::OpenL();

CleanupStack::PushL(iContactsDb);

CContactItemFieldDef*  iFieldDef = new (ELeave)CContactItemFieldDef();

CleanupStack::PushL(iFieldDef);

iFieldDef->AppendL(KUidContactFieldGivenName);

iFieldDef->AppendL(KUidContactFieldFamilyName);

_LIT(KFindToken, "Bond");

CIdleFinder * iFinder = iContactsDb->FindAsyncL( KFindToken, iFieldDef, this);

CleanupStack::PushL(iFinder);

if(iFinder->IsComplete())

   {

if(iFinder->Error() == KErrNone)

        {

CContactIdArray* result = iFinder->TakeContactIds();

CleanupStack:: PushL(result);

for(TInt i=0; i<result->Count(); i++)

   {

TContactItemId cardId = (*result)[i];

CContactItem* ownCard = iContactsDb ->OpenContactL(cardId);

CleanupStack::PushL(ownCard);

TInt index =

ownCard->CardFields().Find(KUidContactFieldGivenName);

ownCard->CardFields()[index].TextStorage()->SetTextL(KOtherForename);

//提交所做的修改，如果這里不做更改可以調用CloseContactL直接關閉

//但是一旦用OpenContactL或OpenContactLX打開就必須調用兩者之一關閉

iContactsDb ->CommitContactL(*ownCard);

CleanupStack::PopAndDestroy();// ownCard

}

CleanupStack::PopAndDestroy();//result;

          }

}

CleanupStack::PopAndDestroy(3);// iContactsDb、iFieldDef、iFinder

 

例6、       導出所選通訊錄條目到文件（vCard）

在這里，主要使用CContactDatabase類中ExportSelectedContactsL函數，關于該函數的定義可以查看SDK文檔；而且在這里與前次遍歷不一樣的是，加了一個過濾器CCntFilter類，雖然取法仍然是所有通訊條目，但做法不一樣，具體例程如下：

RFs fileSession;

//連接文件服務器

User::LeaveIfError(fileSession.Connect());

CleanupClosePushL(fileSession); //1

//打開默認數據庫

CContactDatabase* contactDb = CContactDatabase::OpenL();

CleanupStack::PushL(contactDb); //2

//新建過濾器

CCntFilter* filter = CCntFilter::NewLC(); //3

filter->SetContactFilterTypeALL(EFalse);

//按vCard格式導出

filter->SetContactFilterTypeCard(ETrue);

//安裝filter

contactDb->FilterDatabaseL(*filter);

//取出滿足條件的記錄數據項數組

CContactIdArray* exportContact = CContactIdArray::NewL(filter->iIds);

CleanupStack::PushL(exportContact); //4

 

RFile file;

//新建文件，aFileName是文件名字

file.Replace(fileSession,aFileName,EFileWrite);

CleanupClosePushL(file); //5

//聲明文件流

RFileWriteStream outputStream(file);

CleanupClosePushL(outputStream); //6

 

TUid id;

id.iUid = KVersitEntityUidVCard;

//導出到文件

contactDb->ExportSelectedContactsL(id,*exportContact, aWriteStream,
CContactDatabase::EExcludeUid);

CleanupStack::PopAndDestroy(6，contactDb);

 

Symbian S60獨有通訊錄操作API引擎

以上是適用于任何Symbian OS通訊錄操作的方法，在S60平臺SDK中nokia專門為我們建立了一個操作通訊錄的引擎，以及相對應的產生了一些封裝的類：

CPbkContactEngine（通訊錄引擎類）：如果已經存在一個缺省數據庫，CPbkContactEngine::NewL()就連接到該數據庫，否則創建該數據庫。當然也可以傳入文件名，打開一個指定的通訊錄數據庫，根據頭文件cpbkcontactengine.h，他就是對CContactDatabase和觀察器類MContactDbObserver封裝了下并進行了一些優化，簡便了我們操作時的一些代碼，為此操作起來比較方便。

CPbkContactItem（通訊錄條目類）：該類頭文件是CPbkContactItem.h，主要對通訊錄條目類CContactItem的封裝和優化，可以看出很多導出函數都是一致的。

TPbkContactItemField（域類）：不用想也知道這個類是怎么來的了，該類的頭文件tpbkcontactitemfield.h。有興趣的可以去研究比照一下。

當然也有其他一些封裝的類，只不過離通訊錄模型比較遠的，我們就不多展開了，在例子中看其使用。

例7、       新建通訊錄條目

_LIT(KFName,"King");

_LIT(KLName,"Chai");

_LIT(KNumber,"13777777777");

//運用引擎打開默認通訊錄

CPbkContactEngine* iPbkContactEngine = CPbkContactEngine::NewL();

CleanupStack::PushL(PbkContactEngine);//1

//新建一空通信錄項

CPbkContactItem* contact = iPbkContactEngine->CreateEmptyContactL();

CleanupStack::PushL(contact); //2

//設置first name 域

TPbkContactItemField* field = contact->FindField(EPbkFieldIdFirstName);

CleanupStack::PushL(contact); //3

field->TextStorage()->SetTextL(KFName);

//設置last name 域

field = contact->FindField(EPbkFieldIdLastName);

field->TextStorage()->SetTextL(KLName);

//設置手機號碼域

field = contact->FindField(EPbkFieldIdPhoneNumberMobile);

field->TextStorage()->SetTextL(KNumber);

//可以添加其他值域

//...

//修改后結果添加到數據庫中，并返回這個通信錄項的id，該id可以以后使用

TContactItemId Id = iPbkContactEngine->AddNewContactL(*contact);

CleanupStack::PopAndDestroy(3);

以上代碼是否比例4的代碼相對來說更簡單些啊？

 

例8、       修改通訊錄條目

實現修改和新建的代碼類似，不同是你需要找到你要修改的通訊錄條目aContactId，然后找到要修改的域進行修改，最后導入數據庫。

_LIT(number,"13500000000");

TBuf<11> phonenumber(number);

CPbkContactEngine* iPbkContactEngine = CPbkContactEngine::NewL();

CleanupStack::PushL(PbkContactEngine);//1

//這里打開條目后加鎖，以防其它客戶端打開

CPbkContactItem* contact = iPbkContactEngine->OpenContactLCX(aContactId);

CleanupStack::PushL(contact); //2

//找到需要修改的field

TPbkContactItemField* field = contact->FindField(EPbkFieldIdPhoneNumberMobile);

CleanupStack::PushL(field); //3

//設置并確認修改

field->TextStorage()->SetTextL(phonenumber);

iPbkContactEngine ->CommitContactL(*contact);

CleanupStack::PopAndDestroy(2)

 

 

 

 

 

 

 

附錄vCard：

手機應用開發中經常會遇到有關OBEX協議的問題，其實在通信錄開發中也遵循這個協議，通信錄中的數據是存在一個名叫vCard的載體里。vCard是一類電子名片，得到許多電子設備（如PDA和移動電話等）的支持。vCard的目的是：在這些設備之間用某些協議實現方便的通信錄數據傳遞。可以將vCard編碼成MIME規范（RFC 1521）所定義的明碼文本。這種編碼確保了各種vCard與限制為7位字符集（如在SMS消息中使用的編碼）的傳遞編碼的完全兼容。

一張vCard被格式化如下（說實話，下面這個vCard我也沒看懂，有看懂的幫忙解釋下）：

BEGIN:VCARD

VERSION:2.1

N:Wilkinson;Steve

FN:Steve Wilkinson

ORG:EMCC Software Ltd.

TEL;WORK;VOICE:01617779700

ADR;WORK;ENCODING=QUOTED-PRINTABLE:;;108 Manchester

d.=0D=0ACarrington;Manchester;UK;M31 4BD;United Kingdom LABEL;WORK;ENCODING=QUOTED-PRINTABLE:108 Manchester Rd.=0D=0ACarrington=0D=0AManchester, UK M31 4BD=0D=0AUnited K= ingdom

EMAIL;PREF;INTERNET:steve.wilkinson@emccsoft.com

REV:20030909T164330Z

END:VCARD

通信錄模型中的許多功能都與vCard的處理有關，以保證Symbian應用開發伙伴們能方便地編制符合電子名片及通訊錄交換方面的工業標準的代碼。

 

致謝：

全文暫告一個段落，應該說自己書都沒有看過，主要參考了網上一些人整理的文章，感謝csdn的風之云的玩轉通訊錄（http://blog.csdn.net/welcome_ck/archive/2005/01/06/242686.aspx），本文原型主要來自于他，另外還參考了兩篇代碼文檔，一篇用C++實現的訪問Symbian手機電話薄（出處http://jcszjswkzhou.itpub.net/post/32804/369208），另一篇忘了出處。由于很多例子本人只是走讀改進了下，還未來得及親測，所以如果有網友親測了某些實例，通不過還望能告知下，當然小筆在用到的時候也會親測下，在此謝過以上三人，當然還要感謝公司和兩位同事，并先感謝有時間來親測的網友。

另：轉載煩請注明http://m.shnenglu.com/franksunny/，以便更多的學習交流