Editing Documentation/Maemo 5 Developer Guide/Using Generic Platform Components/Using Address Book API

 

The Maemo 5 Address Book is a fully-featured address book software stack. This includes the Contacts application (process name "osso-addressbook"), a support library which implements most of its functionality (libosso-abook), and contact storage via Evolution Data Server (EDS). As any address book program, the Contacts application allows you to add, edit and delete contacts. But beyond basic contacts, the Address Book supports browsing and importing SIM card contacts and tightly integrates VoIP and IM contacts provided by the Telepathy communications framework.

[[Image:abook-components.png]]

The libebook library provides access to the contacts stored in Evolution Data Server. The higher-level libosso-abook library uses libebook extensively internally, and you will not likely need to use libebook directly. For more advanced contact manipulation, libebook's EVCard class may be useful (since the main libosso-abook contact class, OssoABookContact is a subclass of it).

N.B. Developers are discouraged from using the EBook and EBookView classes of libebook because they do not provide libosso-abook's features of contact aggregation, presence abstraction, and so on.

= Non-Widget Classes =

== OssoABookAvatar ==

 

=== Overview ===

 

=== Basic Example ===

<pre>

include <glib.h>

</pre>

=== Additional API ===

Because images can take a relatively long time to process and are inconvenient to compare, it's often easiest to compare simple, unique values to determine image equality. This is especially useful when caching avatar images. In this snippet, image_token is a hashable value:

<pre>

</pre>

=== Notable Signals ===

* notify::avatar-image

=== Complete API Documentation ===

=== Overview ===

OssoABookContacts may possess a number of different capabilities, so the OssoABookCaps interface (which OssoABookContacts implements) provides a simple means to detect these capabilities.

=== Basic Example ===

The core of OssoABookCaps is the OssoABookCapsFlags enumeration, accessible by osso_abook_caps_get_capabilities(). Its values are orthogonal and may be bitwise-ORed or -ANDed together for more detailed capabilities checks:

<pre>

</pre>

=== Additional API ===

OssoABookCaps also contains a convenience function for getting the capabilities of our own accounts (of type McAccount*).

<pre>

</pre>

=== Notable Signals ===

* notify::capabilities

== OssoABookContact ==

 

The central class in libosso-abook is OssoABookContact, which is used in a few different ways:

So if you just wish to display all of your contacts' names and IM availability, you would simply use the appropriate OssoABookContact functions on the list of master contacts and the master contacts will automatically report their "most-online" presence amongst their attached roster contacts (if any).

In addition to its own functionality, OssoABookContact implements the OssoABookAvatar, OssoABookCaps, and OssoABookPresence interfaces. So OssoABookContacts can be used in their functions and will emit their signals. See their documentation for more details.

This example is meant to show off a few functions that you may want to use to get specific, basic Contact details. If you would like to get its avatar, see the documentation on OssoABookAvatar; for its IM presence or capabilities, see OssoABookPresence and OssoABookCaps.

<pre>

</pre>

=== Additional API ===

There are many ways to use an OssoABookContact, and a significant portion of that lay in its parent classes and implemented interfaces (OssoABookAvatar, OssoABookCaps, and OssoABookPresence). See the appropriate documentation for more details.

Here are some highlights of additional API for OssoABookContact.

==== General Functions ====

Sometimes it can be handy to get a full listing of a contact's contents. In that case, you may wish to print out the low-level vCard representation of the contact. Note that this will not include the contents of any roster contacts, in the case of a master contact. Set the last argument to TRUE if you wish to include the contact's avatar data (this can be very long).

<pre>

</pre>

In case you need to sort some contacts, osso_abook_contact_collate() is a strcmp()-like function that does just that. So, to sort a GList of contacts:

<pre>

</pre>

 

==== Roster Contact List Handling ====

<pre>

</pre>

==== Roster Contacts ====

<pre>

</pre>

==== Attribute Convenience Functions ====

<pre>

</pre>

<pre>

</pre>

<pre>

</pre>

=== Notable Signals ===

* reset

* contact-attached

* contact-detached

=== Complete API Documentation ===

Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/OssoABookContact.html reference documentation for OssoABookContact].

== OssoABookPresence ==

 

=== Overview ===

:a well-known string describing the contact's availability. In Maemo 5, this string is always one of {"available", "away", "dnd" (do not disturb), "offline", and "unknown"}. The "type" (see below) is the preferred element for determining a contact's availability.  

:the string set by your contact (e.g., "I'm running outside")

:an integer representing the contact's availability. This is more fine-grained than "status" (see above) and the preferred way to determine a contact's availability

An OssoABookContact master contact has the aggregated presence of all its roster contact(s). In the case of status, the master contact will have the "most-online" status amongst its roster contacts. For example, given a master contact with roster contacts having statuses "away" and "offline", the master contact's status will be "away".

<pre>

</pre>

=== Additional API ===

The example above shows how to compare the basic TpConnectionPresenceType return value of osso_abook_presence_get_presence_type(). At a higher level, if you want to compare the relative availability of two OssoABookPresences (e.g., OssoABookContacts), you can use the convenience function osso_abook_presence_compare(). It works like most strcmp()-like functions, except that it returns a value < 0 is the first presence is more online than the other, and vice versa.

<pre>

</pre>

=== Notable Signals ===

* notify::presence-location-string

* notify::presence-status

* notify::presence-status-message

* notify::presence-type

=== Complete API Documentation ===

= Widget Classes =

== OssoABookContactChooser ==

OssoABookContactChooser is a widget that allows you to present a selectable list

of contacts to the user. The contact chooser is relatively flexible so that it

=== Basic Example ===

The following is a simple example of the use of OssoABookContactChooser:

<pre>

                 g_printf ("Selected Contacts:\n")

                         g_printf ("%s\n", osso_abook_contact_get_display_name((l->data));

</pre>

=== Additional API ===

osso_abook_contact_chooser_set_capabilities() allows you to limit the contacts

shown in the list to only those that have certain capabilities. For example, to

<pre>

</pre>

<pre>

</pre>

<pre>

</pre>

osso_abook_contact_chooser_set_visible_func() provides a way for the application

to supply a predicate function that will determine whether the contact should be

<pre>

</pre>

=== Complete API Documentation ===

== OssoABookTreeView ==

 

Although OssoABookTreeView's name might imply that it inherits from GtkTreeView,

it is actually an ancestor of GtkVBox that contains a GtkTreeView inside of a

HildonPannableArea. It provides a convenient way to display a list of contacts

and sets up the TreeView columns automatically. It can show the contacts' name,

Telephone number, presence status, and avatar image. These details can be

OssoABookTreeView object directly. Most of the time, applications will deal

with OssoABookContactView objects, which inherits from this class and does most

of the setup work for you.

=== Additional API ===

OssoABookTreeView is an aggregate widget, but it provides direct access to the

underlying widgets as well (e.g. osso_abook_tree_view_get_tree_view(),

osso_abook_tree_view_get_pannable_area().

view by using osso_abook_tree_view_set_filter_model().  The following example

shows how to display only those contacts whose names contain a certain string:

<pre>

</pre>

In addition, if you only want to display those contacts associated with a

particular VoIP or IM account, use the function

osso_abook_tree_view_set_aggregation_account ().  In addition to limiting the

contacts to only those specified by those accounts, it will also display the

* show-contact-avatar

* show-contact-name

* show-contact-presence

* show-contact-telephone

=== Complete API Documentation ===

== OssoABookContactView ==

 

OssoABookContactView provides a convenient widget for displaying a list of

contacts in a list. It builds upon OssoABookTreeView and adds a bit of

=== Basic Example ===

<pre>

</pre>

=== Additional API ===

OssoABookContactView has some additional convenience API that allows you to get

the contact (or properties of the contact) that currently has input focus:

* osso_abook_contact_view_get_focus()

* osso_abook_contact_view_get_focus_avatar()

* osso_abook_contact_view_get_focus_presence()

* osso_abook_contact_view_get_focus_caps()

osso_abook_contact_view_set_minimum_selection() and

osso_abook_contact_view_set_maximum_selection() allow fine-grained control over

how contacts can be selected.

=== Complete API Documentation ===

== OssoABookTouchContactStarter ==

OssoABookTouchContactStarter is a widget that displays the information for a

contact and can be used to initiate communication with a contact (email, IM,

=== Basic Example ===

OssoABookTouchContactStarter to display the details of a particular contact.

<pre>

</pre>

customize the OssoABookTouchContactStarter widget.  By default the contact

starter is created in 'read-only' mode.  But if the starter was created with

osso_abook_touch_contact_starter_new_with_editor(), a contact editor can be

launched by clicking the avatar icon. This allows the contact's details to be

changed directly from the contact starter widget. An editor can also be

launched programmatically by calling

osso_abook_touch_contact_starter_start_editor().

osso_abook_touch_contact_starter_new_not_interactive().  In addition, an

application can override the default actions by connecting to the

"pre-action-start" signal.  For example:

<pre>

</pre>

=== Complete API Documentation ===

= Glossary =

:a persistent master contact with one or more attached roster contacts.

:an OssoABookAggregator object which manages connections to the EDS backends and associates master contacts with their roster contacts.

:an OssoABookContact which aggregates the attributes of zero or one persistent master contacts and zero or more roster contacts.

:an OssoABookContact which is stored in the EDS local database and has zero or more roster contacts.

:an OssoABookContact which is stored in the EDS Telepathy backend and represents a (VoIP/IM username, account) pair. Roster contacts are always attached to exactly one temporary master contact or one or more persistent master contacts.

:a master contact which was created at run-time for a roster contact to attach to, so that all roster contacts have one or more master contacts. Temporary master contacts are not stored in the local database and their UIDs must not be stored beyond the lifetime of the contact aggregator to which they belong.

:a hashable ID which is unique across all EDS back-ends. See the definition for "temporary master contact" for relevant usage warnings.