OssoABookContact

OssoABookContact — Rich representation of addressbook contacts.

Synopsis

                    OssoABookContact;
OssoABookContact*   osso_abook_contact_new              (void);
OssoABookContact*   osso_abook_contact_new_from_template
                                                        (EContact *templ);
OssoABookContact*   osso_abook_contact_new_from_vcard   (const char *uid,
                                                         const char *vcard);

gboolean            osso_abook_contact_add_value        (EContact *contact,
                                                         const char *attr_name,
                                                         GCompareFunc value_check,
                                                         const char *value);
gboolean            osso_abook_contact_find_matching_values
                                                        (EContact *contact_a,
                                                         EContact *contact_b,
                                                         const char *attr_name,
                                                         GList **values);
char*               osso_abook_contact_get_value        (EContact *contact,
                                                         const char *attr_name);
GList*              osso_abook_contact_get_values       (EContact *contact,
                                                         const char *attr_name);
void                osso_abook_contact_remove_value     (EContact *contact,
                                                         const char *attr_name,
                                                         const char *value);
void                osso_abook_contact_set_value        (EContact *contact,
                                                         const char *attr_name,
                                                         const char *value);

gboolean            osso_abook_contact_add_master_uid   (OssoABookContact *roster_contact,
                                                         const char *master_uid);
GList*              osso_abook_contact_get_master_uids  (OssoABookContact *roster_contact);
gboolean            osso_abook_contact_remove_master_uid
                                                        (OssoABookContact *roster_contact,
                                                         const char *master_uid);
gboolean            osso_abook_contact_is_roster_contact
                                                        (OssoABookContact *contact);

GList*              osso_abook_contact_get_roster_contacts
                                                        (OssoABookContact *master_contact);

const char**        osso_abook_contact_get_collate_keys (OssoABookContact *contact,
                                                         OssoABookNameOrder order);
int                 osso_abook_contact_collate          (OssoABookContact *a_contact,
                                                         OssoABookContact *b_contact,
                                                         OssoABookNameOrder order);

void                osso_abook_contact_set_roster       (OssoABookContact *contact,
                                                         OssoABookRoster *roster);
OssoABookRoster*    osso_abook_contact_get_roster       (OssoABookContact *contact);
McAccount*          osso_abook_contact_get_account      (OssoABookContact *contact);
const char*         osso_abook_contact_get_vcard_field  (OssoABookContact *contact);


void                osso_abook_contact_commit           (OssoABookContact *contact,
                                                         gboolean create,
                                                         EBook *book,
                                                         GtkWindow *window);
void                osso_abook_contact_delete           (OssoABookContact *contact,
                                                         EBook *book,
                                                         GtkWindow *window);
void                osso_abook_contact_delete_many      (GList *contacts,
                                                         EBook *book,
                                                         GtkWindow *window);
GdkPixbuf*          osso_abook_contact_get_photo        (OssoABookContact *contact);
void                osso_abook_contact_set_pixbuf       (OssoABookContact *contact,
                                                         GdkPixbuf *pixbuf,
                                                         EBook *book,
                                                         GtkWindow *window);
void                osso_abook_contact_set_photo        (OssoABookContact *contact,
                                                         const char *filename,
                                                         EBook *book,
                                                         GtkWindow *window);
OssoABookAvatar*    osso_abook_contact_get_avatar       (OssoABookContact *contact,
                                                         const char *username,
                                                         const char *vcard_field);
GdkPixbuf*          osso_abook_contact_get_avatar_pixbuf
                                                        (OssoABookContact *contact,
                                                         const char *username,
                                                         const char *vcard_field);
const char*         osso_abook_contact_get_name_with_order
                                                        (OssoABookContact *contact,
                                                         OssoABookNameOrder order);
gboolean            osso_abook_contact_get_blocked      (OssoABookContact *contact);
gboolean            osso_abook_contact_can_block        (OssoABookContact *contact,
                                                         const char **infoprint);
gboolean            osso_abook_contact_can_request_auth (OssoABookContact *contact,
                                                         const char **infoprint);
const char*         osso_abook_contact_get_name         (OssoABookContact *contact);
const char*         osso_abook_contact_get_display_name (OssoABookContact *contact);
void                osso_abook_contact_vcard_clean      (EContact *contact);

enum                OssoABookNameOrder;
const GEnumValue*   osso_abook_name_order_from_name     (const char *name);
const GEnumValue*   osso_abook_name_order_from_nick     (const char *nick);
const char*         osso_abook_name_order_get_name      (OssoABookNameOrder value);
const char*         osso_abook_name_order_get_nick      (OssoABookNameOrder value);

#define             OSSO_ABOOK_VCA_OSSO_CONTACT_STATE
#define             OSSO_ABOOK_VCA_OSSO_LAST_USED
#define             OSSO_ABOOK_VCA_OSSO_MASTER_UID
#define             OSSO_ABOOK_VCA_TELEPATHY_BLOCKED
#define             OSSO_ABOOK_VCA_TELEPATHY_CAPABILITIES
#define             OSSO_ABOOK_VCA_TELEPATHY_HANDLE
#define             OSSO_ABOOK_VCA_TELEPATHY_PRESENCE
#define             OSSO_ABOOK_VCA_TELEPATHY_PUBLISHED
#define             OSSO_ABOOK_VCA_TELEPATHY_SUBSCRIBED

#define             OSSO_ABOOK_VCP_OSSO_BOUND
#define             OSSO_ABOOK_VCP_OSSO_FIELD_STATE

Description

This module provides the OssoABookContact class, but also a collection of utility functions which operate on plain EContact objects.

Details

OssoABookContact

typedef struct {
        EContact parent;
} OssoABookContact;

All the fields of this structure are private to the object's implementation and should never be accessed directly.


osso_abook_contact_new ()

OssoABookContact*   osso_abook_contact_new              (void);

Create a new and still empty OssoABookContact.

Returns : A newly allocated OssoABookContact.

osso_abook_contact_new_from_template ()

OssoABookContact*   osso_abook_contact_new_from_template
                                                        (EContact *templ);

Create a new and initializes its attributes to match templ.

templ : the contact template
Returns : A newly allocated OssoABookContact.

osso_abook_contact_new_from_vcard ()

OssoABookContact*   osso_abook_contact_new_from_vcard   (const char *uid,
                                                         const char *vcard);

Create a new and initializes to have the attributes described in vcard. The vcard string is not parsed unless another attribute but the UID attribute is required.

uid : the UID of the contact, or NULL
vcard : the vCard string describing the contact
Returns : A newly allocated OssoABookContact.

osso_abook_contact_add_value ()

gboolean            osso_abook_contact_add_value        (EContact *contact,
                                                         const char *attr_name,
                                                         GCompareFunc value_check,
                                                         const char *value);

Adds a new value to the attribute matching attr_name. The value is not added, when a function is specified for value_check and this function returns 0 for value and one of the existing attribute values.

contact : a EContact
attr_name : the attribute name
value_check : a function to check for unique values, or NULL
value : the new value
Returns : TRUE when value was added, and FALSE otherwise.

osso_abook_contact_find_matching_values ()

gboolean            osso_abook_contact_find_matching_values
                                                        (EContact *contact_a,
                                                         EContact *contact_b,
                                                         const char *attr_name,
                                                         GList **values);

contact_a :
contact_b :
attr_name :
values :
Returns :

osso_abook_contact_get_value ()

char*               osso_abook_contact_get_value        (EContact *contact,
                                                         const char *attr_name);

Retrieves the value of the named single-value attribute, when found.

contact : a EContact
attr_name : the attribute name
Returns : A newly allocated string representing the attribute value, or NULL when the attribute was not found.

osso_abook_contact_get_values ()

GList*              osso_abook_contact_get_values       (EContact *contact,
                                                         const char *attr_name);

Retrieves the value list for the first attribute matching attr_name.

contact : a EContact
attr_name : the attribute name
Returns : A string list. The list is owned by the contact and must not be freed.

osso_abook_contact_remove_value ()

void                osso_abook_contact_remove_value     (EContact *contact,
                                                         const char *attr_name,
                                                         const char *value);

Removes all occurrences of value from the value list of the attribute matching attr_name.

contact : a EContact
attr_name : the attribute name
value : the value to remove

osso_abook_contact_set_value ()

void                osso_abook_contact_set_value        (EContact *contact,
                                                         const char *attr_name,
                                                         const char *value);

Changes the value of the named single-value attribute. Passing a value of NULL removes the attribute.

contact : a EContact
attr_name : the attribute name
value : the new value, or NULL

osso_abook_contact_add_master_uid ()

gboolean            osso_abook_contact_add_master_uid   (OssoABookContact *roster_contact,
                                                         const char *master_uid);

Adds a master contact's UID to the OSSO_ABOOK_VCA_OSSO_MASTER_UID attribute of the contact.

roster_contact : a OssoABookContact
master_uid : the master's UID
Returns : TRUE when the contact was modified, and FALSE otherwise.

osso_abook_contact_get_master_uids ()

GList*              osso_abook_contact_get_master_uids  (OssoABookContact *roster_contact);

Retrieves the list of master contact's UID stored in this contact's OSSO_ABOOK_VCA_OSSO_MASTER_UID attribute.

roster_contact : a OssoABookContact
Returns : A string list. The list is owned by the contact and must not be freed.

osso_abook_contact_remove_master_uid ()

gboolean            osso_abook_contact_remove_master_uid
                                                        (OssoABookContact *roster_contact,
                                                         const char *master_uid);

Removes a master contact's UID from the OSSO_ABOOK_VCA_OSSO_MASTER_UID attribute of the contact.

roster_contact : a OssoABookContact
master_uid : the master's UID
Returns : TRUE when the contact was modified, and FALSE otherwise.

osso_abook_contact_is_roster_contact ()

gboolean            osso_abook_contact_is_roster_contact
                                                        (OssoABookContact *contact);

Checks if the contact originates from some Telepathy based OssoABookRoster.

contact : a OssoABookContact
Returns : TRUE when the contact comes from some Telepathy roster, and FALSE otherwise.

osso_abook_contact_get_roster_contacts ()

GList*              osso_abook_contact_get_roster_contacts
                                                        (OssoABookContact *master_contact);

Retrieves the current list of roster contacts attached to this contact.

master_contact : a OssoABookContact
Returns : A OssoABookContact list. The content of the list is owned by the contact and should not be modified or freed. Use g_list_free() when done using the list.

osso_abook_contact_get_collate_keys ()

const char**        osso_abook_contact_get_collate_keys (OssoABookContact *contact,
                                                         OssoABookNameOrder order);

Returns the locale specific sorting keys for contacts with respect to the preferred name order.

contact : An OssoABookContact
order : The OssoABookNameOrder to use
Returns : A NULL terminated array of collate keys for contact. This array is owned by libosso-abook and should not be freed.

osso_abook_contact_collate ()

int                 osso_abook_contact_collate          (OssoABookContact *a_contact,
                                                         OssoABookContact *b_contact,
                                                         OssoABookNameOrder order);

Compares two contacts by name with respect to order and locale specific sorting rules.

a_contact : First OssoABookContact
b_contact : Second OssoABookContact
order : The OssoABookNameOrder to use
Returns : -1 when a_contact is before b_contact, 0 when both contacts are equal and +1 when a_contact is after b_contact.

osso_abook_contact_set_roster ()

void                osso_abook_contact_set_roster       (OssoABookContact *contact,
                                                         OssoABookRoster *roster);

Changes the OssoABookRoster this contact is supposed to come from.

contact : a OssoABookContact
roster : the OssoABookRoster

osso_abook_contact_get_roster ()

OssoABookRoster*    osso_abook_contact_get_roster       (OssoABookContact *contact);

Queries the OssoABookRoster this contact comes from.

contact : a OssoABookContact
Returns : A OssoABookRoster, or NULL when the roster is not known.

osso_abook_contact_get_account ()

McAccount*          osso_abook_contact_get_account      (OssoABookContact *contact);

Queries the McAccount this contact comes from.

contact : a OssoABookContact
Returns : A McAccount, or NULL when the account is not known.

osso_abook_contact_get_vcard_field ()

const char*         osso_abook_contact_get_vcard_field  (OssoABookContact *contact);

Queries the primary vCard attributes of the OssoABookRoster this contact comes from.

contact : a OssoABookContact
Returns : The name of a vCard attribute, or NULL.

osso_abook_contact_commit ()

void                osso_abook_contact_commit           (OssoABookContact *contact,
                                                         gboolean create,
                                                         EBook *book,
                                                         GtkWindow *window);

Commits contact to book asynchronously. When book is NULL and contact is an OssoABookContact, then the contact's OssoABookRoster is queried to find the EBook this contact originates from.

contact : An OssoABookContact
create : TRUE if this is a new OssoABookContact
book : The EBook contact originates from, or NULL
window : Optional parent window for the error banner

osso_abook_contact_delete ()

void                osso_abook_contact_delete           (OssoABookContact *contact,
                                                         EBook *book,
                                                         GtkWindow *window);

Deletes contact.

contact : An OssoABookContact
book : The EBook contact originates from, or NULL to purely modify contact without commiting the change.
window : optional parent for error banners

osso_abook_contact_delete_many ()

void                osso_abook_contact_delete_many      (GList *contacts,
                                                         EBook *book,
                                                         GtkWindow *window);

contacts :
book :
window :

osso_abook_contact_get_photo ()

GdkPixbuf*          osso_abook_contact_get_photo        (OssoABookContact *contact);

Fetches and returns the photo for a contact (as set in the PHOTO field). It also scales the photo to 64x90 pixels.

contact : An OssoABookContact
Returns : A newly allocated GdkPixbuf of the photo, or NULL.

osso_abook_contact_set_pixbuf ()

void                osso_abook_contact_set_pixbuf       (OssoABookContact *contact,
                                                         GdkPixbuf *pixbuf,
                                                         EBook *book,
                                                         GtkWindow *window);

Stores the image pointed to by pixbuf into the photo cache as a 64x90 JPEG file, and points the photo field of contact to it.

contact : An OssoABookContact
pixbuf : A GdkPixbuf of the new image
book : The EBook contact originates from, or NULL to purely modify contact without commiting the change.
window : optional parent window for the error banners

osso_abook_contact_set_photo ()

void                osso_abook_contact_set_photo        (OssoABookContact *contact,
                                                         const char *filename,
                                                         EBook *book,
                                                         GtkWindow *window);

Stores the image pointed to by filename into the photo cache as a 64x90 JPEG file, and points the photo field of contact to it.

contact : An OssoABookContact
filename : A path to an image file
book : The EBook contact originates from, or NULL to purely modify contact without commiting the change.
window : optional parent window for the error banners

osso_abook_contact_get_avatar ()

OssoABookAvatar*    osso_abook_contact_get_avatar       (OssoABookContact *contact,
                                                         const char *username,
                                                         const char *vcard_field);

Gets the OssoABookAvatar associated to contact, using username and vcard_field to select the specific account. You should use this function if you want to have notification for when the avatar image changes. If username or vcard_field are NULL, the returned object will monitor every account bound to contact.

contact : a OssoABookContact
username : the account's user name, or NULL
vcard_field : the account's vCard field name, or NULL
Returns : a OssoABookAvatar object.

osso_abook_contact_get_avatar_pixbuf ()

GdkPixbuf*          osso_abook_contact_get_avatar_pixbuf
                                                        (OssoABookContact *contact,
                                                         const char *username,
                                                         const char *vcard_field);

Gets the avatar image set for contact, using username and vcardf_ield to get the specific image set for an account. If username and vcard_field are NULL, the returned image will be the first found. If you want to have notification for when the contact's avatar image changes you should use osso_abook_contact_get_avatar() to retrieve the OssoABookAvatar object and connect to the 'notify::image' signal of that object.

contact : An OssoABookContact
username : the account's user name, or NULL
vcard_field : the account's vCard field name, or NULL
Returns : a GdkPixbuf containing the contact's avatar, or NULL. You should use g_object_unref() on the returned pixbuf when done.

osso_abook_contact_get_name_with_order ()

const char*         osso_abook_contact_get_name_with_order
                                                        (OssoABookContact *contact,
                                                         OssoABookNameOrder order);

Retreives the text used to display the name of contact according to order.

contact : An OssOABookContact
order : The OssoABookNameOrder to use
Returns : The display name of contact. This string is owned by libosso-abook and should not be freed.

osso_abook_contact_get_blocked ()

gboolean            osso_abook_contact_get_blocked      (OssoABookContact *contact);

Returns a boolean indicating whether contact is blocked or not.

contact : An OssoABookContact
Returns : TRUE if contact is blocked, FALSE otherwise.

osso_abook_contact_can_block ()

gboolean            osso_abook_contact_can_block        (OssoABookContact *contact,
                                                         const char **infoprint);

Checks if it is possible to block contact, and if not possible sets infoprint to point to a string explaining why not.

contact : An OssoABookContact
infoprint : Location to store the explanation string, or NULL
Returns : TRUE if contact can be blocked

osso_abook_contact_can_request_auth ()

gboolean            osso_abook_contact_can_request_auth (OssoABookContact *contact,
                                                         const char **infoprint);

Checks if it is possible to request authorization for contact, and if not possible sets infoprint to point to a string explaining why not.

contact : An OssoABookContact
infoprint : Location to store the explanation string, or NULL
Returns : TRUE if authorization can be requested for contact

osso_abook_contact_get_name ()

const char*         osso_abook_contact_get_name         (OssoABookContact *contact);

Retreives the text used to represent the name of contact internally. This string is formed according to the "/apps/osso-addressbook/display_method" preference. To keep it up to date, call this function again when the preference changes.

To display the name of a contact use osso_abook_contact_get_display_name().

contact : An OssOABookContact
Returns : The name of contact. This string is owned by libosso-abook and should not be freed.

osso_abook_contact_get_display_name ()

const char*         osso_abook_contact_get_display_name (OssoABookContact *contact);

Retreives the text used to display the name of contact. This string is formed according to the "/apps/osso-addressbook/display_method" preference. To keep the display up to date, call this function again when the preference changes.

contact : An OssoABookContact
Returns : The display name of contact. This string is owned by libosso-abook and should not be freed.

osso_abook_contact_vcard_clean ()

void                osso_abook_contact_vcard_clean      (EContact *contact);

Clean a contact, by removing all empty fields.

contact : An EContact

enum OssoABookNameOrder

typedef enum {
        OSSO_ABOOK_NAME_ORDER_FIRST,
        OSSO_ABOOK_NAME_ORDER_LAST,
        OSSO_ABOOK_NAME_ORDER_NICK
} OssoABookNameOrder;

Preferred order for name components for sorting and display.

OSSO_ABOOK_NAME_ORDER_FIRST Display given name first
OSSO_ABOOK_NAME_ORDER_LAST Display family name first
OSSO_ABOOK_NAME_ORDER_NICK Display nickname only

osso_abook_name_order_from_name ()

const GEnumValue*   osso_abook_name_order_from_name     (const char *name);

Looks up the description of the OssoABookNameOrder member with that full name.

name : the full name of a OssoABookNameOrder member
Returns : A GEnumValue when name is valid, NULL otherwise.

osso_abook_name_order_from_nick ()

const GEnumValue*   osso_abook_name_order_from_nick     (const char *nick);

Looks up the description of the OssoABookNameOrder member with that nick name.

nick : the nick name of a OssoABookNameOrder member
Returns : A GEnumValue when nick is valid, NULL otherwise.

osso_abook_name_order_get_name ()

const char*         osso_abook_name_order_get_name      (OssoABookNameOrder value);

Retreives the full name of a OssoABookNameOrder member.

value : the a OssoABookNameOrder member
Returns : The full name for value, or NULL if there is no such member.

osso_abook_name_order_get_nick ()

const char*         osso_abook_name_order_get_nick      (OssoABookNameOrder value);

Retreives the nick name of a OssoABookNameOrder member.

value : the a OssoABookNameOrder member
Returns : The nick name for value, or NULL if there is no such member.

OSSO_ABOOK_VCA_OSSO_CONTACT_STATE

#define OSSO_ABOOK_VCA_OSSO_CONTACT_STATE       "X-OSSO-CONTACT-STATE"


OSSO_ABOOK_VCA_OSSO_LAST_USED

#define OSSO_ABOOK_VCA_OSSO_LAST_USED           "X-OSSO-LAST-USED"


OSSO_ABOOK_VCA_OSSO_MASTER_UID

#define OSSO_ABOOK_VCA_OSSO_MASTER_UID          "X-OSSO-MASTER-UID"

VCard attribute name for storing the set of master contact UIDs.


OSSO_ABOOK_VCA_TELEPATHY_BLOCKED

#define OSSO_ABOOK_VCA_TELEPATHY_BLOCKED        "X-TELEPATHY-BLOCKED"

VCard attribute name for reporting the contact's blocking state. Valid values: yes, no, local-pending, remote-pending


OSSO_ABOOK_VCA_TELEPATHY_CAPABILITIES

#define OSSO_ABOOK_VCA_TELEPATHY_CAPABILITIES   "X-TELEPATHY-CAPABILITIES"

VCard attribute name for reporting the contact's communication capabilities. Valid values: {text,audio,video}*


OSSO_ABOOK_VCA_TELEPATHY_HANDLE

#define OSSO_ABOOK_VCA_TELEPATHY_HANDLE         "X-TELEPATHY-HANDLE"

VCard attribute name for reporting the contact's Telepathy handle.


OSSO_ABOOK_VCA_TELEPATHY_PRESENCE

#define OSSO_ABOOK_VCA_TELEPATHY_PRESENCE       "X-TELEPATHY-PRESENCE"

VCard attribute name for reporting the contact's presence state. Valid values: [detailed-name;]{available,away,...}[;custom-message]


OSSO_ABOOK_VCA_TELEPATHY_PUBLISHED

#define OSSO_ABOOK_VCA_TELEPATHY_PUBLISHED      "X-TELEPATHY-PUBLISHED"

VCard attribute name for reporting the contact's publication state. Valid values: yes, no, local-pending, remote-pending


OSSO_ABOOK_VCA_TELEPATHY_SUBSCRIBED

#define OSSO_ABOOK_VCA_TELEPATHY_SUBSCRIBED     "X-TELEPATHY-SUBSCRIBED"

VCard attribute name for reporting the contact's subscription state. Valid values: yes, no, local-pending, remote-pending


OSSO_ABOOK_VCP_OSSO_BOUND

#define OSSO_ABOOK_VCP_OSSO_BOUND               "X-OSSO-BOUND"


OSSO_ABOOK_VCP_OSSO_FIELD_STATE

#define OSSO_ABOOK_VCP_OSSO_FIELD_STATE         "X-OSSO-FIELD-STATE"