BREW开发教程(12):数据库操作

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

AEEDB_FT_BYTE Field contains an 8 bit value.
AEEDB_FT_WORD Field contains a 16 bit value.
AEEDB_FT_DWORD Field contains a 32 bit value.
AEEDB_FT_STRING Field contains an AECHAR array (NULL terminated).
AEEDB_FT_BINARY Field contains a Binary value.
AEEDB_FT_PHONE Field contains an AECHAR array (NULL terminate).
AEEDB_FT_BITMAP Field contains a bitmap in BMP format.

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_FULLNAME Field contains a full name.
AEEDBFIELD_LASTNAME Field contains a last name.
AEEDBFIELD_FIRSTNAME Field contains a first name.
AEEDBFIELD_HOME_PHONE Field contains a home telephone number.
AEEDBFIELD_WORK_PHONE Field contains a work telephone number.
AEEDBFIELD_MOBILE_PHONE Field contains a mobile telephone number.
AEEDBFIELD_FAX Field contains a fax number.
AEEDBFIELD_ADDRESS Field contains a mailing address.
AEEDBFIELD_EMAIL Field contains an email address.
AEEDBFIELD_URL Field contains a URL.
AEEDBFIELD_DATE_TIME Field contains date and time.
AEEDBFIELD_CATEGORY Field contains a category specification.
AEEDBFIELD_ALARM Field contains an alarm.
AEEDBFIELD_PREF_ID Field contains a Preference ID.
AEEDBFIELD_PREF_VER Field contains a Preference Version Number.
AEEDBFIELD_PREF_DATA Field contains Preference Data (such as user preference).
AEEDBFIELD_TITLE Field contains a Title.
AEEDBFIELD_TEXT Field contains text.

在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()在由2得到的数据库中创建并增加一条记录。
  4. 调用IDATABASE_Reset()和 IDATABASE_GetNextRecord() 来遍历整个数据库(比如查找满足某个条件的所用记录)。调用IDATABASE_GetRecordByID()可以根据指定的记录ID来检索某条记录。

结束数据库访问时调用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() 来关闭它,如果如步骤4中删除一条记录,则不需要再调用IDBRECORD_Release() 来关闭它

IAddrBook 接口

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

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

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

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

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

IAddrBook提供了一个BREW接口用于访问指定的地址簿,地址簿为一条或多条地址记录的集合。

接口提供了:

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

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

IAddrRec接口

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

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