OssoABookContact

OssoABookContact — Rich representation of addressbook contacts.

Synopsis

#define             OSSO_ABOOK_VCA_GENDER
#define             OSSO_ABOOK_VCA_OSSO_MASTER_UID
#define             OSSO_ABOOK_VCA_TELEPATHY_HANDLE
#define             OSSO_ABOOK_VCA_TELEPATHY_PRESENCE
#define             OSSO_ABOOK_VCA_TELEPATHY_CAPABILITIES
#define             OSSO_ABOOK_VCA_TELEPATHY_BLOCKED
#define             OSSO_ABOOK_VCA_TELEPATHY_SUBSCRIBED
#define             OSSO_ABOOK_VCA_TELEPATHY_PUBLISHED
#define             OSSO_ABOOK_VCP_OSSO_READONLY
#define             OSSO_ABOOK_VCP_OSSO_VALID
#define             OSSO_ABOOK_DTMF_CHARS
#define             OSSO_ABOOK_HOME_APPLET_PREFIX
enum                OssoABookContactAction;
void                (*OssoABookContactWriteToFileCb)    (OssoABookContact *contact,
                                                         GFile *file,
                                                         const GError *error,
                                                         gpointer user_data);
void                (*OssoABookContactActionStartCb)    (const GError *error,
                                                         GtkWindow *parent,
                                                         gpointer user_data);
enum                OssoABookContactActionError;
                    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);
return              e_contact_get_const                 ();
const char*         osso_abook_contact_get_persistent_uid
                                                        (OssoABookContact *contact);
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_set_value        (EContact *contact,
                                                         const char *attr_name,
                                                         const char *value);
gboolean            osso_abook_contact_add_value        (EContact *contact,
                                                         const char *attr_name,
                                                         GCompareFunc value_check,
                                                         const char *value);
void                osso_abook_contact_remove_value     (EContact *contact,
                                                         const char *attr_name,
                                                         const char *value);
gboolean            osso_abook_contact_find_matching_values
                                                        (EContact *contact_a,
                                                         EContact *contact_b,
                                                         const char *attr_name,
                                                         GList **values);
void                osso_abook_contact_reset            (OssoABookContact *contact,
                                                         OssoABookContact *replacement);
void                osso_abook_contact_attribute_set_readonly
                                                        (EVCardAttribute *attribute,
                                                         gboolean readonly);
gboolean            osso_abook_contact_attribute_is_readonly
                                                        (EVCardAttribute *attribute);
void                osso_abook_contact_attribute_set_profile
                                                        (EVCardAttribute *attribute,
                                                         const char *profile_name);
McProfile*          osso_abook_contact_attribute_get_profile
                                                        (EVCardAttribute *attribute);
gboolean            osso_abook_contact_attach           (OssoABookContact *master_contact,
                                                         OssoABookContact *roster_contact);
gboolean            osso_abook_contact_detach           (OssoABookContact *master_contact,
                                                         OssoABookContact *roster_contact);
gboolean            osso_abook_contact_has_roster_contacts
                                                        (OssoABookContact *master_contact);
GList*              osso_abook_contact_find_roster_contacts_for_attribute
                                                        (OssoABookContact *master_contact,
                                                         EVCardAttribute *attribute);
char*               osso_abook_create_temporary_uid     (void);
gboolean            osso_abook_is_temporary_uid         (const char *uid);
GList*              osso_abook_contact_get_master_uids  (OssoABookContact *roster_contact);
gboolean            osso_abook_contact_add_master_uid   (OssoABookContact *roster_contact,
                                                         const char *master_uid);
gboolean            osso_abook_contact_remove_master_uid
                                                        (OssoABookContact *roster_contact,
                                                         const char *master_uid);
gboolean            osso_abook_contact_is_temporary     (OssoABookContact *contact);
gboolean            osso_abook_contact_is_roster_contact
                                                        (OssoABookContact *contact);
gboolean            osso_abook_contact_is_sim_contact   (OssoABookContact *contact);
OssoABookRoster*    osso_abook_contact_get_roster       (OssoABookContact *contact);
McAccount*          osso_abook_contact_get_account      (OssoABookContact *contact);
McProfile*          osso_abook_contact_get_profile      (OssoABookContact *contact);
const char*         osso_abook_contact_get_vcard_field  (OssoABookContact *contact);
const char*         osso_abook_contact_get_bound_name   (OssoABookContact *contact);
gboolean            osso_abook_contact_has_invalid_username
                                                        (OssoABookContact *contact);
void                osso_abook_contact_set_roster       (OssoABookContact *contact,
                                                         OssoABookRoster *roster);
gboolean            osso_abook_contact_matches_phone_number
                                                        (OssoABookContact *contact,
                                                         const char *phone_number,
                                                         gboolean fuzzy_match);
gboolean            osso_abook_contact_matches_username (OssoABookContact *contact,
                                                         const char *username,
                                                         const char *vcard_field,
                                                         const char *account_name);
void                osso_abook_contact_set_presence     (OssoABookContact *contact,
                                                         guint type,
                                                         const gchar *status,
                                                         const gchar *message);
gboolean            osso_abook_contact_photo_is_user_selected
                                                        (OssoABookContact *contact);
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);
void                osso_abook_contact_set_photo_data   (OssoABookContact *contact,
                                                         gconstpointer data,
                                                         gsize len,
                                                         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         (OssoABookContact *contact);
const char*         osso_abook_contact_get_display_name (OssoABookContact *contact);
void                osso_abook_contact_get_name_components
                                                        (EContact *contact,
                                                         OssoABookNameOrder order,
                                                         gboolean strict,
                                                         char **primary_out,
                                                         char **secondary_out);
const char*         osso_abook_contact_get_name_with_order
                                                        (OssoABookContact *contact,
                                                         OssoABookNameOrder order);
gboolean            osso_abook_contact_action_start     (OssoABookContactAction action,
                                                         OssoABookContact *contact,
                                                         EVCardAttribute *attribute,
                                                         McAccount *account,
                                                         GtkWindow *parent);
gboolean            osso_abook_contact_action_start_with_callback
                                                        (OssoABookContactAction action,
                                                         OssoABookContact *contact,
                                                         EVCardAttribute *attribute,
                                                         McAccount *account,
                                                         GtkWindow *parent,
                                                         OssoABookContactActionStartCb callback,
                                                         gpointer callback_data);
char*               osso_abook_contact_to_string        (OssoABookContact *contact,
                                                         EVCardFormat format,
                                                         gboolean inline_avatar);
char*               osso_abook_contact_get_locale       (OssoABookContact *contact);
char*               osso_abook_contact_get_basename     (OssoABookContact *contact,
                                                         gboolean strict);
void                osso_abook_contact_write_to_file    (OssoABookContact *contact,
                                                         EVCardFormat format,
                                                         gboolean inline_avatar,
                                                         gboolean strict_filename,
                                                         GFile *parent_file,
                                                         OssoABookContactWriteToFileCbcallback ,
                                                         gpointer user_data);
gboolean            osso_abook_contact_shortcut_exists  (OssoABookContact *contact,
                                                         GSList **ret_list);
gboolean            osso_abook_contact_shortcut_create  (OssoABookContact *contact);
OssoABookContact*   osso_abook_contact_fetch_roster_info
                                                        (OssoABookContact *contact);
const char**        osso_abook_contact_get_collate_keys (OssoABookContact *contact,
                                                         OssoABookNameOrder order);
int                 osso_abook_contact_collate          (OssoABookContact *a,
                                                         OssoABookContact *b,
                                                         OssoABookNameOrder order);
int                 osso_abook_contact_uid_compare      (OssoABookContact *a,
                                                         OssoABookContact *b);
guint               osso_abook_contact_async_add        (OssoABookContact *contact,
                                                         EBook *book,
                                                         EBookIdCallback callback,
                                                         gpointer user_data);
guint               osso_abook_contact_async_commit     (OssoABookContact *contact,
                                                         EBook *book,
                                                         EBookCallback callback,
                                                         gpointer user_data);
void                osso_abook_contact_commit           (OssoABookContact *contact,
                                                         gboolean create,
                                                         EBook *book,
                                                         GtkWindow *window);
void                osso_abook_contact_accept           (OssoABookContact *contact,
                                                         OssoABookContact *master,
                                                         GtkWindow *parent);
void                osso_abook_contact_accept_for_uid   (OssoABookContact *contact,
                                                         const char *master_uid,
                                                         GtkWindow *parent);
void                osso_abook_contact_async_accept     (OssoABookContact *contact,
                                                         const char *master_uid,
                                                         EBookIdCallback callback,
                                                         gpointer user_data);
void                osso_abook_contact_reject           (OssoABookContact *contact,
                                                         GtkWindow *parent);
void                osso_abook_contact_reject_for_uid   (OssoABookContact *contact,
                                                         const char *master_uid,
                                                         GtkWindow *parent);
gboolean            osso_abook_contact_delete           (OssoABookContact *contact,
                                                         EBook *book,
                                                         GtkWindow *window);
void                osso_abook_contact_delete_many      (GList *contacts,
                                                         EBook *book,
                                                         GtkWindow *window);
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);
void                osso_abook_contact_vcard_clean      (EContact *contact);
gboolean            osso_abook_contact_has_valid_name   (OssoABookContact *contact);

Object Hierarchy

  GObject
   +----EVCard
         +----EContact
               +----OssoABookContact
                     +----OssoABookGconfContact

Implemented Interfaces

OssoABookContact implements OssoABookAvatar, OssoABookPresence and OssoABookCaps.

Properties

  "display-name"             gchar*                : Read

Signals

  "contact-attached"                               : Run First
  "contact-detached"                               : Run First
  "reset"                                          : Run First

Description

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

Details

OSSO_ABOOK_VCA_GENDER

#define OSSO_ABOOK_VCA_GENDER          "X-GENDER"

VCard attribute name for storing the gender.


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_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_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_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_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_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_VCP_OSSO_READONLY

#define OSSO_ABOOK_VCP_OSSO_READONLY            "X-OSSO-READONLY"

This paramter marks a vCard attribute as read-only. Valid values: yes, no


OSSO_ABOOK_VCP_OSSO_VALID

#define OSSO_ABOOK_VCP_OSSO_VALID               "X-OSSO-VALID"

VCard parameter name for marking an attribute as known-invalid (eg, after confirming with the server that a username is invalid/missing). Valid values: yes, no, <parameter missing> (validity unconfirmed)


OSSO_ABOOK_DTMF_CHARS

#define OSSO_ABOOK_DTMF_CHARS                   "PpWwXx"

Set of characters starting a DTMF sequence.


OSSO_ABOOK_HOME_APPLET_PREFIX

#define OSSO_ABOOK_HOME_APPLET_PREFIX           "osso-abook-applet-"

enum OssoABookContactAction

typedef enum {
        OSSO_ABOOK_CONTACT_ACTION_NONE,
        OSSO_ABOOK_CONTACT_ACTION_TEL,
        OSSO_ABOOK_CONTACT_ACTION_SMS,
        OSSO_ABOOK_CONTACT_ACTION_CHATTO,
        OSSO_ABOOK_CONTACT_ACTION_VOIPTO,
        OSSO_ABOOK_CONTACT_ACTION_VOIPTO_AUDIO,
        OSSO_ABOOK_CONTACT_ACTION_VOIPTO_VIDEO,
        OSSO_ABOOK_CONTACT_ACTION_DATE,
        OSSO_ABOOK_CONTACT_ACTION_MAILTO,
        OSSO_ABOOK_CONTACT_ACTION_MAP,
        OSSO_ABOOK_CONTACT_ACTION_URL,
        OSSO_ABOOK_CONTACT_ACTION_CREATE_ACCOUNT,
        OSSO_ABOOK_CONTACT_ACTION_BIND,
        OSSO_ABOOK_CONTACT_ACTION_CHATTO_ERROR,
        OSSO_ABOOK_CONTACT_ACTION_VOIPTO_ERROR,
} OssoABookContactAction;

OssoABookContactWriteToFileCb ()

void                (*OssoABookContactWriteToFileCb)    (OssoABookContact *contact,
                                                         GFile *file,
                                                         const GError *error,
                                                         gpointer user_data);

OssoABookContactActionStartCb ()

void                (*OssoABookContactActionStartCb)    (const GError *error,
                                                         GtkWindow *parent,
                                                         gpointer user_data);

enum OssoABookContactActionError

typedef enum {
        OSSO_ABOOK_CONTACT_ACTION_ERROR_SUCCESS,
        OSSO_ABOOK_CONTACT_ACTION_ERROR_ADDRESS,
} OssoABookContactActionError;

OssoABookContact

typedef struct _OssoABookContact 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.

e_contact_get_const ()

return              e_contact_get_const                 ();

osso_abook_contact_get_persistent_uid ()

const char*         osso_abook_contact_get_persistent_uid
                                                        (OssoABookContact *contact);

Retrieves the persistent UID of this contact which should be stored in databases and such.

contact : a OssoABookContact
Returns : The persistent UID for this contact, or NULL if this contact isn't persistent.

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_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_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_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_find_matching_values ()

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

osso_abook_contact_reset ()

void                osso_abook_contact_reset            (OssoABookContact *contact,
                                                         OssoABookContact *replacement);

osso_abook_contact_attribute_set_readonly ()

void                osso_abook_contact_attribute_set_readonly
                                                        (EVCardAttribute *attribute,
                                                         gboolean readonly);

osso_abook_contact_attribute_is_readonly ()

gboolean            osso_abook_contact_attribute_is_readonly
                                                        (EVCardAttribute *attribute);

osso_abook_contact_attribute_set_profile ()

void                osso_abook_contact_attribute_set_profile
                                                        (EVCardAttribute *attribute,
                                                         const char *profile_name);

Associates a McProfile this vcard attribute.

attribute : the EVCardAttribute
profile_name : the unique McProfile name

osso_abook_contact_attribute_get_profile ()

McProfile*          osso_abook_contact_attribute_get_profile
                                                        (EVCardAttribute *attribute);

Find the McProfile associated with this vcard attribute. The returned object's reference count is incremented.

attribute : the EVCardAttribute
Returns : The first associated McProfile or NULL. Call g_object_unref() on the returned object when done.

osso_abook_contact_attach ()

gboolean            osso_abook_contact_attach           (OssoABookContact *master_contact,
                                                         OssoABookContact *roster_contact);

Attaches a roster contact to some master contact, so that the master contact can utilize presence information from that roster contact to estimate its own presence state.

master_contact : a OssoABookContact
roster_contact : the OssoABookContact to attach
Returns : TRUE when the contact was attached, and FALSE otherwise.

osso_abook_contact_detach ()

gboolean            osso_abook_contact_detach           (OssoABookContact *master_contact,
                                                         OssoABookContact *roster_contact);

Detaches a roster contact from some master contact, so that the master contact won't utilize presence information from that roster contact to estimate its own presence state anymore.

master_contact : a OssoABookContact
roster_contact : the OssoABookContact to detach
Returns : TRUE when the contact was detached, and FALSE otherwise.

osso_abook_contact_has_roster_contacts ()

gboolean            osso_abook_contact_has_roster_contacts
                                                        (OssoABookContact *master_contact);

master_contact : a OssoABookContact
Returns : TRUE if the OssoABookContact has associated roster contacts.

osso_abook_contact_find_roster_contacts_for_attribute ()

GList*              osso_abook_contact_find_roster_contacts_for_attribute
                                                        (OssoABookContact *master_contact,
                                                         EVCardAttribute *attribute);

osso_abook_create_temporary_uid ()

char*               osso_abook_create_temporary_uid     (void);

Creates a new temporary UID. The created UID is unique within this process.

Returns : A newly allocated UID string.

osso_abook_is_temporary_uid ()

gboolean            osso_abook_is_temporary_uid         (const char *uid);

Checks if uid was generated by osso_abook_create_temporary_uid().

uid : the UID to check
Returns : TRUE when uid is temporary, 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_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_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_temporary ()

gboolean            osso_abook_contact_is_temporary     (OssoABookContact *contact);

Checks if the contact is a temporary contact which isn't stored in any addressbook yet.

contact : a OssoABookContact
Returns : TRUE when contact is temporary, 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_is_sim_contact ()

gboolean            osso_abook_contact_is_sim_contact   (OssoABookContact *contact);

Checks if the contact originates from some SIM card.

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

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_profile ()

McProfile*          osso_abook_contact_get_profile      (OssoABookContact *contact);

Queries the McProfile of the OssoABookRoster this contact comes from.

contact : a OssoABookContact
Returns : The contact's McProfile, or NULL.

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_get_bound_name ()

const char*         osso_abook_contact_get_bound_name   (OssoABookContact *contact);

osso_abook_contact_has_invalid_username ()

gboolean            osso_abook_contact_has_invalid_username
                                                        (OssoABookContact *contact);

contact : A roster OssoABookContact
Returns : TRUE if the roster contact's username has been confirmed invalid. Note that a return value of FALSE may mean that the validity has not been confirmed.

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_matches_phone_number ()

gboolean            osso_abook_contact_matches_phone_number
                                                        (OssoABookContact *contact,
                                                         const char *phone_number,
                                                         gboolean fuzzy_match);

osso_abook_contact_matches_username ()

gboolean            osso_abook_contact_matches_username (OssoABookContact *contact,
                                                         const char *username,
                                                         const char *vcard_field,
                                                         const char *account_name);

osso_abook_contact_set_presence ()

void                osso_abook_contact_set_presence     (OssoABookContact *contact,
                                                         guint type,
                                                         const gchar *status,
                                                         const gchar *message);

osso_abook_contact_photo_is_user_selected ()

gboolean            osso_abook_contact_photo_is_user_selected
                                                        (OssoABookContact *contact);

contact : A master OssoABookContact
Returns : TRUE if the contact's photo/avatar was user-selected (as opposed to being retrieved from one of the contact's roster contacts), otherwise FALSE.

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_set_photo_data ()

void                osso_abook_contact_set_photo_data   (OssoABookContact *contact,
                                                         gconstpointer data,
                                                         gsize len,
                                                         EBook *book,
                                                         GtkWindow *window);

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

contact : An OssoABookContact
data : The avatar data
len : The size of data
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::avatar-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 ()

const char*         osso_abook_contact_get_name         (OssoABookContact *contact);

Retrieves the text used to represent the name of contact internally. This string is formed according to the "/apps/osso-addressbook/name_order" 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. The returned value can be NULL or an empty string. 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);

Retrieves the text used to display the name of contact. This string is formed according to the "/apps/osso-addressbook/name_order" 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 never NULL or an empty string. This string is owned by libosso-abook and should not be freed.

osso_abook_contact_get_name_components ()

void                osso_abook_contact_get_name_components
                                                        (EContact *contact,
                                                         OssoABookNameOrder order,
                                                         gboolean strict,
                                                         char **primary_out,
                                                         char **secondary_out);

osso_abook_contact_get_name_with_order ()

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

Retrieves 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_action_start ()

gboolean            osso_abook_contact_action_start     (OssoABookContactAction action,
                                                         OssoABookContact *contact,
                                                         EVCardAttribute *attribute,
                                                         McAccount *account,
                                                         GtkWindow *parent);

Simplified version of osso_abook_contact_action_start_with_callback() for actions that don't require a callback. See osso_abook_contact_action_start_with_callback() for more information.

action : The OssoABookContactAction action type to start
contact : OssoABookContact for the value(s) associated with the action
attribute : EVCardAttribute for the value(s) associated with the action
account : McAccount of the account associated with the action
callback : GCallback to call with the result
callback_data : data to pass into the callback
parent : The parent GtkWindow to make any dialogs transient to

osso_abook_contact_action_start_with_callback ()

gboolean            osso_abook_contact_action_start_with_callback
                                                        (OssoABookContactAction action,
                                                         OssoABookContact *contact,
                                                         EVCardAttribute *attribute,
                                                         McAccount *account,
                                                         GtkWindow *parent,
                                                         OssoABookContactActionStartCb callback,
                                                         gpointer callback_data);

Start an action for a contact. If the action is initiated successfully, both this function will return TRUE and the GError argument to callback will be NULL.

action : The OssoABookContactAction action type to start
contact : OssoABookContact for the value(s) associated with the action
attribute : EVCardAttribute for the value(s) associated with the action
account : McAccount of the account associated with the action
callback : GCallback to call with the result
callback_data : data to pass into the callback
parent : The parent GtkWindow to make any dialogs transient to

osso_abook_contact_to_string ()

char*               osso_abook_contact_to_string        (OssoABookContact *contact,
                                                         EVCardFormat format,
                                                         gboolean inline_avatar);

Creates a string representation of the contact.

contact : an OssoABookContact
format : output format
inline_avatar : if TRUE the avatar image (if the contact has one) will be inlined.
Returns : a newly allocated vcard string, or NULL.

osso_abook_contact_get_locale ()

char*               osso_abook_contact_get_locale       (OssoABookContact *contact);

osso_abook_contact_get_basename ()

char*               osso_abook_contact_get_basename     (OssoABookContact *contact,
                                                         gboolean strict);

Creates the basename component that can be use for creating a filename for this contact (e.g. "basename.vcf" or "basename (n).vcf").

Return: A newly allocated string.

contact : the OssoABookContact
strict : allow only safe characters from ASCII codeset

osso_abook_contact_write_to_file ()

void                osso_abook_contact_write_to_file    (OssoABookContact *contact,
                                                         EVCardFormat format,
                                                         gboolean inline_avatar,
                                                         gboolean strict_filename,
                                                         GFile *parent_file,
                                                         OssoABookContactWriteToFileCbcallback ,
                                                         gpointer user_data);

osso_abook_contact_shortcut_exists ()

gboolean            osso_abook_contact_shortcut_exists  (OssoABookContact *contact,
                                                         GSList **ret_list);

osso_abook_contact_shortcut_create ()

gboolean            osso_abook_contact_shortcut_create  (OssoABookContact *contact);

osso_abook_contact_fetch_roster_info ()

OssoABookContact*   osso_abook_contact_fetch_roster_info
                                                        (OssoABookContact *contact);

This function retrieves all roster contacts of this master contact, and adds ContactInfo fields of these roster contacts to a newly allocated OssoABookContact object after removing duplication.

contact : either a local master contact or a temporary master contact
Returns : a newly allocated OssoABookContact object which consists of attributes of ContactInfo fields (but not master contact fields), or NULL.

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,
                                                         OssoABookContact *b,
                                                         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_uid_compare ()

int                 osso_abook_contact_uid_compare      (OssoABookContact *a,
                                                         OssoABookContact *b);

Compares two contacts by their UID preserving those properties:

1. old contacts are listed before new contacts 2. file-backend contacts are listed before artificial contacts

First property is guaranteed, because the file-backend and the aggregator generate auto-incrementing UIDs which are recognized by the strverscmp() function.

Second property is guaranteed, because strverscmp() behaves like plain strcmp() unless numbers have common prefix. Digits have a smaller ASCII code than letters, therefore file-backend UIDs which are plain numbers are listed before aggregator generated UIDs have the prefix "osso-abook-".

a : first OssoABookContact
b : second OssoABookContact

osso_abook_contact_async_add ()

guint               osso_abook_contact_async_add        (OssoABookContact *contact,
                                                         EBook *book,
                                                         EBookIdCallback callback,
                                                         gpointer user_data);

osso_abook_contact_async_commit ()

guint               osso_abook_contact_async_commit     (OssoABookContact *contact,
                                                         EBook *book,
                                                         EBookCallback callback,
                                                         gpointer user_data);

Applies the changes made to contact to the stored version in book without blocking. if async_commit virtual method is redefined the vcard could be saved on another place than the book. OssoABookSelfContact saves the vcard to a gconf key.

contact : a OssoAbookContact
book : an EBook
callback : function to call when the operation finishes
user_data : data to pass to callback function
Returns : TRUE if the operation was started, FALSE otherwise.

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_accept ()

void                osso_abook_contact_accept           (OssoABookContact *contact,
                                                         OssoABookContact *master,
                                                         GtkWindow *parent);

osso_abook_contact_accept_for_uid ()

void                osso_abook_contact_accept_for_uid   (OssoABookContact *contact,
                                                         const char *master_uid,
                                                         GtkWindow *parent);

osso_abook_contact_async_accept ()

void                osso_abook_contact_async_accept     (OssoABookContact *contact,
                                                         const char *master_uid,
                                                         EBookIdCallback callback,
                                                         gpointer user_data);

osso_abook_contact_reject ()

void                osso_abook_contact_reject           (OssoABookContact *contact,
                                                         GtkWindow *parent);

osso_abook_contact_reject_for_uid ()

void                osso_abook_contact_reject_for_uid   (OssoABookContact *contact,
                                                         const char *master_uid,
                                                         GtkWindow *parent);

osso_abook_contact_delete ()

gboolean            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);

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_vcard_clean ()

void                osso_abook_contact_vcard_clean      (EContact *contact);

Clean a contact, by removing all empty fields.

contact : An EContact

osso_abook_contact_has_valid_name ()

gboolean            osso_abook_contact_has_valid_name   (OssoABookContact *contact);

Checks if the contact contains an attribute that can be used as a display name.

contact : An OssoABookContact
Returns : TRUE if the contact contains an attribute that can be used as a display name, FALSE otherwise

Property Details

The "display-name" property

  "display-name"             gchar*                : Read

The text used to display the name of the contact.

Default value: NULL

Signal Details

The "contact-attached" signal

void                user_function                      (OssoABookContact *master_contact,
                                                        OssoABookContact *roster_contact,
                                                        gpointer          user_data)           : Run First

This signal is emitted when a roster contact is associated with ("attached to") a master contact. At this point, master_contact's attributes may have changed, so any cached data should be re-loaded.

master_contact : a master OssoABookContact
roster_contact : the roster OssoABookContact which was attached to master_contact
user_data : user data set when the signal handler was connected.

The "contact-detached" signal

void                user_function                      (OssoABookContact *master_contact,
                                                        OssoABookContact *roster_contact,
                                                        gpointer          user_data)           : Run First

This signal is emitted when a roster contact is no longer associated with ("detached from") a master contact. At this point, master_contact's attributes may have changed, so any cached data should be re-loaded.

master_contact : a master OssoABookContact that the roster contact was attached to
roster_contact : the roster OssoABookContact which was attached to master_contact
user_data : user data set when the signal handler was connected.

The "reset" signal

void                user_function                      (OssoABookContact *master_contact,
                                                        gpointer          user_data)           : Run First

This signal is emitted when a contact's attributes are completely re-written. At this point, master_contact's attributes may have changed, so any cached data should be re-loaded.

master_contact : a master OssoABookContact
user_data : user data set when the signal handler was connected.