![]() |
![]() |
![]() |
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); GList* osso_abook_contact_get_attributes (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_get_roster_contacts (OssoABookContact *master_contact); GList* osso_abook_contact_find_roster_contacts (OssoABookContact *master_contact, const char *username, const char *vcard_field); GList* osso_abook_contact_find_roster_contacts_for_account (OssoABookContact *master_contact, const char *username, const char *account_id); 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_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 OssoABookPresence, OssoABookAvatar 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;
OSSO_ABOOK_CONTACT_ACTION_NONE: no actions supported OSSO_ABOOK_CONTACT_ACTION_TEL: Start a telephone call OSSO_ABOOK_CONTACT_ACTION_SMS: Send an SMS message OSSO_ABOOK_CONTACT_ACTION_CHATTO: Start a text chat OSSO_ABOOK_CONTACT_ACTION_VOIPTO: Start a VoIP call OSSO_ABOOK_CONTACT_ACTION_VOIPTO_AUDIO: Start a VoIP audio call OSSO_ABOOK_CONTACT_ACTION_VOIPTO_VIDEO: Start a VoIP video call OSSO_ABOOK_CONTACT_ACTION_DATE: Open a date in the calendar OSSO_ABOOK_CONTACT_ACTION_MAILTO: Send an email OSSO_ABOOK_CONTACT_ACTION_MAP: Open location in map application OSSO_ABOOK_CONTACT_ACTION_URL: Open URL in the browser OSSO_ABOOK_CONTACT_ACTION_CREATE_ACCOUNT: create an IM or VoIP account OSSO_ABOOK_CONTACT_ACTION_BIND: binding an IM or VoIP username to an existing account OSSO_ABOOK_CONTACT_ACTION_CHATTO_ERROR: Display an error for invalid IM username OSSO_ABOOK_CONTACT_ACTION_VOIPTO_ERROR: Display an error for invalid VoIP username
Actions that are supported by different fields of an OssoABookContact
void (*OssoABookContactWriteToFileCb) (OssoABookContact *contact, GFile *file, const GError *error, gpointer user_data);
A function that will be called when osso_abook_contact_write_to_file()
is
complete
contact : |
the OssoABookContact that was written |
file : |
the file that was written |
error : |
possible error value, or NULL on success
|
user_data : |
additional user_data |
void (*OssoABookContactActionStartCb) (const GError *error, GtkWindow *parent, gpointer user_data);
A function that will be called after an action has been started to report the status of the action
error : |
possible error value, or NULL on success
|
parent : |
a parent GtkWindow |
user_data : |
additional 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. |
GList* osso_abook_contact_get_attributes (EContact *contact, const char *attr_name);
Retrieves the list of attributes with a name matching attr_name
.
contact : |
a EContact |
attr_name : |
the attribute name |
Returns : | A EVCardAttribute list. The list elements are owned by the contact
and must not be freed. The list itself must be freed with g_list_free()
after usage.
|
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
. If value_check
is
non-NULL
, it will be called to compare value
to each of the existing values
of the attribute. If value_check
returns 0 for one of these comparisons,
the value will not be added. This allows you to easily avoid adding
duplicate values if desired.
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);
Remove all writable attributes from contact
and replace them with the
attributes specified in replacement
contact : |
a OssoABookContact |
replacement : |
an a contact to use as a replacement |
void osso_abook_contact_attribute_set_readonly (EVCardAttribute *attribute, gboolean readonly);
If readonly
is TRUE
, marks attribute
as read-only, else marks it as
writeable
attribute : |
a EVCardAttribute |
readonly : |
whether attribute should be read-only or not
|
gboolean osso_abook_contact_attribute_is_readonly (EVCardAttribute *attribute);
Checks whether attribute
is read-only or not
attribute : |
a EVCardAttribute |
Returns : | TRUE if attribute is read-only, else FALSE .
|
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_get_roster_contacts (OssoABookContact *master_contact);
Retrieves the current list of roster contacts attached to this master 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.
|
GList* osso_abook_contact_find_roster_contacts (OssoABookContact *master_contact, const char *username, const char *vcard_field);
Finds the roster contacts attached to this contact matching the passed
account properties (user_name
, vcard_field
).
master_contact : |
a OssoABookContact |
user_name : |
the roster contact's user name, or NULL
|
vcard_field : |
the roster contact's user name, or NULL
|
Returns : | The list of matching roster contacts. 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.
|
GList* osso_abook_contact_find_roster_contacts_for_account (OssoABookContact *master_contact, const char *username, const char *account_id);
Finds the roster contacts attached to this contact matching the passed
account properties (user_name
, account_id
).
master_contact : |
a OssoABookContact |
user_name : |
the roster contact's user name, or NULL
|
account_id : |
the roster contact's user name, or NULL
|
Returns : | The list of matching roster contacts. 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.
|
GList* osso_abook_contact_find_roster_contacts_for_attribute (OssoABookContact *master_contact, EVCardAttribute *attribute);
Finds the roster contacts attached to this contact which match the specified
attribute
. For example, the following vcard field will match all roster
contacts that have a google talk username of foobar.com
:
X-JABBER;TYPE="google-talk":foobar.com
See osso_abook_contact_real_find_roster_contacts()
for more information about
matching the vcard field.
master_contact : |
a OssoABookContact |
attribute : |
an attribute containing a roster contact username |
Returns : | The list of matching roster contacts. 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.
|
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 and its contents are 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);
Gets the bound name for contact
. A bound name is a normalized version of
the user-specified username for a contact.
contact : |
a OssoABookContact |
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);
Checks whether contact
contains a phone number that matches phone_number
.
For details about fuzzy_match
, see osso_abook_query_phone_number()
contact : |
a OssoABookContact |
phone_number : |
a phone number |
fuzzy_match : |
whether fuzzy matching is desired |
Returns : | TRUE if contact has the specified phone number, else FALSE
|
gboolean osso_abook_contact_matches_username (OssoABookContact *contact, const char *username, const char *vcard_field, const char *account_name);
Checks whether contact
has a roster contact with the specified username
.
If vcard_field
or account_name
are non-NULL
, it also checks whether
the IM or VoIP account with that username also matches the vcard_field
and
account_name
as well
contact : |
a OssoABookContact |
username : |
an IM or VoIP username |
vcard_field : |
An optional name for a vcard field to restrict matches to (e.g. "X-JABBER") |
account_name : |
an optional account name to restrict matches to |
Returns : | TRUE if all specified parameters match, else FALSE
|
void osso_abook_contact_set_presence (OssoABookContact *contact, guint type, const gchar *status, const gchar *message);
Sets the presence for contact
to the specified values. These parameters
conform to the Telepathy
SimplePresence specification. See the
Simple_Presence type for more information.
contact : |
a OssoABookContact |
type : |
a TpConnectionPresenceType |
status : |
a status identifier (e.g. "available") |
message : |
a free-form status 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).
contact : |
An OssoABookContact |
Returns : | A GdkPixbuf of the photo, or NULL . The pixbuf is owned by
contact
|
void osso_abook_contact_set_pixbuf (OssoABookContact *contact, GdkPixbuf *pixbuf, EBook *book, GtkWindow *window);
Stores the image pointed to by pixbuf
as contact
's photo. If pixbuf
is
greater than OSSO_ABOOK_PIXEL_SIZE_AVATAR_LARGE
, it will be scaled down. If
pixbuf
is NULL
, contact
's photo will be removed. When the contact is
committed to the addressbook (e.g. book
is non-NULL
or
osso_abook_contact_commit()
is called), the pixbuf will be cached on disk.
contact : |
An OssoABookContact |
pixbuf : |
A GdkPixbuf of the new image |
book : |
The EBook contact originates from, or NULL to modify contact
without committing 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);
Loads the file specified by filename
as a pixbuf at size
OSSO_ABOOK_PIXEL_SIZE_AVATAR_DEFAULT
and calls
osso_abook_contact_set_pixbuf()
.
contact : |
An OssoABookContact |
filename : |
A path to an image file |
book : |
The EBook contact originates from, or NULL to 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);
Loads data
into a GdkPixbuf and then calls osso_abook_contact_set_pixbuf()
.
contact : |
An OssoABookContact |
data : |
The avatar data |
len : |
The size of data
|
book : |
The EBook contact originates from,
or NULL to 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 vcard_field
to get the specific image 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);
Gets the primary and secondary name components for contact
, according to
specified order
. If strict
is FALSE
and contact
is missing a primary
name component, this function will attempt to use a fallback primary name
component.
The name components are returned in primary_out
and secondary_out
if those
arguments are non-NULL
. The returned strings are owned by the caller and
must be freed with g_free()
.
contact : |
a EContact |
order : |
display order for name |
strict : |
Whether to get name components strictly according to order , even if
the primary name would be empty
|
primary_out : |
return location for primary name |
secondary_out : |
return location for secondary name |
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 vCard 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);
Writes contact
out to a vCard file. The filename is automatically chosen
from contact
's name (see osso_abook_contact_get_basename()
for more
information). When the file has been written (or an error occurs), callback
will be called to report the status of the operation.
contact : |
the OssoABookContact to write |
format : |
vCard version to use |
inline_avatar : |
whether to include the avatar inline in the vCard |
strict_filename : |
only use safe characters from ASCII (see
osso_abook_contact_get_basename()
|
parent_file : |
the location to save the file (parent directory) |
callback : |
a function to call when the file is written |
user_data : |
additional data to pass to callback
|
gboolean osso_abook_contact_shortcut_exists (OssoABookContact *contact, GSList **ret_list);
Checks if contact
currently has a home applet shortcut registered. If
ret_list
is non-NULL
the list of all home applet shortcuts will be
returned. The list and its contents are owned by the caller. Each element
in the list is a string of the form
OSSO_ABOOK_HOME_APPLET_PREFIX
<UID>.
contact : |
a OssoABookContact |
ret_list : |
an optional return location for all registered shortcuts |
Returns : | TRUE if a shortcut exists for contact , else FALSE
|
gboolean osso_abook_contact_shortcut_create (OssoABookContact *contact);
Creates a Home applet shortcut for contact
. If contact
already has a
shortcut, a second shortcut will not be created.
contact : |
a OssoABookContact |
Returns : | TRUE if shortcut was created successfully, else FALSE .
|
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
a : |
first OssoABookContact |
b : |
second OssoABookContact |
guint osso_abook_contact_async_add (OssoABookContact *contact, EBook *book, EBookIdCallback callback, gpointer user_data);
Adds contact
to book
asynchronously. If book
is NULL
, contact
will be
added to the EBook associated with contact
's roster (if any) or the system
addressbook.
contact : |
a OssoABookContact to add |
book : |
a EBook to add the contact to |
callback : |
a function to call when complete |
user_data : |
additional data to pass to callback
|
Returns : | TRUE if the operation was started, FALSE othewise.
|
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);
Adds contact
to an IM account roster, authorizes contact
to see our
presence, and requests authorization from that contact to see their presence
(if not already authorized). If master
is specified, contact
is attached to
master
. Any errors are handled internally and an error banner will be
displayed.
contact : |
a roster contact |
master : |
an optional master contact |
parent : |
an optional parent GtkWindow |
void osso_abook_contact_accept_for_uid (OssoABookContact *contact, const char *master_uid, GtkWindow *parent);
Adds contact
to an IM account roster and optionally attaches contact
to a
master contact with uid equal to master_uid
. This function is rarely
useful; use osso_abook_contact_accept()
instead.
contact : |
a roster contact |
master_uid : |
a UID of a master contact |
parent : |
an optional parent GtkWindow |
void osso_abook_contact_async_accept (OssoABookContact *contact, const char *master_uid, EBookIdCallback callback, gpointer user_data);
Adds contact
to an IM account roster asynchronously and optionally attaches
contact
to a master contact with uid equal to master_uid
. This function is
rarely useful; use osso_abook_contact_accept()
instead.
contact : |
a roster contact |
master_uid : |
a UID of a master contact |
callback : |
a function to call when the operation is complete |
user_data : |
optional data to pass to callback
|
void osso_abook_contact_reject (OssoABookContact *contact, GtkWindow *parent);
Remove contact
and revoke authorization to see our presence.
contact : |
a roster contact |
parent : |
an optional parent GtkWindow |
void osso_abook_contact_reject_for_uid (OssoABookContact *contact, const char *master_uid, GtkWindow *parent);
Detach contact
from the master contact with UID equal to master_uid
, and if
contact
is not attached to any other master contacts, it will removed and
authorization revoked. This function is rarely useful; use
osso_abook_contact_reject()
instead.
contact : |
a roster contact |
master_uid : |
a UID of a master contact |
parent : |
an optional parent GtkWindow |
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 use the default book
for contact
|
window : |
optional parent for error banners |
void osso_abook_contact_delete_many (GList *contacts, EBook *book, GtkWindow *window);
Deletes contacts
.
contacts : |
a list of OssoABookContacts to delete |
book : |
The EBook contact originates from, or NULL to remove from the system
addressbook
|
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. |