20110510 Brew工程师培训笔记——第十七章 地址簿的使用

第十七章 地址簿的使用

一、主要内容

（1）、地址簿接口的创建

（2）、有关记录的分类

（3）、地址簿记录的介绍

（4）、修改记录中的字段

（5）、为地址簿增加记录

（6）、从地址簿中获取记录

（7）、有关地址簿应用的一些常见问题

二、使用地址簿的准备

（1）、接口的创建

（2）、在应用的MIF文件中选定“Access to Address Book” 

（3）、不支持多地址簿操作 

三、记录的分组

（1）、手机地址簿中的记录分组 

（a）、typedef uint16 AEEAddrCat;

（2）、预先定义好的分组

（a）、AEE_ADDR_CAT_NONE 没有分组

（b）、AEE_ADDR_CAT_PERSONAL 私人记录分组

（c）、AEE_ADDR_CAT_BUSINESS 商务记录分组

（d）、AEE_ADDR_CAT_USER_DEFINED 手机厂商定义的记录分组的起点

（e）、AEE_ADDR_CAT_ERR手机厂商定义的记录分组的最大值

（3）、手机厂商定义的记录分组 

（a）、必须介于AEE_ADDR_CAT_USER_DEFINED 和AEE_ADDR_CAT_ERR两个值之间 

四、记录的分组示例

if(AEE_SUCCESS == IADDRBOOK_EnumCategoryInit(pMe->m_pIAddrBook)) 

// initialize the enumeration operation

{

AEEAddrCat ac; // stores enumerated category

while(IADDRBOOK_EnumNextCategory(pIAddrBook, &ac)) 

// enumerate all supported categories

{

// perform some action...

}

}

五、地址簿记录

（1）、地址簿记录中的数据存储在手机厂商定义的一系列字段中，具体的字段在数据结构AEEAddrField 中 

typedef structure {

AEEAddrFieldID fID; // label of the IAddrBook field

AEEAddrFieldType fType; // datatype stored in this field (such as FT_STRING)

void * pBuffer; // pointer to the actual data

uint16 wDataLen; // length of the data (bytes)

} AEEAddrField;

六、获得记录字段的类型

// initialize the enumeration operation

if(AEE_SUCCESS == IADDRBOOK_EnumFieldsInfoInit(pIAddrBook, addressCat)) 

{

// stores enumerated field info

AEEAddrFieldInfo afi; 

// enumerate all supported fields

while(IADDRBOOK_EnumNextFieldsInfo(pIAddrBook, &afi)) 

{

// perform some action...

}

}

七、修改记录中的字段

（1）、IAddrRec 可以实现对地址记录中个别字段的访问。 它提供以下功能：

（a）、为记录添加新字段

（b）、更新现有地址记录的字段

（c）、删除现有地址记录的字段

（d）、更改记录

八、增加一个字段的方法示例

AEEAddrField aField;

AECHAR sCPNum[MYMAXPHONELEN];

// convert char to AECHAR

STRTOWSTR("13301330133", sCPNum, sizeof(sCPNum));

 aField.fID = AEE_ADDRFIELD_PHONE_CELL; // fill in cell phone field

aField.fType = AEEDB_FT_PHONE;

aField.pBuffer = sCPNum;

aField.wDataLen = WSTRLEN(sCPNum);

// add field to record

if(AEE_SUCCESS != IADDREC_AddField(pIAddRec, &aField))

{

// error condition

}

九、增加记录到地址簿

（1）、要准备好该记录的各个字段 

（2）、使用的主要方法是IADDRBOOK_CreateRec()函数 

// create record

if(NULL == (pIAddrRec = IADDRBOOK_CreateRec(

pIAddrBook, AEE_ADDR_CAT_NONE, aFields, 

MYNUMFIELDS)))

{

/ / record create fail, check IADDBOOK_GetLastError()

}

十、地址簿中记录的获取

（1）、按照一定的规则进行枚举

（a）、需要使用IADDBOOK_EnumRecInit() 来初始化一组记录的集合 

（b）、再利用IADDRBOOK_EnumNextRec()来得到所需的结果 

（2）、更具该记录的标识直接获得

（a）、可以简单的通过IADDRBOOK_GetRecByID()方法

十一、常见问题

（1）、导致ISHELL_CreateInstance()的失败

（a）、忽略了MIF文件中正确权限的选择

（b）、SDK的版本与手机上的BREW版本不一致 

（2）、地址簿操作异常

（a）、头文件使用错误

（b）、由于地址簿是与目标手机密切相关的，手机厂商有时会提供自己的头文件

十二、本章关键点

（1）、地址簿的创建

（2）、地址簿分组的访问

（3）、地址簿记录的访问

十三、问题回顾

（1）、如何访问RUIM卡上的地址簿？

（2）、向地址簿增加记录时要注意什么？

（3）、如何修改记录的字段？