Maemo Wiki Mirror - User contributions [en]

Mer/Build

2012-10-27T06:32:01Z

94.23.1.28: Undo revision 20960 by 212.242.158.18 (Talk)

Clothing has always been a thing that has been given a great imctoranpe by human beings. It displays the attitude that the people exhibit. Lots of brands have been existent in the clothing industry and a famous one among them is the Ed hardy clothing brand.The brand got its name from the famous American tattoo artist Ed Hardy. He was a very famous tattoo artist and has published many books on tattooing techniques. But his tattooing turned into a brand by the efforts of a company called Christian Audiger. This company was a very famous and very powerful company in the field of clothing. They felt that it would be appropriate to create a brand called Ed hardy and use Hardy's art as the main selling point for the brand. This venture had turned out to be a very successful one and Ed hardy clothing is one of the most famous brands in the clothing industry.The brand became very famous because it was worn by many famous celebrities like Madonna, Britney spears and also Sylvester Stallone. The brand has clothes for men, women, and kids. They have also diversified their business by having a lot of accessories to support their clothing business. for men they have a variety of products such as active wear, denim, outwear, swim trucks, sweaters, t-shirts, tops etc. the accessories include things such as belts, caps, scarves, shoes, socks, jeweler, sunglasses, ties and even wallets.The art works is a unique combination of American and Japanese cultures. The unique selling proposition of the brand is the way in which the company has used the art works of Ed hardy.

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

2012-10-27T05:56:06Z

94.23.1.28: /* OssoABookPresence */

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.

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 [http://maemo.org/api_refs/5.0/5.0-final/libosso-abook/ reference documentation].

== Components ==

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|frame|center|alt=Diagram of address book components|Address book components]]

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

=== 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:

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

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

==== 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, <code>OssoABookContact</code> is a subclass of it).

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) ===

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 ==

=== 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:

# Any user-set image
# 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>.

==== Basic Example ====

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

<source lang="c">
#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");
}
}
</source>

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

==== 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, <code>image_token</code> is a hashable value:
<source lang="c">
gpointer image_token = osso_abook_avatar_get_image_token (OSSO_ABOOK_AVATAR (contact));
</source>

==== Notable Signals ====

* <code>notify::avatar-image</code>

==== Complete API Documentation ====

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

=== OssoABookCaps ===

<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 ====

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:

<source lang="c">
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");
}
</source>

==== Additional API ====

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

<source lang="c">
OssoABookCapsFlags caps_flags = osso_abook_caps_from_account (account);
</source>

==== Notable Signals ====

* <code>notify::capabilities</code>

==== 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].

=== OssoABookContact ===

The central class in libosso-abook is <code>OssoABookContact</code>, 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 <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.

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.

==== Basic Examples ====

===== 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 <code>OssoABookAvatar</code>; for its IM presence or capabilities, see <code>OssoABookPresence</code> and <code>OssoABookCaps</code>.

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

<source lang="c">
#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");
}
</source>

==== Additional API ====

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 <code>OssoABookContact</code>.

===== 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 <code>TRUE</code> if you wish to include the contact's avatar data (this can be very long).

<source lang="c">
osso_abook_contact_to_string (contact, EVC_FORMAT_VCARD_30, FALSE);
</source>

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:

<source lang="c">
/* 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);
</source>

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

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

<source lang="c">
#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);
}
</source>

===== Roster Contacts =====

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

<source lang="c">
#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");
}
</source>

===== Attribute Convenience Functions =====

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

<source lang="c">
const char *key = osso_abook_contact_get_uid (contact);
</source>

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

<source lang="c">
const char *key = osso_abook_contact_get_persistent_uid (contact);

if (!key) {
g_print ("This contact isn't persistent!");
}
</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:

<source lang="c">
#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);
}
</source>

==== Notable Signals ====

* <code>reset</code>
* <code>contact-attached</code>
* <code>contact-detached</code>

==== Complete API Documentation ====

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

Between me and my husband we've owned more MP3 paryels over the years than I can count, including Sansas, iRivers, iPods (classic & touch), the Ibiza Rhapsody, etc. But, the last few years I've settled down to one line of paryels. Why? Because I was happy to discover how well-designed and fun to use the underappreciated (and widely mocked) Zunes are.

== Widget Classes ==

=== OssoABookContactChooser ===

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

==== Basic Example ====

The following is a simple example of the use of <code>OssoABookContactChooser</code>:

<source lang="c">
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);
}
</source>

==== Additional API ====

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

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

<source lang="c">
osso_abook_contact_chooser_set_capabilities (chooser, OSSO_ABOOK_CAPS_EMAIL);
</source>

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:

<source lang="c">
osso_abook_contact_chooser_set_hide_offline_contacts (chooser, TRUE);
</source>

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.

<source lang="c">
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);
</source>

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

<source lang="c">
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);
</source>

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.

==== 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].

=== OssoABookTreeView ===

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
selectively enabled or disabled according to an application's requirements.

It is unlikely that an application will need or want to instantiate an
<code>OssoABookTreeView</code> object directly. Most of the time, applications will deal
with <code>OssoABookContactView</code> objects, which inherits from this class and does most of the setup work for you.

==== Additional API ====

<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>,
<code>osso_abook_tree_view_get_pannable_area()</code>.

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

<source lang="c">
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);
</source>

In addition, if you only want to display those contacts associated with a 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
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:
* <code>show-contact-avatar</code>
* <code>show-contact-name</code>
* <code>show-contact-presence</code>
* <code>show-contact-telephone</code>

==== 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].

=== OssoABookContactView ===

<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
convenience API.

==== Basic Example ====

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

<source lang="c">
#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 ();
}
</source>

==== Additional API ====

<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:
* <code>osso_abook_contact_view_get_focus()</code>
* <code>osso_abook_contact_view_get_focus_avatar()</code>
* <code>osso_abook_contact_view_get_focus_presence()</code>
* <code>osso_abook_contact_view_get_focus_caps()</code>

The Contact view can support both single- and multiple-selection modes.
<code>osso_abook_contact_view_set_minimum_selection()</code> and
<code>osso_abook_contact_view_set_maximum_selection()</code> allow fine-grained control over how contacts can be selected.

==== 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].

=== OssoABookTouchContactStarter ===

<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,
VoIP, etc).

==== Basic Example ====

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

<source lang="c">
#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;
}
</source>

==== Additional API ====

In addition to the basic example shown above, there are several other ways to
customize the <code>OssoABookTouchContactStarter</code> widget. By default the contact 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
changed directly from the contact starter widget. An editor can also be
launched programmatically by calling <code>osso_abook_touch_contact_starter_start_editor()</code>.

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
<code>osso_abook_touch_contact_starter_new_not_interactive()</code>. In addition, an
application can override the default actions by connecting to the <code>pre-action-start</code> signal. For example:

<source lang="c">
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);

</source>

==== 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].

== Glossary ==

;aggregated contact
: a persistent master contact with one or more attached roster contacts.
;aggregator
: an <code>OssoABookAggregator</code> object which manages connections to the EDS backends and associates master contacts with their roster contacts.
;master contact
: an <code>OssoABookContact</code> which aggregates the attributes of zero or one persistent master contacts and zero or more roster contacts.
;persistent master contact
: an <code>OssoABookContact</code> which is stored in the EDS local database and has zero or more roster contacts.
;roster contact
: 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
: 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.

[[Category:Development]]
[[Category:Documentation]]
[[Category:Fremantle]]

Extras repository process definition

2012-06-14T03:30:13Z

94.23.1.28: /* Nokia */

{{quotation|To provide the simplest interface for end users to get good quality third party software that downloads and installs flawlessly, without compromising their default system. To provide maemo tools and infrastructure to developers so they can check the quality of their software, offer it to end users and promote it.|Quim Gil}}

== Analysis of current situation ==
The Extras repository needs to maintain a high level of quality applications.

This is way better than a brick & mroatr establishment.

=== Developers ===
* We have problems promoting their software. (Promote)
* It is difficult to assure that the application is installing and running well on all devices. (Quality Assurance)
* There are multiple platforms that we need to build manually for. (Build Management)
* We have problems to coordinating our work with the work of other developers—especially if using common libraries. (Coordination)
* Not every developer is alike. The process must support:
** Garage projects
** External projects with local packaging
** External projects (Flexible)

=== Users ===
* There are a huge number of applications. Most of the applications would promote the devices and the platform, but it is difficult to:
** Find applications (Locate)
** Judge if the application is of good "quality" (Quality)

== Resulting Claims ==

We need a process that...

* '''Defines Quality''': What constitutes quality? A checklist for determining if a package is satisfactory.
* '''Assures Quality''': Each package undergoes QA to make sure it is satisfactory.
* '''Is simple''': Avoid unnecessary esoteric complications. Keep the process straightforward and well-documented.
* '''Is somewhat centralized''': The system is centralized for better control and better QA.
* '''Is scalable''': The system will scale easily and cleanly under increased load.
* '''Assures security and control over the process''': Centralized system to control the quality of packages and help assure packages and the system are safe and secure.
* '''Is iterative for developers''': Development can take place in small steps.
* '''Eases building packages''': Reduces developer workload
* '''Helps user finding applications''': Clear, clean, centralized organization helps users to find the software they need.
* '''Helps promoting software''': Help advertise and promote good software to users and the community.
* '''Must be flexible regarding package sources''': Flexible build and distribution system for a variety of package sources.

== Concepts ==

* We need a very clear definition of quality (with possible exceptions to avoid excessively stringent qualifications).
* Use Debian staging approach with multiple repositories (unstable, testing, stable). Tune it to fit for smaller number of packages and smaller community. This includes uploading of only source packages and an autobuilder.
* Define a bug tracking system as master for all Extras packages.
* Enhance the application catalog to give the user a hint about the measured quality of an application.
* Enhance the application catalog to allow the user to rate the quality of an application.
* Try to directly link (aka http links) and integrate (linking information) bug tracking system and application catalog.
* Enhance the packaging format link to package specific information in the bug tracking system and in the application catalog.
* Enhance the device to simplify the rating, quality assurance and bug tracking process.
* While the process itself should be as much automated as possible we still need a team that decides in situations like:
** MIA
** Packaging conflicts (multiple packages for the same software, different required versions)—especially for shared libraries and base packages.

== Solution strategies ==

The resulting solution strategy consists of a number of concrete proposals for changes and additions to the existing infrastructure to create an environment to fit the requirements.

=== Bugzilla ===

* Each extras package should have its own defined bug tracking system (either in garage or a component in bugs.maemo.org?).
** Ensuring that each package has its own bug-tracking system isn't feasible. What about trivial make/compile ports, and packages which are adapted from debian largely unchanged. These will appropriately have essentially no maemo-specific infrastructure, and will have infrastructure upstream instead. Also consider the case of a very immature project with a single developer who hasn't created infrastructure yet.
** Instead, extras should have its own bug-tracker which applies to extras as a whole.
** Each package should have an owner, who may or may not be the upstream developer. The owner must watch the extras bug-tracker for bugs submitted against their packages.
** Bugs which are appropriately resolved upstream should be resubmitted there, either by the package owner, or by closing the bug wontfix with a comment that certain types of need to be dealt with upstream and a polite message requesting that the submitter resubmit the bug there.
** Extras is essentially a linux distro. The above bug handling strategies are used by every major distro on the planet, we should use them too.
* Try to synchronize application bug tracking system with upstream bug tracking system.

=== Downloads ===

* Add statistical information from the bug tracking system.
* [http://bugs.maemo.org/show_bug.cgi?id=2179 Bug 2179 - Visualize rating creation date and related software version].
* Directly display available version in the Extras repository '''- [http://lists.maemo.org/pipermail/maemo-developers/2008-July/034212.html maemo.org/downloads automatic updates from Extras]'''
* Directly link to bug tracking "new bug" package for this application.

=== Device ===
* [http://bugs.maemo.org/show_bug.cgi?id=1563 Bug 1563 - Application installer to send feedback to the providing site if install fails]
* Desktop should open crash report dialog if application crashes.
* Application Manager should integrate rating of applications (possibly 3rd party application first).

=== Repository ===

* Nokia has initiated creation of an extras-devel repository.
* Initiate some variant of the debian staging process.

=== autobuilder ===

''The autobuilder automatically builds packages based on source packages.''

Package requirements:

* Needs to be a source package.
* Needs to have a Garage page or at least links to maintainer, upstream and a bug tracking system.

Process requirements:

* Simple (re)upload of packages
* Automatically compile one package for multiple OSs (OS 2006, OS 2007, OS 2008)
* Automatically recompile everything for a new OS.
* Automatically update corresponding downloads.maemo.org page.
* Should honor build dependencies (build dependencies first).
* Always build in a clean environment that only has build dependencies preinstalled. Thus checking for missing build dependencies.
* Possibility to manually force rebuild of a certain package or all dependencies of a certain package (e.g. an unversioned dependency changes).
* Push packages only into the repository, if all runtime dependencies are fulfilled.
* Automatically notify the package maintainer on build failures (per email or per bug tracking system).
* Uploading to the autobuilder should be possibly directly from the garage project page.

=== autotester ===

The autotester does some automatic tests on build packages to assure certain packaging quality constraints.

* Possibly use [http://lintian.debian.org/ Lintian] as part of such solution ([https://bugs.maemo.org/show_bug.cgi?id=2240 Bug 2240 - Add Lintian])
* Regularly install everything in the archive in a clean environment to check if there are installation installation conflicts (multiple packages installing same files).

=== autostager ===

The autostager does some automatic rating of a package base on a number of criteria and information source to judge its quality and thus add the package to a certain staging repository or to remove it from a staging repository.

* Automatically create a page on Downloads if it does not exist.

=== Package ===

* [http://www.hadrons.org/~guillem/debian/docs/origin.proposal Origin field in deb]

=== Quality Assurance ===

Your ideas here.

* Visibility and promotion of [http://maemo.org/maemo_release_documentation/maemo4.1.x/node16.html Quality considerations] for application developers.
** A checkbox requesting the developer to say 'Yes, I'm aware of the quality considerations and I have done my best implementing them in my software"? Might sound a bit stupid and totally by-passable but it might be a good promotion of these quality considerations.--[[User:qgil|qgil]] 09:28, 21 November 2008 (UTC)
* Perhaps a very basic and descriptive list of Very Basic Testing to do in each release?
* Automated testing, what can be done on the server side?
* Some days of quarantene in extras-testing when promoting a package from extras-devel, no matter what?
** Hum, falling again in the unstable-testing-stable paradigm.--[[User:qgil|qgil]] 09:28, 21 November 2008 (UTC)
* Objective criteria to demote a package from extras to testing/devel?
** What would happen to regular users with that package installed? They might be confused if a human-readable notification doesn't tell them what's going on.--[[User:qgil|qgil]] 09:28, 21 November 2008 (UTC)
* Nokia to include extras apps in their own testing.
* Specific QA routines to be defined for extras apps being promoted in maemo.nokia.com or other marketing activities.
* Automated use of Debian tools like [http://wiki.debian.org/piuparts piuparts] would help find issues with installing, upgrading, downgrading, and removing packages.

== Links ==

* [http://lists.maemo.org/pipermail//maemo-developers/2007-October/012192.html related thread on maemo-developers mailing list regarding extra repository]
* [http://lists.maemo.org/pipermail//maemo-developers/2007-November/012600.html related thread on maemo-developers mailing list regarding autobuilder]

[[Category:Community]]