As a consequence some features have been granted in Streamezzo solution in order to provide the ability to consult and manipulate data from the handset contact book.

Principle

As goes for other handset related data browsing / consulting / management, the provided features rely on presenter pattern, close to usual database accesses:

• A variable module enables to manage the index of the currently selected entry (i.e. like a database cursor).
• A filter can be operated on the set of entries stored on the handset (i.e. database select-where statement, retrieving as a recordset primary keys for all entries matching criteria).
• A loader enables accessing a given entry from the filtered subsets of entries stored on the handset (i.e. access entry for the recordset, based on index or primary key).
• An accessor enables consulting data for a given loaded entry (i.e. consult database fields based on entry primary key).
• Dedicated operations enable to add/update/delete a given loaded entry (i.e. insert / update / delete from database).

Features

Variables module

This arithmetic variables module is meant to be used jointly with the contact book integration. Those variables are set in a reserved space for this. The purpose of this module is especially to manage a variable that is intended to stored the currently selected contact book entry index (in case the contact book is displayed in the rich media application).

• Declare variable / Set variable value: cmd://pk_varSet?name=[name]&value=[value]
• Get variable value: cmd://pk_varGet?name=[name]&idT=[Text_DEF_to_store_get_value]&idS=[startable_DEF_variable_is_declared]&idH=[startable_DEF_variable_is_not_declared]
• Add value to current variable value: cmd://pk_varAdd?name=[name]&value=[value]
• Sub value from current variable value: cmd://pk_varSub?name=[name]&value=[value]

Filter manipulation

This feature enables specifying which subset of the entries contained in the handset contact book are expected to be accessed. Applying the filter will load data in memory (i.e. make it available for access).
As a consequence an alternative instruction will enable to explicitly unmount such data from memory (i.e. free memory when data becomes useless). Additionally, mounted data that is supposed to be updated from storage (refreshed) will require to call back the filter.

• Filter setting: cmd://pk_setFilter?name=[my_filter_name]&expr=[my_filter_criteria_expression] Attributes that can be filtered on:
  • FIRSTNAME
  • LASTNAME
  • MOBILEPN
• Filter release: cmd://pk_freeFilter?name=[my_filter_name]

Data loading

This features enables accessing a given entry from the subset selected when applying the filter. An entry can be accessed either from its index in this subset (depending on the operated sort) or from an entry id (i.e. retrieving the specifying a backward or forward index from a given entry).

• By index: cmd://pk_loadID?filter=[my_filter_name]&index=[my_variable_name (source)]&idT=[my_Text_nodes_DEF_list]&idS=[my_item_exist_startable_nodes_DEF_list]&idH=[my_item_not_exist_startable_nodes_DEF_list]&empty=[my_no_item_startable_node_DEF]
• By (id, delta): cmd://pk_loadID?filter=[my_filter_name]&id=[my_item_id]&delta[my_delta]&index=[my_variable_name (target)]&idT=[my_Text_nodes_DEF_list]&idS=[my_item_exist_startable_nodes_DEF_list]&idH=[my_item_not_exist_startable_nodes_DEF_list]&empty=[my_no_item_startable_node_DEF]

Attribute retrieval

This feature enables retrieving a given attribute value for a given entry, based on both the attribute name and the entry id (the entry id has usually been retrieved relying on data loading). cmd://pk_getAttr?id=[my_item_ID]&name=[my_attribute_name]&target=[my_node_DEF]&field=[my_node_attribute]&idS=[my_attribute_exist_startable_DEF]&idH=[my_attribute_not_exist_startable_DEF]

Possible attribute names are:

• FIRSTNAME: string (the first name of the item)
• SECONDNAME: string (the second name of the item)
• LASTNAME: string (the last name of the item)
• MOBILEPN: string (the mobilephone number of the item)
• WORKPN: string (the work phone number of the item)
• HOMEPN: string (the home phone number of the item)
• ISPBKENTRY: boolean (is the item stored on the device phone book?)
• ISSIMENTRY: boolean (is the item stored on the SIM card?)

Data manipulation (add, delete, update)

This feature enable updating the contact book data stored in the handset. Updated or deleted entries are specified based on their entry id (the entry id has usually been retrieved relying on data loading).

• Add entry in phone book: cmd://pk_addEntry?firstname=[my_firstname]&lastname=[my_lastname]&secondname=[my_secondname]&mobilepn=[my_mobilepn]&workpn=[my_workpn]&homepn=[my_homepn]&storage=[SIM|PHONE]
• Delete entry from phone book: cmd://pk_delEntry?id=[my_item_ID]&success=[my_deletion_success_startable_DEF]&error=[my_deletion_error_startable_DEF]
• Update entry in phone book: cmd://pk_updateAttr?id=[my_item_ID]&name=[my_attribute_name]&source=[my_Text_DEF]&field=[my_node_field_name]&success=[my_update_success_startable_DEF]&error=[my_update_error_startable_DEF]

Typical example

The coding example below stands for a rich media contact book presenter that shows infos for one contact at a time and enables displaying the ones for the new or previous entry.

Known limitations

• Only Symbian UIQ platform manages both device and SIM contacts / SIM contacts are NOT manageable on other platforms.
• On Java devices, feature availability depends on JSR-75 availability and implementation + certification may be required.
• Some operations on the handset contact book may require a significant processing delay, according to the amount of entries.
• Moreover, during this delay the overall application performances will be altered, so this shall be considered with care.