Latest revision |
Your text |
Line 330: |
Line 330: |
| 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]. | | 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 ===
| + | 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. |
- | | + | |
- | 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 <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".
| + | |
- | | + | |
- | <code>OssoABookPresence</code> is implemented by <code>OssoABookContact</code>, so <code>OssoABookPresence</code> functions are used directly upon <code>OssoABookContacts</code>.
| + | |
- | | + | |
- | ==== 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.
| + | |
- | | + | |
- | <source lang="c">
| + | |
- | #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, ¤t_status, ¤t_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)));
| + | |
- | }
| + | |
- | </source>
| + | |
- | | + | |
- | ==== Additional API ====
| + | |
- | | + | |
- | 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.
| + | |
- | | + | |
- | <source lang="c">
| + | |
- | /* Sort the contacts in order of decreasing availability */
| + | |
- | contacts = g_list_sort (contacts, (GCompareFunc) osso_abook_presence_compare);
| + | |
- | </source>
| + | |
- | | + | |
- | ==== Notable Signals ====
| + | |
- | | + | |
- | * <code>notify::presence-location-string</code>
| + | |
- | * <code>notify::presence-status</code>
| + | |
- | * <code>notify::presence-status-message</code>
| + | |
- | * <code>notify::presence-type</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-presence.html reference documentation for OssoABookPresence].
| + | |
| | | |
| == Widget Classes == | | == Widget Classes == |