学步园

IDBMgr 接口

IDBMgr接口函数用来创建、打开和删除数据库，数据库指的是多字段记录的集合。当数据库打开之后，就可以使用由Idatabase接口提供的函数来创建、检索及关闭数据库，并可以使用由IDRecord接口提供的函数来访问和更新单个记录。

注意：应用程序必需要有PL_FILE 和 PL_SYSTEM权限才能调用这个接口来打开、创建数据库。

IDBMGR_OpenDatabase()根据指定的数据库名称打开数据库，数据库名称为对应的包含数据库内容的BREW文件名称。当调用这个函数时，如果该数据库不存在就会创建一个新的数据库。

IDBMGR_OpenDatabaseEx()功能类似，但可以允许开发者指定最小记录大小和创建数据库时的最小记录数。该函数预留一些空间来保存指定数量的记录数。上述两个函数都返回一个指向Idatabase的指针，可以用来访问打开的数据库。

IDBMGR_Remove()通过删除包含记录的文件来删除一个数据库，如果数据库处于打开状态，必需先调用IDBMGR_Release() 先关闭数据库然后再删除它。

IDBMgr接口的使用步骤

1. 调用ISHELL_CreateInstance()创建一个指向IDBMgr接口的指针。
2. 调用IDBMGR_OpenDatabase()打开一个已存在的数据库或是新建一个数据库，如果需要为新创建的数据库指定最小记录数，使用IDBMGR_OpenDatabaseEx()。
3. 使用由步骤2得到的Idatabase接口指针，使用Idatabase接口函数来创建、检索数据库中的记录。使用IDBRecord接口函数来访问和修改一条记录。
4. 当不再需要使用数据库时调用IDATABASE_Release()来关闭一个数据库。
5. 有必要时调用IDBMGR_Remove()删除一个数据库。
6. 当不再需要使用IDBMgr接口指针时调用IDBMGR_Release()

IDatabase接口

IDatabase接口函数可以用来操作由IDBMgr接口打开或创建的数据库中的记录。首先调用IDBMGR_OpenDatabase()打开特定的数据库，然后使用由该函数返回的Idatabase接口指针来操作数据库，并可使用IDBRecord接口函数来访问单个数据库记录。当完成数据库操作时，调用IDATABASE_Release()关闭数据库。

IDATABASE_CreateRecord()创建一个新记录并在数据库中增加一条记录（函数IDBRECORD_Remove()用于在数据库中删除一条记录）。每条记录包含一个或多个字段，每个字段由一个AEEDBField结构定义，

AEEDBField结构定义：

typedef enum

{

AEEDB_FT_NONE,

AEEDB_FT_BYTE,

AEEDB_FT_WORD,

AEEDB_FT_DWORD,

AEEDB_FT_STRING,

AEEDB_FT_BINARY,

AEEDB_FT_PHONE,

AEEDB_FT_BITMAP,

AEEDB_FT_MAX

} AEEDBFieldType

typedef enum

{

AEEDBFIELD_NONE,

AEEDBFIELD_FULLNAME,

AEEDBFIELD_LASTNAME,

AEEDBFIELD_FIRSTNAME,

AEEDBFIELD_HOME_PHONE,

AEEDBFIELD_WORK_PHONE,

AEEDBFIELD_MOBILE_PHONE,

AEEDBFIELD_FAX, AEEDBFIELD_ADDRESS,

AEEDBFIELD_EMAIL,

AEEDBFIELD_URL,

AEEDBFIELD_DATE_TIME,

AEEDBFIELD_CATEGORY,

AEEDBFIELD_ALARM,

AEEDBFIELD_PREF_ID,

AEEDBFIELD_PREF_VER,

AEEDBFIELD_PREF_DATA,

AEEDBFIELD_TITLE,

AEEDBFIELD_TEXT

} AEEDBFieldName;

在AEEDBField结构中包含了下面的元素：

typedef structure

{

AEEDBFieldType fType;

AEEDBFieldName fName;

uint16 wDataLen;

void * pBuffer;

} AEEDBField;

其中字段名称这字段内容的一个描述（如姓名、电话号码、Email地址等）AEEDBFieldName枚举类型定义一些常用的字段名称。

字段类型给出了该字段的数据类型（字节，字、双字、字符串，二进制数、电话号码或位图等）。

字段存贮区指针指向字段内容的首地址。

字段长度指出字段内容长度。

当创建一个记录时，首先将数据填充到一个AEEDBField结构数组中，给出记录的字段名、类型、内容及长度。然后调用IDATABASE_CreateRecord(),给出指向该数组的指针，IDATABASE_CreateRecord()返回一个指向IDBRecord接口的指针，可以用来访问和更新该记录，字段类型的指定是在创建或更新单个记录时分别指定的，并不要求数据库中每条记录具有相同的结构。

创建并在数据库中增加了记录之后，可以使用另外的Idatabase接口函数来检索数据库。

检索数据库的每条记录。

1. 首先调用IDATABASE_Reset()将数据记录指定指向0。
2. 然后重复调用IDATABASE_GetNextRecord()来获得指向数据库中每条记录的IDBRecord接口指针，直到IDATABASE_GetNextRecord()返回空指针表明所有记录都已被遍历。

Idatabase接口使用步骤

1. 如有必要，调用ISHELL_CreateInstance()来创建一个指向IDBMgr的指针。
2. 调用IDBMGR_OpenDatabase()或IDBMGR_OpenDatabaseEx()来得到一个已存在或新建数据库的Idatabase接口指针。
3. 调用IDATABASE_CreateRecord()在由２得到的数据库中创建并增加一条记录。
4. 调用IDATABASE_Reset()和 IDATABASE_GetNextRecord() 来遍历整个数据库（比如查找满足某个条件的所用记录）。调用IDATABASE_GetRecordByID()可以根据指定的记录ＩＤ来检索某条记录。

结束数据库访问时调用IDATABASE_Release()来关闭数据库。

IDBRecord　接口

IDBRecord 接口包含了一组用于访问、更新数据库中记录的函数，使用IDatabase 接口函数来得到一个指向某条记录的IDBRecord接口实例指针，IDBRecord指针可以通过IDATABASE_CreateRecord()返回一个新记录指针，通过IDATABASE_GetNextRecord() 和 IDATABASE_GetRecordByID() 返回一个已存在记录的IDBRecord指针，得到IDBRecord指针之后，就可以使用IDBRecord 接口函数来操作记录的字段，结束对一个记录的访问之后，调用IDBRECORD_Release()来关闭它。

每条记录字段包含字段名、类型、内容指针及内容长度，记录操作函数针对的是当前字段，IDBRECORD_Reset()使用记录的第一个字段成为当前字段，IDBRECORD_NextField()将当前字段的下一个字段成为当前字段，该函数同样返回字段名称、类型及长度（不返加字段内容指针）。或者返回一个字段结束标识以表明记录的所用字段都已被遍历过。IDBRECORD_GetField()返回指向当前字段内容的指针，同时返回当前字段的名称、类型及长度。

IDBRecord接口也提供了一个简明函数来访问字段类型为已知的当前字段内容。

• IDBRECORD_GetFieldWord()检索字段类型为Word型的字段内容。
• IDBRECORD_GetFieldDWord()检索字段类型为DWord型的字段内容。
• IDBRECORD_GetFieldString()检索字段类型为字符串型的字段内容。

上述函数在数据类型不匹配时返回一个错误信息。

IDBRecord接口函数用法

1. 如需要，调用ISHELL_CreateInstance()创建一个指向IDBMgr的指针。
2. 调用IDBMGR_OpenDatabase() 或 IDBMGR_OpenDatabaseEx()打开一个指向新建或已存在的Idatabase接口指针。
3. 调用IDATABASE_CreateRecord(),      IDATABASE_GetRecordByID()或      IDATABASE_GetNextRecord() 来得到一个 IDBRecord 接口指针用于操作该记录。

访问指定记录

1. 调用IDBRECORD_Reset() 和 IDBRECORD_NextField()来遍历一条记录的所有字段以得字段名称、类型及内容长度。调用一个IDBRECORD_GetField()函数来取得当前字段的内容。
2. 调用IDBRECORD_GetID()获得该记录的唯一索引。
3. 调用IDBRECORD_Update()为一个记录提供新值。
4. 调用IDBRECORD_Remove() 从数据库中删除一条记录。
5. 当不需再访问某条记录时调用 IDBRECORD_Release() 来关闭它，如果如步骤４中删除一条记录，则不需要再调用IDBRECORD_Release() 来关闭它

IAddrBook 接口

IaddrBook 接口提供与ＯＥＭ地址簿交互的能力，OEM地址簿为手机上的首选地址簿，它不支持多地址簿。

IaddrBook接口提供了对地址簿集合的访问，地址簿记录包含了存放于地址簿中数据，每条地址簿地录可以属于某个特定的分类（如私人或商业分类）。所支持的分类由OEM来控制，可以通过调用IADDRBOOK_EnumCategoryInit() 和 IADDRBOOK_EnumNextCategory() 来枚举出由OEM所支持的分类。

每个记录包含一组字段集合，每个字段具有一个FieldID和字段类型，FieldID由枚举类型AEEAddrFieldID来索引，OEM可以增加OEM特定的字段。

同一个字段不能包含多个值，如果一个地址簿记录需要记录多于一个HOME PHONE号码，则需要为每个号码给出一个字段。

同样的情形，如果一个号码既是家庭号码又是办公号码，需要两个不同的字段来表明家庭和工作信息。AEE_ADDRFIELD_PHONE_HOME，AEE_ADDRFIELD_PHONE_WORK。

IAddrBook提供了一个ＢＲＥＷ接口用于访问指定的地址簿，地址簿为一条或多条地址记录的集合。

接口提供了：

• 枚举地址簿分类的能力。
• 枚举所支持字段字型的能力。
• 在地址簿中增加一条记录。
• 根据指定的字段或分类查找地址簿。
• 浏览整个地址簿。

IAddrBook接口可以用于访问设备地址簿或在RUIM卡的地址簿，访问设备地址簿必需使用 AEECLSID_ADDRBOOK来创建IaddrBook接口指针，而需访问RUIM卡时，则为AEECLSID_ADDRBOOK_RUIM。

IAddrRec接口

IAddrRec提供了访问地址簿记录单个字段的能力：

• 为记录增加一个字段。
• 更新一个现存记录的字段。
• 删除一个现存记录的字段。
• 修改一个记录的分类。