2 Design and Concepts
This chapter addresses the things that you as a programmer should know about libabenabler when developing it and use it implement your own address book applications. It helps to understand its architecture and implementation. Armed with this knowledge, you will be better equipped to make this enabler run with higher performance, avoids potential pitfalls such as deadlocks or unexpected errors and even import any new features on your needs. You will see how AddressBook works in relation to your code and you can be more confident that you are attacking the problem from the right direction.
2.1 Architecture
Before we get started discussing the principle data structures, let's have a basic view on the architecture of libabenabler.
Figure 2.1 Architecture of libabenabler
As we can see in the figure 2.1, enabler provides the unique interfaces to applications but has different low-level implementation modules. It uses session to hold each connection between application and real storage repository. Each application can launch more than one session through enabler interfaces and each session is related to a specific storage repository by a proper address book module.
2.2 Concept
Address book enabler define a set of concepts such as contacts, category, field and template.
Field has a number of attributes such as a value type (e.g. string, number, date, URI, phone number, etc), a printable label (e.g. "Name", "Mobile Number", etc), a maximal size. Also a field may have a value. Fields are created from field templates.
Template defines the initial values of a field's attributes (the value type, the label, the maximal size, etc) and the field semantics (i.e. first name, mobile phone number, etc.). This specification defines a set of standard field templates; platform vendors, application developers and end users may also create sets of custom field templates. Once created a field keeps a reference to its template, therefore, for a given field it's always possible to know the field template it has been created from and consequently the semantics of the field.
Contact is an item in the address book, representing a person, a company, etc. A contact is a collection of fields, such as name, phone number and so on. A contact may contain several fields created from one field template, e.g. a contact may have two "mobile number" fields created from the same "mobile phone number" field template. Among these fields, only one field may be the default field of the field template, and applications can use a pair of specific setter and getter functions to manipulate its default field.
Address book maintains a set of available field templates which includes a subset of standard field templates and possibly a set of custom field templates. Applications can update the custom field template set adding new custom field templates into this set or removing field templates from this set.
Category represents a group of contacts such as friends, business partners, etc. Each contact may belong to one or more categories. Each category also has a set of fields such as name, ringtone, which could specify the default ring tone for incoming calls from the contacts belonging to this category, etc.
This specification defines a set of standard field templates listed in the table 2.1:
Table 2.1: List of existing field templates
|
FTID |
Printable Label |
Type |
Description |
|
1 |
¡°¡± |
Integer |
Contact/Category identifier |
|
2 |
¡°¡± |
Integer |
Category identifier which the contact belongs to |
|
3 |
¡°Last Name¡± |
String |
|
|
4 |
¡°Middle Name¡± |
String |
|
|
5 |
¡°First Name¡± |
String |
|
|
6 |
¡°Nick Name¡± |
String |
|
|
7 |
¡°Mobile Num¡± |
Telephone Number |
|
|
8 |
¡°Home Num¡± |
Telephone Number |
|
|
9 |
¡°Business Num¡± |
Telephone Number |
|
|
10 |
¡°Fax Num¡± |
Telephone Number |
|
|
11 |
¡°Company¡± |
String |
|
|
12 |
¡°Department¡± |
String |
|
|
13 |
¡°Website¡± |
URI |
|
|
14 |
¡°Email¡± |
String |
|
|
15 |
¡°Picture¡± |
URI |
|
|
16 |
¡°Ringtone¡± |
URI |
|
|
17 |
¡°Home street¡± |
String |
|
|
18 |
¡°Home City¡± |
String |
|
|
19 |
¡°Home state¡± |
String |
|
|
20 |
¡°Home zip¡± |
String |
|
|
21 |
¡°Home country¡± |
String |
|
|
22 |
¡°Business street¡± |
String |
|
|
23 |
¡°Business City¡± |
String |
|
|
24 |
¡°Business state¡± |
String |
|
|
25 |
¡°Business zip¡± |
String |
|
|
26 |
¡°Business country¡± |
String |
|
|
27 |
¡°Category Name¡± |
String |
|
|
28 |
¡°Presense¡± |
Integer |
Presense information of a network address book entry |
|
29 |
¡°IM_URI¡± |
String |
|
|
30 |
¡°subscription¡± |
Integer |
|
2.3 Modules
Enabler describes module functionality in a transparent data structure ab_module_t and it treats all the modules as two different types: static and plug-ins. Static modules are integrated in enabler library at compile time while plug-ins modules are loaded at runtime. Currently local flash module and SIM card module are implemented as static and network module is a plug-in.
An enabler module SHOULD supply two function symbols named "ab_plugin_get_module" and "ab_plugin_get_loc_support ". The former one return a constant pointer points to an ab_module_t object which defines functionalities provided in plug-in and the latter one describes which storage repository type plug-in supports by using an ab_location_t enumeration.
2.4 Templates
As we discussed in section 2.2, contacts and categories in an address book are consisted of a set of fields defined in independent templates. In current implementation of enabler, templates are defined by user in plain-text files with a specific format. For example, in a text file named "cnt_local.tmpl" would have following lines:
D, 1, UID, Unique Identifier, INTEGER, PRIMARY, 4,
D, 3, Full Name, Full Name, STRING, NONE, 40,
D, 7, Mobile Number, Mobile Number, STRING, MULTI, 20,
E, 7, 2nd Mobile Number, 2nd Mobile Number, NULL, NULL, NULL,
This file describes a contact in local flash repository which would have a structure layout with one UID field, one full name field and two mobile number fields at creating time. Each single line in template represent a field template and different items in template are separated by a separator ','. Letter 'D' or 'E' at head of each line indicate what kind of filed this line intend to define. 'D' stands for default while 'E' stands for extends. The second item is field template identifier and all identifier are listed in table 2.1. The third and forth item describe display label and description for the current field sperately. The fifth item define type of the field and the sixth item lists the item attributes. The "Multi" attribute means a contact can define one default field and more than one extended field of this field template. The last item define the maximum size of field can support.