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

(Overview)
(Undo revision 50501 by 94.23.1.28 (Talk) vandalism)
 
(13 intermediate revisions not shown)
Line 1: Line 1:
-
= Overview =
+
The [[Open development/Maemo roadmap/Fremantle|Maemo 5]] Address Book is a fully-featured address book software stack. This includes the Contacts application (process name [http://maemo.org/packages/view/osso-addressbook/ osso-addressbook]), a support library which implements most of its functionality ([http://maemo.org/packages/view/libosso-abook/ libosso-abook]), and contact storage via Evolution Data Server ([http://maemo.org/packages/view/evolution-data-server-addressbook/ EDS]). As with 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.
-
 
+
-
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.
+
This allows Contacts and your application to automatically add IM contacts to your account when adding an IM username to a contact or add a dialog to initiate phone calls, VoIP calls, text messages, emails, or chats with a single tap, and much more.
This allows Contacts and your application to automatically add IM contacts to your account when adding an IM username to a contact or add a dialog to initiate phone calls, VoIP calls, text messages, emails, or chats with a single tap, and much more.
Line 11: Line 9:
The main components in the Maemo Address Book stack are the Contacts application (osso-addressbook), support library (libosso-abook), and Evolution Data Server.
The main components in the Maemo Address Book stack are the Contacts application (osso-addressbook), support library (libosso-abook), and Evolution Data Server.
-
[[Image:abook-components.png]]
+
[[Image:abook-components.png|frame|center|alt=Diagram of address book components|Address book components]]
=== The Contacts application (osso-addressbook) ===
=== The Contacts application (osso-addressbook) ===
Line 39: Line 37:
==== libebook ====
==== libebook ====
-
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).
+
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, <code>OssoABookContact</code> 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.
+
N.B. Developers are discouraged from using the <code>EBook</code> and <code>EBookView</code> classes of libebook because they do not provide libosso-abook's features of contact aggregation, presence abstraction, and so on.
=== Contacts Home Applet (osso-abook-home-applet) ===
=== Contacts Home Applet (osso-abook-home-applet) ===
Line 47: Line 45:
In order to minimize the number of taps required to contact your favorite contacts, Contacts provides a way to add shortcuts to specific contacts on your home views. The Contacts Home Applet is the process that draws these shortcuts on the home view.
In order to minimize the number of taps required to contact your favorite contacts, Contacts provides a way to add shortcuts to specific contacts on your home views. The Contacts Home Applet is the process that draws these shortcuts on the home view.
-
= Non-Widget Classes =
+
== Non-Widget Classes ==
-
== OssoABookAvatar ==
+
=== OssoABookAvatar ===
-
 
+
-
=== Overview ===
+
Contacts may have an associated image, called their "avatar". An avatar may be retrieved from a corresponding contact on an IM account or from a user-set local image.
Contacts may have an associated image, called their "avatar". An avatar may be retrieved from a corresponding contact on an IM account or from a user-set local image.
Line 60: Line 56:
# The most-recently-changed avatar amongst all attached roster contacts (i.e., on IM servers)
# The most-recently-changed avatar amongst all attached roster contacts (i.e., on IM servers)
 +
<code>OssoABookAvatar</code> is implemented by <code>OssoABookContact</code>, so <code>OssoABookAvatar</code> functions are used directly upon <code>OssoABookContacts</code>.
-
OssoABookAvatar is implemented by OssoABookContact, so OssoABookAvatar functions are used directly upon OssoABookContacts.
+
==== Basic Example ====
-
 
+
-
=== Basic Example ===
+
The most important part of a contact's avatar is the image it contains, so this example focuses on that:
The most important part of a contact's avatar is the image it contains, so this example focuses on that:
-
<pre>
+
 
-
include <glib.h>
+
<source lang="c">
 +
#include <glib.h>
#include <libosso-abook/osso-abook.h>
#include <libosso-abook/osso-abook.h>
Line 87: Line 83:
         }
         }
}
}
-
</pre>
+
</source>
See the Additional API section for tips on caching avatar images.
See the Additional API section for tips on caching avatar images.
-
=== Additional API ===
+
==== 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:
+
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, <code>image_token</code> is a hashable value:
-
<pre>
+
<source lang="c">
gpointer image_token = osso_abook_avatar_get_image_token (OSSO_ABOOK_AVATAR (contact));
gpointer image_token = osso_abook_avatar_get_image_token (OSSO_ABOOK_AVATAR (contact));
-
</pre>
+
</source>
-
=== Notable Signals ===
+
==== Notable Signals ====
-
* notify::avatar-image
+
* <code>notify::avatar-image</code>
-
=== Complete API Documentation ===
+
==== Complete API Documentation ====
-
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/libosso-abook-osso-abook-avatar.html reference documentation for OssoABookAvatar].
+
-
== OssoABookCaps ==
+
Full details can be found in the API [http://maemo.org/api_refs/5.0/5.0-final/libosso-abook/libosso-abook-osso-abook-avatar.html reference documentation for OssoABookAvatar].
-
=== Overview ===
+
=== OssoABookCaps ===
-
OssoABookContacts may possess a number of different capabilities, so the OssoABookCaps interface (which OssoABookContacts implements) provides a simple means to detect these capabilities.
+
<code>OssoABookContacts</code> may possess a number of different capabilities, so the <code>OssoABookCaps</code> interface (which <code>OssoABookContacts</code> implements) provides a simple means to detect these capabilities.
-
=== Basic Example ===
+
==== 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:
+
The core of <code>OssoABookCaps</code> is the <code>OssoABookCapsFlags</code> enumeration, accessible by <code>osso_abook_caps_get_capabilities()</code>. Its values are orthogonal and may be bitwise-ORed or -ANDed together for more detailed capabilities checks:
-
<pre>
+
 
 +
<source lang="c">
static void
static void
contact_print_caps_details (OssoABookContact *contact)
contact_print_caps_details (OssoABookContact *contact)
Line 135: Line 131:
                 caps_flags & (OSSO_ABOOK_CAPS_PHONE | OSSO_ABOOK_CAPS_VOICE | OSSO_ABOOK_CAPS_VIDEO) ? "yes" : "no");
                 caps_flags & (OSSO_ABOOK_CAPS_PHONE | OSSO_ABOOK_CAPS_VOICE | OSSO_ABOOK_CAPS_VIDEO) ? "yes" : "no");
}
}
-
</pre>
+
</source>
-
=== Additional API ===
+
==== Additional API ====
-
OssoABookCaps also contains a convenience function for getting the capabilities of our own accounts (of type McAccount*).
+
<code>OssoABookCaps</code> also contains a convenience function for getting the capabilities of our own accounts (of type <code>McAccount*</code>).
-
<pre>
+
 
 +
<source lang="c">
OssoABookCapsFlags caps_flags = osso_abook_caps_from_account (account);
OssoABookCapsFlags caps_flags = osso_abook_caps_from_account (account);
-
</pre>
+
</source>
-
=== Notable Signals ===
+
==== Notable Signals ====
-
* notify::capabilities
+
* <code>notify::capabilities</code>
 +
 
 +
==== Complete API Documentation ====
-
=== Complete API Documentation ===
 
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/libosso-abook-osso-abook-caps.html reference documentation for OssoABookCaps].
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/libosso-abook-osso-abook-caps.html reference documentation for OssoABookCaps].
-
== OssoABookContact ==
+
=== OssoABookContact ===
-
=== Overview ===
+
The central class in libosso-abook is <code>OssoABookContact</code>, which is used in a few different ways:
-
 
+
-
The central class in libosso-abook is OssoABookContact, which is used in a few different ways:
+
* as a master contact, which acts as an authoritative source of contact attributes for itself and any number of roster contacts. This use is further broken into:
* as a master contact, which acts as an authoritative source of contact attributes for itself and any number of roster contacts. This use is further broken into:
Line 164: Line 160:
In most cases, you will only be interested in master contacts (in general) because they aggregate all of the attributes of their own and their roster contacts. Every master contact is the authoritative source of a person's displayable name, avatar, presence, status message, etc. If a master contact and its roster contact(s) have multiple values for a single-instance attribute (e.g., avatar), the master contact will automatically pick an authoritative value.
In most cases, you will only be interested in master contacts (in general) because they aggregate all of the attributes of their own and their roster contacts. Every master contact is the authoritative source of a person's displayable name, avatar, presence, status message, etc. If a master contact and its roster contact(s) have multiple values for a single-instance attribute (e.g., avatar), the master contact will automatically pick an authoritative value.
-
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).
+
So if you just wish to display all of your contacts' names and IM availability, you would simply use the appropriate <code>OssoABookContact</code> 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, <code>OssoABookContact</code> implements the <code>OssoABookAvatar</code>, <code>OssoABookCaps</code>, and <code>OssoABookPresence</code> interfaces. So <code>OssoABookContacts</code> can be used in their functions and will emit their signals. See their documentation for more details.
 +
 
 +
<code>OssoABookContact</code> inherits from <code>EContact</code> (which itself inherits from <code>EVCard</code>). At its core, <code>OssoABookContact</code> is based around the vCard format for storing contact attributes. We recommend against manipulating and accessing contacts at the vCard level, since it's more complicated and error-prone than using the <code>OssoABookContact</code> functionality. Note that the Maemo Address Book adds some vCard attributes (e.g., <code>gender/X-GENDER</code>, <code>Skype username/X-SKYPE</code>) that are not accessible at the EContact level, since they are not defined in <code>EContactField</code>. So we recommend using the <code>EVCard</code> functions over similar <code>EContact</code> functions whenever possible. See the <code>EContact</code> and <code>EVCard</code> documentation for more details on their API.
-
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.
+
As with any <code>EContact</code>, changes to an <code>OssoABookContact</code> are not permanently stored until they are explicitly committed. See the example and explanation of <code>osso_abook_contact_commit()</code> below.
-
OssoABookContact inherits from EContact (which itself inherits from EVCard). At its core, OssoABookContact is based around the vCard format for storing contact attributes. We recommend against manipulating and accessing contacts at the vCard level, since it's more complicated and error-prone than using the OssoABookContact functionality. Note that the Maemo Address Book adds some vCard attributes (e.g., gender/X-GENDER, Skype username/X-SKYPE) that are not accessible at the EContact level, since they are not defined in EContactField. So we recommend using the EVCard functions over similar EContact functions whenever possible. See the EContact and EVCard documentation for more details on their API.
+
==== Basic Examples ====
-
As with any EContact, changes to an OssoABookContact are not permanently stored until they are explicitly committed. See the example and explanation of osso_abook_contact_commit() below.
+
===== Printing out basic contact details =====
-
=== Basic Examples ===
+
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 <code>OssoABookAvatar</code>; for its IM presence or capabilities, see <code>OssoABookPresence</code> and <code>OssoABookCaps</code>.
-
==== Printing out basic contact details ====
+
Also note that, for most cases of displaying an avatar, presence icon, etc., libosso-abook provides widgets. See <code>OssoABookAvatarImage</code>, <code>OssoABookPresenceIcon</code>, and <code>OssoABookTouchContactStarter</code>.
-
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.
+
-
Also note that, for most cases of displaying an avatar, presence icon, etc., libosso-abook provides widgets. See OssoABookAvatarImage, OssoABookPresenceIcon, and OssoABookTouchContactStarter.
+
<source lang="c">
-
<pre>
+
#include <glib.h>
#include <glib.h>
#include <libosso-abook/osso-abook.h>
#include <libosso-abook/osso-abook.h>
Line 201: Line 199:
                 osso_abook_contact_is_sim_contact (contact)      ? "yes" : "no");
                 osso_abook_contact_is_sim_contact (contact)      ? "yes" : "no");
}
}
-
</pre>
+
</source>
-
=== Additional API ===
+
==== 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.
+
There are many ways to use an <code>OssoABookContact</code>, and a significant portion of that lay in its parent classes and implemented interfaces (<code>OssoABookAvatar</code>, <code>OssoABookCaps</code>, and <code>OssoABookPresence</code>). See the appropriate documentation for more details.
-
Here are some highlights of additional API for OssoABookContact.
+
Here are some highlights of additional API for <code>OssoABookContact</code>.
-
==== General Functions ====
+
===== 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).
+
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 <code>TRUE</code> if you wish to include the contact's avatar data (this can be very long).
-
<pre>
+
<source lang="c">
osso_abook_contact_to_string (contact, EVC_FORMAT_VCARD_30, FALSE);
osso_abook_contact_to_string (contact, EVC_FORMAT_VCARD_30, FALSE);
-
</pre>
+
</source>
-
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:
+
In case you need to sort some contacts, <code>osso_abook_contact_collate()</code> is a <code>strcmp()</code>-like function that does just that. So, to sort a <code>GList</code> of contacts:
-
<pre>
+
<source lang="c">
/* To sort by presence, use OSSO_ABOOK_CONTACT_ORDER_PRESENCE instead */
/* To sort by presence, use OSSO_ABOOK_CONTACT_ORDER_PRESENCE instead */
g_list_sort_with_data (contacts, osso_abook_contact_collate, OSSO_ABOOK_CONTACT_ORDER_NAME);
g_list_sort_with_data (contacts, osso_abook_contact_collate, OSSO_ABOOK_CONTACT_ORDER_NAME);
-
</pre>
+
</source>
-
 
+
===== Roster Contact List Handling =====
-
==== Roster Contact List Handling ====
+
In case you need to access a master contact's roster contacts, you can do so like this:
In case you need to access a master contact's roster contacts, you can do so like this:
-
<pre>
+
<source lang="c">
#include <libosso-abook/osso-abook.h>
#include <libosso-abook/osso-abook.h>
Line 246: Line 243:
         g_list_free (contacts);
         g_list_free (contacts);
}
}
-
</pre>
+
</source>
-
==== Roster Contacts ====
+
===== Roster Contacts =====
There are a number of useful functions for accessing roster contact details. This example shows off the basic ones:
There are a number of useful functions for accessing roster contact details. This example shows off the basic ones:
-
<pre>
+
 
 +
<source lang="c">
#include <glib.h>
#include <glib.h>
#include <libosso-abook/osso-abook.h>
#include <libosso-abook/osso-abook.h>
Line 274: Line 272:
                 osso_abook_contact_has_invalid_username (contact) ?  "yes" : "no");                     
                 osso_abook_contact_has_invalid_username (contact) ?  "yes" : "no");                     
}
}
-
</pre>
+
</source>
-
==== Attribute Convenience Functions ====
+
===== Attribute Convenience Functions =====
If you need a hashable key (to temporarily use) for contacts, use:
If you need a hashable key (to temporarily use) for contacts, use:
-
<pre>
+
<source lang="c">
const char *key = osso_abook_contact_get_uid (contact);
const char *key = osso_abook_contact_get_uid (contact);
-
</pre>
+
</source>
However, if you need a persistent hashable key (such as for an on-disk cache, database, etc.), use the following function:
However, if you need a persistent hashable key (such as for an on-disk cache, database, etc.), use the following function:
-
<pre>
+
<source lang="c">
const char *key = osso_abook_contact_get_persistent_uid (contact);
const char *key = osso_abook_contact_get_persistent_uid (contact);
Line 292: Line 290:
         g_print ("This contact isn't persistent!");
         g_print ("This contact isn't persistent!");
}
}
-
</pre>
+
</source>
Sometimes it can be useful to add vCard attributes to a contact for custom applications. Say you have a networked game called Foo Bar Tetris, and you want to associate someone's username on the network with their contact:
Sometimes it can be useful to add vCard attributes to a contact for custom applications. Say you have a networked game called Foo Bar Tetris, and you want to associate someone's username on the network with their contact:
-
<pre>
+
<source lang="c">
#include <glib.h>
#include <glib.h>
#include <libosso-abook/osso-abook.h>
#include <libosso-abook/osso-abook.h>
Line 320: Line 318:
         g_free (current_username);
         g_free (current_username);
}
}
-
</pre>
+
</source>
-
=== Notable Signals ===
+
==== Notable Signals ====
-
* reset
+
* <code>reset</code>
-
* contact-attached
+
* <code>contact-attached</code>
-
* contact-detached
+
* <code>contact-detached</code>
-
=== Complete API Documentation ===
+
==== 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].
+
Full details can be found in the API [http://maemo.org/api_refs/5.0/5.0-final/libosso-abook/OssoABookContact.html reference documentation for OssoABookContact].
-
== OssoABookPresence ==
+
=== OssoABookPresence ===
-
 
+
-
=== Overview ===
+
A contact's "presence" is comprised of a few elements, including:
A contact's "presence" is comprised of a few elements, including:
;status
;status
-
: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.  
+
: 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.  
;status message
;status message
-
:the string set by your contact (e.g., "I'm running outside")
+
: the string set by your contact (e.g., "I'm running outside")
;type
;type
-
: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 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 <code>OssoABookContact</code> 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".
-
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".
+
<code>OssoABookPresence</code> is implemented by <code>OssoABookContact</code>, so <code>OssoABookPresence</code> functions are used directly upon <code>OssoABookContacts</code>.
-
OssoABookPresence is implemented by OssoABookContact, so OssoABookPresence functions are used directly upon OssoABookContacts.
+
==== Basic Example ====
-
=== Basic Example ===
+
This example shows off some of the more useful basic functions in <code>OssoABookPresence</code>. Note that you will always be using <code>OssoABookPresence</code> functions on <code>OssoABookContacts</code>, since they're the only class that implements the interface.
-
This example shows off some of the more useful basic functions in OssoABookPresence. Note that you will always be using OssoABookPresence functions on OssoABookContacts, since they're the only class that implements the interface.
+
<source lang="c">
-
<pre>
+
#include <glib.h>
#include <glib.h>
#include <telepathy-glib/connection.h>
#include <telepathy-glib/connection.h>
Line 421: Line 418:
                 osso_abook_presence_state_get_nick (osso_abook_presence_get_subscribed (presence)));
                 osso_abook_presence_state_get_nick (osso_abook_presence_get_subscribed (presence)));
}
}
-
</pre>
+
</source>
-
=== Additional API ===
+
==== 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.
+
The example above shows how to compare the basic <code>TpConnectionPresenceType</code> return value of <code>osso_abook_presence_get_presence_type()</code>. At a higher level, if you want to compare the relative availability of two <code>OssoABookPresences</code> (e.g., <code>OssoABookContacts</code>), you can use the convenience function <code>osso_abook_presence_compare()</code>. It works like most <code>strcmp()</code>-like functions, except that it returns a value < 0 is the first presence is more online than the other, and vice versa.
-
<pre>
+
 
 +
<source lang="c">
/* Sort the contacts in order of decreasing availability */
/* Sort the contacts in order of decreasing availability */
contacts = g_list_sort (contacts, (GCompareFunc) osso_abook_presence_compare);
contacts = g_list_sort (contacts, (GCompareFunc) osso_abook_presence_compare);
-
</pre>
+
</source>
-
=== Notable Signals ===
+
==== Notable Signals ====
-
* notify::presence-location-string
+
* <code>notify::presence-location-string</code>
-
* notify::presence-status
+
* <code>notify::presence-status</code>
-
* notify::presence-status-message
+
* <code>notify::presence-status-message</code>
-
* notify::presence-type
+
* <code>notify::presence-type</code>
-
=== Complete API Documentation ===
+
==== Complete API Documentation ====
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/libosso-abook-osso-abook-presence.html reference documentation for OssoABookPresence].
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/libosso-abook-osso-abook-presence.html reference documentation for OssoABookPresence].
-
= Widget Classes =
+
== Widget Classes ==
-
== OssoABookContactChooser ==
+
=== OssoABookContactChooser ===
-
=== Overview ===
+
<code>OssoABookContactChooser</code> 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
-
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
+
can be used in many different situations.   
can be used in many different situations.   
-
=== Basic Example ===
+
==== Basic Example ====
-
The following is a simple example of the use of OssoABookContactChooser:
+
 
 +
The following is a simple example of the use of <code>OssoABookContactChooser</code>:
-
<pre>
+
<source lang="c">
static void
static void
test_contact_chooser (void)
test_contact_chooser (void)
Line 480: Line 477:
                 GList *l;
                 GList *l;
-
                 g_printf ("Selected Contacts:\n")
+
                 g_printf ("Selected Contacts:\n");
                 for (l = selection; l; l = l->next) {
                 for (l = selection; l; l = l->next) {
-
                         g_printf ("%s\n", osso_abook_contact_get_display_name((l->data));
+
                         g_printf ("%s\n", osso_abook_contact_get_display_name(l->data));
                 }
                 }
         } else {
         } else {
Line 493: Line 490:
         gtk_widget_destroy (chooser);
         gtk_widget_destroy (chooser);
}
}
-
</pre>
+
</source>
-
=== Additional API ===
+
==== Additional API ====
The contacts shown in the list can be customized in several ways.
The contacts shown in the list can be customized in several ways.
-
osso_abook_contact_chooser_set_capabilities() allows you to limit the contacts
+
<code>osso_abook_contact_chooser_set_capabilities()</code> allows you to limit the contacts shown in the list to only those that have certain capabilities. For example, to
-
shown in the list to only those that have certain capabilities. For example, to
+
show only those contacts that have an associated email address:
show only those contacts that have an associated email address:
-
<pre>
+
<source lang="c">
osso_abook_contact_chooser_set_capabilities (chooser, OSSO_ABOOK_CAPS_EMAIL);
osso_abook_contact_chooser_set_capabilities (chooser, OSSO_ABOOK_CAPS_EMAIL);
-
</pre>
+
</source>
You can show only those contacts whose presence status indicates that they are
You can show only those contacts whose presence status indicates that they are
Line 511: Line 507:
contact over a messaging protocol:
contact over a messaging protocol:
-
<pre>
+
<source lang="c">
osso_abook_contact_chooser_set_hide_offline_contacts (chooser, TRUE);
osso_abook_contact_chooser_set_hide_offline_contacts (chooser, TRUE);
-
</pre>
+
</source>
If there are specific contacts that you wish to exclude from the chooser, you
If there are specific contacts that you wish to exclude from the chooser, you
Line 520: Line 516:
that are already present in the "To:" field.
that are already present in the "To:" field.
-
<pre>
+
<source lang="c">
OssoABookContact *john_doe; /* reference to a contact from the addressbook */
OssoABookContact *john_doe; /* reference to a contact from the addressbook */
Line 526: Line 522:
contacts = g_list_prepend (contacts, john_doe);
contacts = g_list_prepend (contacts, john_doe);
osso_abook_contact_chooser_set_excluded_contacts (chooser, contacts);
osso_abook_contact_chooser_set_excluded_contacts (chooser, contacts);
-
</pre>
+
</source>
If an application needs even more control,
If an application needs even more control,
-
osso_abook_contact_chooser_set_visible_func() provides a way for the application
+
<code>osso_abook_contact_chooser_set_visible_func()</code> provides a way for the application to supply a predicate function that will determine whether the contact should be
-
to supply a predicate function that will determine whether the contact should be
+
shown in the chooser.
shown in the chooser.
-
<pre>
+
<source lang="c">
gboolean custom_visible_func(OssoABookContactChooser *chooser,
gboolean custom_visible_func(OssoABookContactChooser *chooser,
                             OssoABookContact *contact,
                             OssoABookContact *contact,
Line 551: Line 546:
osso_abook_contact_chooser_set_visible_func (chooser, custom_visible_func,
osso_abook_contact_chooser_set_visible_func (chooser, custom_visible_func,
                                             "foo", NULL);
                                             "foo", NULL);
-
</pre>
+
</source>
In addition to the ability to customize the contacts that are shown in the
In addition to the ability to customize the contacts that are shown in the
Line 559: Line 554:
functions to programmatically select and deselect items from the list.
functions to programmatically select and deselect items from the list.
-
=== Complete API Documentation ===
+
==== Complete API Documentation ====
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/OssoABookContactChooser.html reference documentation for OssoABookContactChooser].
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/OssoABookContactChooser.html reference documentation for OssoABookContactChooser].
-
== OssoABookTreeView ==
+
=== OssoABookTreeView ===
-
=== Overview ===
+
Although <code>OssoABookTreeView</code>'s name might imply that it inherits from <code>GtkTreeView</code>, it is actually an ancestor of <code>GtkVBox</code> that contains a <code>GtkTreeView</code> inside of a <code>HildonPannableArea</code>. It provides a convenient way to display a list of contacts and sets up the <code>GtkTreeView</code> columns automatically. It can show the contacts' name, Telephone number, presence status, and avatar image. These details can be
-
 
+
-
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
+
selectively enabled or disabled according to an application's requirements.
selectively enabled or disabled according to an application's requirements.
It is unlikely that an application will need or want to instantiate an
It is unlikely that an application will need or want to instantiate an
-
OssoABookTreeView object directly. Most of the time, applications will deal
+
<code>OssoABookTreeView</code> object directly. Most of the time, applications will deal
-
with OssoABookContactView objects, which inherits from this class and does most
+
with <code>OssoABookContactView</code> objects, which inherits from this class and does most of the setup work for you.
-
of the setup work for you.
+
-
=== Additional API ===
+
==== Additional API ====
-
OssoABookTreeView is an aggregate widget, but it provides direct access to the
+
<code>OssoABookTreeView</code> is an aggregate widget, but it provides direct access to the underlying widgets as well (e.g. <code>osso_abook_tree_view_get_tree_view()</code>,
-
underlying widgets as well (e.g. osso_abook_tree_view_get_tree_view(),
+
<code>osso_abook_tree_view_get_pannable_area()</code>.
-
osso_abook_tree_view_get_pannable_area().
+
An application can filter the list of contacts that gets displayed in the tree
An application can filter the list of contacts that gets displayed in the tree
-
view by using osso_abook_tree_view_set_filter_model().  The following example
+
view by using <code>osso_abook_tree_view_set_filter_model()</code>.  The following example shows how to display only those contacts whose names contain a certain string:
-
shows how to display only those contacts whose names contain a certain string:
+
-
<pre>
+
<source lang="c">
OssoABookTreeView *view;
OssoABookTreeView *view;
OssoABookListStore *base_model;
OssoABookListStore *base_model;
Line 603: Line 589:
osso_abook_tree_view_set_base_model (view, base_model);
osso_abook_tree_view_set_base_model (view, base_model);
osso_abook_tree_view_set_filter_model (view, filter_model);
osso_abook_tree_view_set_filter_model (view, filter_model);
-
</pre>
+
</source>
-
In addition, if you only want to display those contacts associated with a
+
In addition, if you only want to display those contacts associated with a particular VoIP or IM account, use the function
-
particular VoIP or IM account, use the function
+
<code>osso_abook_tree_view_set_aggregation_account()</code>.  In addition to limiting the contacts to only those specified by those accounts, it will also display the
-
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
+
presence status and avatar image for that particular account regardless of the
presence status and avatar image for that particular account regardless of the
contact's status on other VoIP or IM accounts.
contact's status on other VoIP or IM accounts.
Line 614: Line 598:
The details shown in the tree view can be controlled with the following
The details shown in the tree view can be controlled with the following
properties:
properties:
-
* show-contact-avatar
+
* <code>show-contact-avatar</code>
-
* show-contact-name
+
* <code>show-contact-name</code>
-
* show-contact-presence
+
* <code>show-contact-presence</code>
-
* show-contact-telephone
+
* <code>show-contact-telephone</code>
-
=== Complete API Documentation ===
+
==== Complete API Documentation ====
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/OssoABookTreeView.html reference documentation for OssoABookTreeView].
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/OssoABookTreeView.html reference documentation for OssoABookTreeView].
-
== OssoABookContactView ==
+
=== OssoABookContactView ===
-
=== Overview ===
+
<code>OssoABookContactView</code> provides a convenient widget for displaying a list of
-
 
+
contacts in a list. It builds upon <code>OssoABookTreeView</code> and adds a bit of
-
OssoABookContactView provides a convenient widget for displaying a list of
+
-
contacts in a list. It builds upon OssoABookTreeView and adds a bit of
+
convenience API.
convenience API.
-
=== Basic Example ===
+
==== Basic Example ====
The following example shows how to display all contacts from the Address Book in
The following example shows how to display all contacts from the Address Book in
a list.
a list.
-
<pre>
+
<source lang="c">
#include <libosso-abook/osso-abook.h>
#include <libosso-abook/osso-abook.h>
Line 660: Line 642:
         gtk_main ();
         gtk_main ();
}
}
-
</pre>
+
</source>
-
=== Additional API ===
+
==== Additional API ====
-
OssoABookContactView has some additional convenience API that allows you to get
+
<code>OssoABookContactView</code> has some additional convenience API that allows you to get the contact (or properties of the contact) that currently has input focus:
-
the contact (or properties of the contact) that currently has input focus:
+
* <code>osso_abook_contact_view_get_focus()</code>
-
* osso_abook_contact_view_get_focus()
+
* <code>osso_abook_contact_view_get_focus_avatar()</code>
-
* osso_abook_contact_view_get_focus_avatar()
+
* <code>osso_abook_contact_view_get_focus_presence()</code>
-
* osso_abook_contact_view_get_focus_presence()
+
* <code>osso_abook_contact_view_get_focus_caps()</code>
-
* osso_abook_contact_view_get_focus_caps()
+
The Contact view can support both single- and multiple-selection modes.
The Contact view can support both single- and multiple-selection modes.
-
osso_abook_contact_view_set_minimum_selection() and
+
<code>osso_abook_contact_view_set_minimum_selection()</code> and
-
osso_abook_contact_view_set_maximum_selection() allow fine-grained control over
+
<code>osso_abook_contact_view_set_maximum_selection()</code> allow fine-grained control over how contacts can be selected.
-
how contacts can be selected.
+
-
=== Complete API Documentation ===
+
==== Complete API Documentation ====
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/OssoABookContactView.html reference documentation for OssoABookContactView].
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/OssoABookContactView.html reference documentation for OssoABookContactView].
-
== OssoABookTouchContactStarter ==
+
=== OssoABookTouchContactStarter ===
-
=== Overview ===
+
<code>OssoABookTouchContactStarter</code> is a widget that displays the information for a contact and can be used to initiate communication with a contact (email, IM,
-
OssoABookTouchContactStarter is a widget that displays the information for a
+
-
contact and can be used to initiate communication with a contact (email, IM,
+
VoIP, etc).
VoIP, etc).
-
=== Basic Example ===
+
==== Basic Example ====
The following is a simple example that shows how to use
The following is a simple example that shows how to use
-
OssoABookTouchContactStarter to display the details of a particular contact.
+
<code>OssoABookTouchContactStarter</code> to display the details of a particular contact.
-
<pre>
+
<source lang="c">
#include <libosso-abook/osso-abook.h>
#include <libosso-abook/osso-abook.h>
Line 728: Line 706:
         return 0;
         return 0;
}
}
-
</pre>
+
</source>
 +
 
 +
==== Additional API ====
-
=== Additional API ===
 
In addition to the basic example shown above, there are several other ways to
In addition to the basic example shown above, there are several other ways to
-
customize the OssoABookTouchContactStarter widget.  By default the contact
+
customize the <code>OssoABookTouchContactStarter</code> widget.  By default the contact starter is created in 'read-only' mode.  But if the starter was created with
-
starter is created in 'read-only' mode.  But if the starter was created with
+
<code>osso_abook_touch_contact_starter_new_with_editor()</code>, a contact editor can be launched by clicking the avatar icon. This allows the contact's details to be
-
osso_abook_touch_contact_starter_new_with_editor(), a contact editor can be
+
changed directly from the contact starter widget. An editor can also be
-
launched by clicking the avatar icon. This allows the contact's details to be
+
launched programmatically by calling <code>osso_abook_touch_contact_starter_start_editor()</code>.
-
changed directly from the contact starter widget. An editor can also be
+
-
launched programmatically by calling
+
-
osso_abook_touch_contact_starter_start_editor().
+
A contact starter is normally interactive in the sense that it can be used to
A contact starter is normally interactive in the sense that it can be used to
initiate contact with the contact (e.g. start a phone call, start a chat, etc),
initiate contact with the contact (e.g. start a phone call, start a chat, etc),
though it can be made non-interactive by creating the starter with
though it can be made non-interactive by creating the starter with
-
osso_abook_touch_contact_starter_new_not_interactive().  In addition, an
+
<code>osso_abook_touch_contact_starter_new_not_interactive()</code>.  In addition, an
-
application can override the default actions by connecting to the
+
application can override the default actions by connecting to the <code>pre-action-start</code> signal.  For example:
-
"pre-action-start" signal.  For example:
+
-
<pre>
+
<source lang="c">
gboolean
gboolean
pre_action_start_cb (OssoABookTouchContactStarter *starter,
pre_action_start_cb (OssoABookTouchContactStarter *starter,
Line 773: Line 748:
                                 G_CALLBACK (pre_action_start_cb), NULL);
                                 G_CALLBACK (pre_action_start_cb), NULL);
-
</pre>
+
</source>
-
=== Complete API Documentation ===
+
==== Complete API Documentation ====
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/OssoABookTouchContactStarter.html reference documentation for OssoABookTouchContactStarter].
Full details can be found in the API [http://maemo.org/api_refs/5.0/beta/libosso-abook/OssoABookTouchContactStarter.html reference documentation for OssoABookTouchContactStarter].
-
= Glossary =
+
== Glossary ==
;aggregated contact
;aggregated contact
-
:a persistent master contact with one or more attached roster contacts.
+
: a persistent master contact with one or more attached roster contacts.
;aggregator
;aggregator
-
:an OssoABookAggregator object which manages connections to the EDS backends and associates master contacts with their roster contacts.
+
: an <code>OssoABookAggregator</code> object which manages connections to the EDS backends and associates master contacts with their roster contacts.
;master contact
;master contact
-
:an OssoABookContact which aggregates the attributes of zero or one persistent master contacts and zero or more roster contacts.
+
: an <code>OssoABookContact</code> which aggregates the attributes of zero or one persistent master contacts and zero or more roster contacts.
;persistent master contact
;persistent master contact
-
:an OssoABookContact which is stored in the EDS local database and has zero or more roster contacts.
+
: an <code>OssoABookContact</code> which is stored in the EDS local database and has zero or more roster contacts.
;roster contact
;roster contact
-
: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.
+
: an <code>OssoABookContact</code> 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.
;temporary master contact
;temporary master contact
-
: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 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.
;unique identifier (UID)
;unique identifier (UID)
-
:a hashable ID which is unique across all EDS back-ends. See the definition for "temporary master contact" for relevant usage warnings.
+
: a hashable ID which is unique across all EDS back-ends. See the definition for "temporary master contact" for relevant usage warnings.
 +
 
 +
[[Category:Development]]
 +
[[Category:Documentation]]
 +
[[Category:Fremantle]]

Latest revision as of 07:40, 27 October 2012

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 with 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.

This allows Contacts and your application to automatically add IM contacts to your account when adding an IM username to a contact or add a dialog to initiate phone calls, VoIP calls, text messages, emails, or chats with a single tap, and much more.

This tutorial is focused on using Address Book functionality within third-party applications. It does not cover all classes nor does it cover any classes exhaustively. For information on the classes, see the reference documentation.

Contents

[edit] Components

The main components in the Maemo Address Book stack are the Contacts application (osso-addressbook), support library (libosso-abook), and Evolution Data Server.

Diagram of address book components
Address book components

[edit] The Contacts application (osso-addressbook)

As you might expect, the Contacts application provides a convenient user interface for manipulating the contacts in the Maemo 5 system. And by design, nearly all the functionality within Contacts (including widgets) is actually located within libosso-abook, so that it can be reused by other applications (such as Phone and Conversations, or your own).

Since this document is intended to be a quick introduction to libosso-abook for developers who would like to include address book functionality in their application, we will not cover Contacts in detail.

[edit] libosso-abook

The libosso-abook library is the highest-level entry point into the address book contents and implements most of the functionality exposed by osso-addressbook. Its main tasks are:

  1. Aggregate "plain" contacts with any associated chat ("roster") contacts
  2. Determine which attribute values to present for aggregated contacts in case of conflict
  3. Handle adding, removing, and editing contacts stored in the different Evolution Data Server back-ends
  4. Provide a number of high-level widgets for adding contacts, presenting contact avatars and online presence, and more
  5. Support intelligently merging contacts and their fields

[edit] Evolution Data Server

Evolution Data Server (EDS) is a software stack that performs most basic addressbook functionality (including storing contacts, calendar events, and so on). In Maemo 5, EDS is used to store contacts which are presented to applications via libosso-abook.

EDS supports multiple back-ends for storing and retrieving contacts from multiple sources. Normally, EDS uses the "file" backend, which simply stores contacts as vCards in the local database. New in Maemo 5, EDS adds the SIM and Telepathy backends for accessing contacts stored on a SIM card and on chat rosters.

The back-ends all provide slightly different functionality, but libosso-abook abstracts them to appear as a single, coherent contact store.

[edit] libebook

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.

[edit] Contacts Home Applet (osso-abook-home-applet)

In order to minimize the number of taps required to contact your favorite contacts, Contacts provides a way to add shortcuts to specific contacts on your home views. The Contacts Home Applet is the process that draws these shortcuts on the home view.

[edit] Non-Widget Classes

[edit] OssoABookAvatar

Contacts may have an associated image, called their "avatar". An avatar may be retrieved from a corresponding contact on an IM account or from a user-set local image.

Master contacts select their avatar image in order of priority:

  1. Any user-set image
  2. The most-recently-changed avatar amongst all attached roster contacts (i.e., on IM servers)

OssoABookAvatar is implemented by OssoABookContact, so OssoABookAvatar functions are used directly upon OssoABookContacts.

[edit] Basic Example

The most important part of a contact's avatar is the image it contains, so this example focuses on that:

#include <glib.h>
#include <libosso-abook/osso-abook.h>
 
static void
avatar_save_image_to_file (OssoABookContact *contact,
                           const char       *filename)
{
        OssoABookAvatar *avatar = OSSO_ABOOK_AVATAR (contact);
        /* To get the image in a different size, use osso_abook_avatar_get_image_scaled() (this may affect image quality) */
        GdkPixbuf *pixbuf = osso_abook_avatar_get_image (avatar);
 
        if (pixbuf) {
                /* In a real application, you would do more careful error checking here */
                if (gdk_pixbuf_save (pixbuf, filename, "png", NULL, NULL)) {
                        g_warning ("failed to save the avatar image '%s'", filename);
                }
        } else {
                g_warning ("no avatar image to save");
        }
}

See the Additional API section for tips on caching avatar images.

[edit] 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:

gpointer image_token = osso_abook_avatar_get_image_token (OSSO_ABOOK_AVATAR (contact));

[edit] Notable Signals

  • notify::avatar-image

[edit] Complete API Documentation

Full details can be found in the API reference documentation for OssoABookAvatar.

[edit] OssoABookCaps

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

[edit] 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:

static void
contact_print_caps_details (OssoABookContact *contact)
{
        OssoABookCaps *caps = OSSO_ABOOK_CAPS (contact);
        OssoABookCapsFlags caps_flags = osso_abook_caps_get_capabilities (caps);
 
        g_print ("   Can receive email?: %s\n"
                 "   Can chat?: %s\n"
                 "   Can receive phone calls?: %s\n"
                 "   Can receive multimedia voice calls?: %s\n"
                 "   Can receive multimedia video calls?: %s\n"
                 "   Can receive calls of some type?: %s\n"
                 "\n",
                 caps_flags & OSSO_ABOOK_CAPS_EMAIL ? "yes" : "no",
                 caps_flags & OSSO_ABOOK_CAPS_CHAT  ? "yes" : "no",
                 caps_flags & OSSO_ABOOK_CAPS_PHONE ? "yes" : "no",
                 caps_flags & OSSO_ABOOK_CAPS_VOICE ? "yes" : "no",
                 caps_flags & OSSO_ABOOK_CAPS_VIDEO ? "yes" : "no",
                 caps_flags & (OSSO_ABOOK_CAPS_PHONE | OSSO_ABOOK_CAPS_VOICE | OSSO_ABOOK_CAPS_VIDEO) ? "yes" : "no");
}

[edit] Additional API

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

OssoABookCapsFlags caps_flags = osso_abook_caps_from_account (account);

[edit] Notable Signals

  • notify::capabilities

[edit] Complete API Documentation

Full details can be found in the API reference documentation for OssoABookCaps.

[edit] OssoABookContact

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

  • as a master contact, which acts as an authoritative source of contact attributes for itself and any number of roster contacts. This use is further broken into:
    • a persistent master contact, which is stored locally and may have zero or more attached roster contacts; OR:
    • a temporary master contact, which is not stored at all and serves as a "placeholder" master for roster contacts which exist on the VoIP/IM server but whose username is not an attribute of a persistent master contact
  • as a roster contact, which corresponds to exactly one (VoIP/IM username, VoIP/IM account) pair. All roster contacts are attached to one or more master contacts, and their details are cached locally but not stored in persistent master contact database

In most cases, you will only be interested in master contacts (in general) because they aggregate all of the attributes of their own and their roster contacts. Every master contact is the authoritative source of a person's displayable name, avatar, presence, status message, etc. If a master contact and its roster contact(s) have multiple values for a single-instance attribute (e.g., avatar), the master contact will automatically pick an authoritative value.

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.

OssoABookContact inherits from EContact (which itself inherits from EVCard). At its core, OssoABookContact is based around the vCard format for storing contact attributes. We recommend against manipulating and accessing contacts at the vCard level, since it's more complicated and error-prone than using the OssoABookContact functionality. Note that the Maemo Address Book adds some vCard attributes (e.g., gender/X-GENDER, Skype username/X-SKYPE) that are not accessible at the EContact level, since they are not defined in EContactField. So we recommend using the EVCard functions over similar EContact functions whenever possible. See the EContact and EVCard documentation for more details on their API.

As with any EContact, changes to an OssoABookContact are not permanently stored until they are explicitly committed. See the example and explanation of osso_abook_contact_commit() below.

[edit] Basic Examples

[edit] Printing out basic contact 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.

Also note that, for most cases of displaying an avatar, presence icon, etc., libosso-abook provides widgets. See OssoABookAvatarImage, OssoABookPresenceIcon, and OssoABookTouchContactStarter.

#include <glib.h>
#include <libosso-abook/osso-abook.h>
 
static void
contact_print_details (OssoABookContact *contact)
{
        g_print ("   UID: %s\n"
                 "   Name: %s\n"
                 "   Is a roster contact?: %s\n"
                 "   Is a master contact?: %s\n"
                 "   Has roster contacts?: %s\n"
                 "   Is a temporary (master) contact?: %s\n"
                 "   Is a SIM contact?: %s\n"
                 "\n",
                 osso_abook_contact_get_uid (contact),
                 osso_abook_contact_get_display_name (contact),
                 osso_abook_contact_is_roster_contact (contact)   ? "yes" : "no",
                 osso_abook_contact_is_roster_contact (contact)   ? "no"  : "yes",
                 osso_abook_contact_has_roster_contacts (contact) ? "yes" : "no",
                 osso_abook_contact_is_temporary (contact)        ? "yes" : "no",
                 osso_abook_contact_is_sim_contact (contact)      ? "yes" : "no");
}

[edit] 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.

[edit] 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).

osso_abook_contact_to_string (contact, EVC_FORMAT_VCARD_30, FALSE);

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:

/* To sort by presence, use OSSO_ABOOK_CONTACT_ORDER_PRESENCE instead */
g_list_sort_with_data (contacts, osso_abook_contact_collate, OSSO_ABOOK_CONTACT_ORDER_NAME);
[edit] Roster Contact List Handling

In case you need to access a master contact's roster contacts, you can do so like this:

#include <libosso-abook/osso-abook.h>
 
/* Ensure that we're getting the roster contacts for a master contact */
if (!osso_abook_contact_is_roster_contact (contact)) {
        GList *contacts;
 
        contacts = osso_abook_contact_get_roster_contacts (contact);
 
        /* Do something with the contacts without altering the list */
        /*
        ...
        */
 
        /* Don't forget to free the list */
        g_list_free (contacts);
}
[edit] Roster Contacts

There are a number of useful functions for accessing roster contact details. This example shows off the basic ones:

#include <glib.h>
#include <libosso-abook/osso-abook.h>
 
static void
roster_contact_print_details (OssoABookContact *contact)
{
        g_print ("      UID: %s\n"
                 "      Name: %s\n"
                 "      McAccount: %p\n"
                 "      McProfile: %p\n"
                 "      vCard field: %s\n"
                 "      Bound name: %s\n"
                 "      Has an invalid username: %s\n"
                 "\n",
                 osso_abook_contact_get_uid (contact),
                 osso_abook_contact_get_display_name (contact),
                 osso_abook_contact_get_account (contact),
                 osso_abook_contact_get_profile (contact),
                 osso_abook_contact_get_vcard_field (contact),
                 osso_abook_contact_get_bound_name (contact),
                 osso_abook_contact_has_invalid_username (contact) ?  "yes" : "no");                    
}
[edit] Attribute Convenience Functions

If you need a hashable key (to temporarily use) for contacts, use:

const char *key = osso_abook_contact_get_uid (contact);

However, if you need a persistent hashable key (such as for an on-disk cache, database, etc.), use the following function:

const char *key = osso_abook_contact_get_persistent_uid (contact);
 
if (!key) {
        g_print ("This contact isn't persistent!");
}

Sometimes it can be useful to add vCard attributes to a contact for custom applications. Say you have a networked game called Foo Bar Tetris, and you want to associate someone's username on the network with their contact:

#include <glib.h>
#include <libosso-abook/osso-abook.h>
 
/* By convention, any arbitrary vCard files not in the specification should begin with "X-" */
#define VCARD_FIELD_USERNAME "X-FOO-BAR-TETRIS-USERNAME"
 
/* Pass in NULL for username to simply remove the attribute */
static void
contact_set_game_username (OssoABookContact *contact,
                           const char       *username)
{
        char *current_username;
 
        /* Cast contact to EContact since this function takes an EContact argument */
        current_username = osso_abook_contact_get_value (E_CONTACT (contact), VCARD_FIELD_USERNAME);
 
        g_print ("current username: %s", current_username);
 
        /* Set the new value; if there already were value(s), they will be removed before adding this new one */
        osso_abook_contact_set_value (E_CONTACT (contact), VCARD_FIELD_USERNAME, username);
 
        g_free (current_username);
}

[edit] Notable Signals

  • reset
  • contact-attached
  • contact-detached

[edit] Complete API Documentation

Full details can be found in the API reference documentation for OssoABookContact.

[edit] OssoABookPresence

A contact's "presence" is comprised of a few elements, including:

status
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.
status message
the string set by your contact (e.g., "I'm running outside")
type
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".

OssoABookPresence is implemented by OssoABookContact, so OssoABookPresence functions are used directly upon OssoABookContacts.

[edit] Basic Example

This example shows off some of the more useful basic functions in OssoABookPresence. Note that you will always be using OssoABookPresence functions on OssoABookContacts, since they're the only class that implements the interface.

#include <glib.h>
#include <telepathy-glib/connection.h>
#include <libosso-abook/osso-abook.h>
 
static void
self_account_print_details (McAccount *account)
{
        const char *current_status;
        const char *current_message;
        const char *requested_status;
        const char *requested_message;
 
        mc_account_get_current_presence (account, NULL, &current_status, &current_message);
        mc_account_get_requested_presence (account, NULL, &requested_status, &requested_message);
 
        g_print ("   Normalized name (unique ID): %s\n"
                 "   Display name: %s\n"
                 "   Has been online?: %s\n"
                 "   Current presence:\n"
                 "      status:  %s\n"
                 "      message: %s\n"
                 "   Requested presence:\n"
                 "      status:  %s\n"
                 "      message: %s\n"
                 "\n",
                 account->name,
                 mc_account_get_display_name (account),
                 mc_account_has_been_online (account) ? "yes" : "no",
                 current_status,
                 current_message,
                 requested_status,
                 requested_message);
}
 
static void
contact_print_presence_details (OssoABookContact *contact)
{
        OssoABookPresence *presence = OSSO_ABOOK_PRESENCE (contact);
        TpConnectionPresenceType type;
 
        type = osso_abook_presence_get_presence_type (presence);
 
        g_print ("   Contact name: %s\n"
                 "   Status type: %d\n"
                 "   Is online?: %s\n"
                 "   Status: %s\n"
                 "   Display Status: %s\n"
                 "   Status Message: %s\n"
                 "   Location: %s\n"
                 "   Icon name: %s\n"
                 "   Presence Is Invalid?: %s\n"
                 "   Blocked state:    %s\n"
                 "   Published state:  %s\n"
                 "   Subscribed state: %s\n"
                 "\n",
                 osso_abook_contact_get_display_name (contact),
                 type,
                 (tp_connection_presence_type_cmp_availability (type, TP_CONNECTION_PRESENCE_TYPE_HIDDEN) > 0) ? "yes" : "no",
                 osso_abook_presence_get_presence_status (presence),
                 osso_abook_presence_get_display_status (presence),
                 osso_abook_presence_get_presence_status_message (presence),
                 osso_abook_presence_get_location_string (presence),
                 osso_abook_presence_get_icon_name (presence),
                 osso_abook_presence_is_invalid (presence) ? "yes" : "no",
                 osso_abook_presence_state_get_nick (osso_abook_presence_get_blocked (presence)),
                 osso_abook_presence_state_get_nick (osso_abook_presence_get_published (presence)),
                 osso_abook_presence_state_get_nick (osso_abook_presence_get_subscribed (presence)));
}

[edit] 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.

/* Sort the contacts in order of decreasing availability */
contacts = g_list_sort (contacts, (GCompareFunc) osso_abook_presence_compare);

[edit] Notable Signals

  • notify::presence-location-string
  • notify::presence-status
  • notify::presence-status-message
  • notify::presence-type

[edit] Complete API Documentation

Full details can be found in the API reference documentation for OssoABookPresence.

[edit] Widget Classes

[edit] 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 can be used in many different situations.

[edit] Basic Example

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

static void
test_contact_chooser (void)
{
        GtkWidget *chooser;
        GList *selection;
 
        chooser = osso_abook_contact_chooser_new (NULL, "Choose a contact");
 
        /* uncomment this to allow user to select more than a single contact
        osso_abook_contact_chooser_set_minimum_selection
                (OSSO_ABOOK_CONTACT_CHOOSER (chooser), 2);
        osso_abook_contact_chooser_set_maximum_selection
                (OSSO_ABOOK_CONTACT_CHOOSER (chooser), G_MAXINT);
        */
 
        gtk_dialog_run (GTK_DIALOG (chooser));
        gtk_widget_hide (chooser);
 
        /* print the names of the selected contact to the command line */
        selection = osso_abook_contact_chooser_get_selection
                (OSSO_ABOOK_CONTACT_CHOOSER (chooser));
 
        if (selection) {
                GList *l;
 
                g_printf ("Selected Contacts:\n");
 
                for (l = selection; l; l = l->next) {
                        g_printf ("%s\n", osso_abook_contact_get_display_name(l->data));
                }
        } else {
                g_printf ("Nothing selected");
        }
 
        g_list_free (selection);
 
        gtk_widget_destroy (chooser);
}

[edit] Additional API

The contacts shown in the list can be customized in several ways.

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 show only those contacts that have an associated email address:

osso_abook_contact_chooser_set_capabilities (chooser, OSSO_ABOOK_CAPS_EMAIL);

You can show only those contacts whose presence status indicates that they are online, which may be useful for applications that want to interact with another contact over a messaging protocol:

osso_abook_contact_chooser_set_hide_offline_contacts (chooser, TRUE);

If there are specific contacts that you wish to exclude from the chooser, you can specify them explicitly. For example, consider an email application: when choosing recipients for a message, it might be useful to exclude the contacts that are already present in the "To:" field.

OssoABookContact *john_doe; /* reference to a contact from the addressbook */
 
GList *contacts = NULL;
contacts = g_list_prepend (contacts, john_doe);
osso_abook_contact_chooser_set_excluded_contacts (chooser, contacts);

If an application needs even more control, 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 shown in the chooser.

gboolean custom_visible_func(OssoABookContactChooser *chooser,
                             OssoABookContact *contact,
                             gpointer user_data)
{
        const char *needle = (const char*)user_data;
        const char *name = osso_abook_contact_get_display_name (contact);
 
        if (strstr (name, needle) != NULL) {
                return TRUE;
        return FALSE;
}
 
...
 
/* only show contacts that contain the string 'foo' in their name */
osso_abook_contact_chooser_set_visible_func (chooser, custom_visible_func,
                                             "foo", NULL);

In addition to the ability to customize the contacts that are shown in the chooser, the appearance and behavior can also be customized. The chooser can operate in either single-selection or multi-selection mode, it allows an application to specify the ordering of the contacts in the list, and provides functions to programmatically select and deselect items from the list.

[edit] Complete API Documentation

Full details can be found in the API reference documentation for OssoABookContactChooser.

[edit] 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 GtkTreeView columns automatically. It can show the contacts' name, Telephone number, presence status, and avatar image. These details can be selectively enabled or disabled according to an application's requirements.

It is unlikely that an application will need or want to instantiate an 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.

[edit] 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().

An application can filter the list of contacts that gets displayed in the tree 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:

OssoABookTreeView *view;
OssoABookListStore *base_model;
OssoABookFilterModel *filter_model;
 
base_model = osso_abook_contact_model_get_default ();
 
filter_model = osso_abook_filter_model_new (base_model);
 
/* only display contacts whose names contain the string "foo" */
osso_abook_filter_model_set_text (filter_model, "foo");
 
osso_abook_tree_view_set_base_model (view, base_model);
osso_abook_tree_view_set_filter_model (view, filter_model);

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 presence status and avatar image for that particular account regardless of the contact's status on other VoIP or IM accounts.

The details shown in the tree view can be controlled with the following properties:

  • show-contact-avatar
  • show-contact-name
  • show-contact-presence
  • show-contact-telephone

[edit] Complete API Documentation

Full details can be found in the API reference documentation for OssoABookTreeView.

[edit] OssoABookContactView

OssoABookContactView provides a convenient widget for displaying a list of contacts in a list. It builds upon OssoABookTreeView and adds a bit of convenience API.

[edit] Basic Example

The following example shows how to display all contacts from the Address Book in a list.

#include <libosso-abook/osso-abook.h>
 
int main (int argc, char** argv)
{
        osso_context_t *osso_cxt;
        OssoABookContactModel *default_model;
        GtkWidget *view, *window;
 
        osso_cxt = osso_initialize (argv[0], "1.0", FALSE, NULL);
        osso_abook_init (&argc, &argv, osso_cxt);
 
        window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 
        default_model = osso_abook_contact_model_get_default ();
        view = osso_abook_contact_view_new_basic (HILDON_UI_MODE_NORMAL,
                        default_model);
 
        gtk_container_add (GTK_CONTAINER (window), view);
 
        gtk_widget_show (view);
        gtk_widget_show (window);
        gtk_main ();
}

[edit] 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()

The Contact view can support both single- and multiple-selection modes. 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.

[edit] Complete API Documentation

Full details can be found in the API reference documentation for OssoABookContactView.

[edit] OssoABookTouchContactStarter

OssoABookTouchContactStarter is a widget that displays the information for a contact and can be used to initiate communication with a contact (email, IM, VoIP, etc).

[edit] Basic Example

The following is a simple example that shows how to use OssoABookTouchContactStarter to display the details of a particular contact.

#include <libosso-abook/osso-abook.h>
 
int main (int argc, char** argv)
{
        osso_context_t *osso_cxt;
        //OssoABookTouchContactStarter *starter;
        GtkWidget *starter, *window, *chooser;
        GList *contacts = NULL;
 
        osso_cxt = osso_initialize (argv[0], "1.0", FALSE, NULL);
        osso_abook_init (&argc, &argv, osso_cxt);
 
        chooser = osso_abook_contact_chooser_new (NULL, "Pick a Contact");
        gtk_dialog_run (GTK_DIALOG (chooser));
        gtk_widget_hide (chooser);
 
        contacts = osso_abook_contact_chooser_get_selection
                (OSSO_ABOOK_CONTACT_CHOOSER (chooser));
 
        if (contacts) {
                starter = osso_abook_touch_contact_starter_new_with_contact
                        (NULL, contacts->data);
                window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
                gtk_container_add (GTK_CONTAINER (window), starter);
 
                gtk_widget_show (starter);
                gtk_widget_show (window);
                g_signal_connect (window, "destroy", gtk_main_quit, NULL);
                gtk_main ();
 
                g_list_free (contacts);
        }
 
        return 0;
}

[edit] Additional API

In addition to the basic example shown above, there are several other ways to 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().

A contact starter is normally interactive in the sense that it can be used to initiate contact with the contact (e.g. start a phone call, start a chat, etc), though it can be made non-interactive by creating the starter with 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:

gboolean
pre_action_start_cb (OssoABookTouchContactStarter *starter,
                OssoABookContactFieldAction *action,
                gpointer user_data)
{
        OssoABookContactAction action_type =
                osso_abook_contact_field_action_get_action (action);
 
        if (OSSO_ABOOK_CONTACT_ACTION_TEL == action_type) {
                hildon_banner_show_information (GTK_WIDGET (starter),
                                NULL, "Telephone call action intercepted");
 
                /* stop signal emission */
                return TRUE;
        }
 
        /* don't stop signal emission -- let the default handler have it */
        return FALSE;
}
 
...
 
g_signal_connect (starter, "pre-action-start",
                                G_CALLBACK (pre_action_start_cb), NULL);

[edit] Complete API Documentation

Full details can be found in the API reference documentation for OssoABookTouchContactStarter.

[edit] Glossary

aggregated contact
a persistent master contact with one or more attached roster contacts.
aggregator
an OssoABookAggregator object which manages connections to the EDS backends and associates master contacts with their roster contacts.
master contact
an OssoABookContact which aggregates the attributes of zero or one persistent master contacts and zero or more roster contacts.
persistent master contact
an OssoABookContact which is stored in the EDS local database and has zero or more roster contacts.
roster contact
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.
temporary master contact
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.
unique identifier (UID)
a hashable ID which is unique across all EDS back-ends. See the definition for "temporary master contact" for relevant usage warnings.