![]() |
![]() |
![]() |
Osso Addressbook Reference Manual | ![]() |
---|---|---|---|---|
#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);
OssoABookContact implements OssoABookAvatar, OssoABookPresence and OssoABookCaps.
This module provides the OssoABookContact class, but also a collection of utility functions which operate on plain EContact objects.
#define OSSO_ABOOK_VCA_GENDER "X-GENDER"
VCard attribute name for storing the gender.
#define OSSO_ABOOK_VCA_OSSO_MASTER_UID "X-OSSO-MASTER-UID"
VCard attribute name for storing the set of master contact UIDs.
#define OSSO_ABOOK_VCA_TELEPATHY_HANDLE "X-TELEPATHY-HANDLE"
VCard attribute name for reporting the contact's Telepathy handle.
#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]
#define OSSO_ABOOK_VCA_TELEPATHY_CAPABILITIES "X-TELEPATHY-CAPABILITIES"
VCard attribute name for reporting the contact's communication capabilities. Valid values: {text,audio,video}*
#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
#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
#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
#define OSSO_ABOOK_VCP_OSSO_READONLY "X-OSSO-READONLY"
This paramter marks a vCard attribute as read-only. Valid values: yes, no
#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)
#define OSSO_ABOOK_DTMF_CHARS "PpWwXx"
Set of characters starting a DTMF sequence.
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;
void (*OssoABookContactWriteToFileCb) (OssoABookContact *contact, GFile *file, const GError *error, gpointer user_data);
void (*OssoABookContactActionStartCb) (const GError *error, GtkWindow *parent, gpointer user_data);
typedef enum { OSSO_ABOOK_CONTACT_ACTION_ERROR_SUCCESS, OSSO_ABOOK_CONTACT_ACTION_ERROR_ADDRESS, } OssoABookContactActionError;
typedef struct _OssoABookContact OssoABookContact;
All the fields of this structure are private to the object's implementation and should never be accessed directly.
OssoABookContact* osso_abook_contact_new (void);
Create a new and still empty OssoABookContact.
Returns : | A newly allocated OssoABookContact. |
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. |
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. |
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.
|
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.
|
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. |
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
|
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.
|
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 |
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);
Associates a McProfile this vcard attribute.
attribute : |
the EVCardAttribute |
profile_name : |
the unique McProfile name |
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.
|
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.
|
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.
|
gboolean osso_abook_contact_has_roster_contacts (OssoABookContact *master_contact);
master_contact : |
a OssoABookContact |
Returns : | TRUE if the OssoABookContact has associated roster contacts.
|
GList* osso_abook_contact_find_roster_contacts_for_attribute (OssoABookContact *master_contact, EVCardAttribute *attribute);
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. |
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.
|
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. |
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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 .
|
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 .
|
const char* osso_abook_contact_get_bound_name (OssoABookContact *contact);
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.
|
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 |
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);
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.
|
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. |
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 |
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 |
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 |
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. |
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.
|
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.
|
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.
|
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);
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.
|
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 |
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 |
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. |
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 |
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);
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 .
|
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.
|
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 .
|
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 |
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);
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. |
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 |
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);
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 |
void osso_abook_contact_delete_many (GList *contacts, EBook *book, GtkWindow *window);
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.
|
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
|
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
|
void osso_abook_contact_vcard_clean (EContact *contact);
Clean a contact, by removing all empty fields.
contact : |
An EContact |
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
|
"contact-attached"
signalvoid 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. |
"contact-detached"
signalvoid 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. |
"reset"
signalvoid 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. |