EContact

EContact

Synopsis

struct              EContact;
enum                EContactField;
                    EContactName;
                    EContactGeo;
                    EContactPhoto;
                    EContactAddress;
                    EContactDate;
                    EContactCert;
EContact *          e_contact_new                       (void);
EContact *          e_contact_new_from_vcard            (const gchar *vcard);
EContact *          e_contact_duplicate                 (EContact *contact);
gpointer            e_contact_get                       (EContact *contact,
                                                         EContactField field_id);
gconstpointer       e_contact_get_const                 (EContact *contact,
                                                         EContactField field_id);
void                e_contact_set                       (EContact *contact,
                                                         EContactField field_id,
                                                         gconstpointer value);
EContactDate *      e_contact_date_new                  (void);
EContactDate *      e_contact_date_from_string          (const gchar *str);
gchar *             e_contact_date_to_string            (EContactDate *dt);
gboolean            e_contact_date_equal                (EContactDate *dt1,
                                                         EContactDate *dt2);
EContactName *      e_contact_name_new                  (void);
gchar *             e_contact_name_to_string            (const EContactName *name);
EContactName *      e_contact_name_from_string          (const gchar *name_str);
EContactName *      e_contact_name_copy                 (EContactName *n);
void                e_contact_date_free                 (EContactDate *date);
void                e_contact_name_free                 (EContactName *name);
EContactPhoto *     e_contact_photo_new                 (void);
const guchar *      e_contact_photo_get_inlined         (EContactPhoto *photo,
                                                         gsize *len);
void                e_contact_photo_set_inlined         (EContactPhoto *photo,
                                                         const guchar *data,
                                                         gsize len);
const gchar *       e_contact_photo_get_mime_type       (EContactPhoto *photo);
void                e_contact_photo_set_mime_type       (EContactPhoto *photo,
                                                         const gchar *mime_type);
const gchar *       e_contact_photo_get_uri             (EContactPhoto *photo);
void                e_contact_photo_set_uri             (EContactPhoto *photo,
                                                         const gchar *uri);
void                e_contact_photo_free                (EContactPhoto *photo);
void                e_contact_geo_free                  (EContactGeo *geo);
EContactAddress *   e_contact_address_new               (void);
void                e_contact_address_free              (EContactAddress *address);
const gchar *       e_contact_field_name                (EContactField field_id);
const gchar *       e_contact_pretty_name               (EContactField field_id);
EContactField       e_contact_field_id                  (const gchar *field_name);
EContactField       e_contact_field_id_from_vcard       (const gchar *vcard_field);
void                e_contact_cert_free                 (EContactCert *cert);
GList *             e_contact_get_attributes            (EContact *contact,
                                                         EContactField field_id);
void                e_contact_set_attributes            (EContact *contact,
                                                         EContactField field_id,
                                                         GList *attributes);
const gchar *       e_contact_vcard_attribute           (EContactField field_id);

Description

Details

struct EContact

struct EContact {
	EVCard parent;
};


enum EContactField

typedef enum {
	E_CONTACT_UID = 1,	 /* string field */
	E_CONTACT_FILE_AS,	 /* string field */
	E_CONTACT_BOOK_URI,      /* string field */

	/* Name fields */
	E_CONTACT_FULL_NAME,	 /* string field */
	E_CONTACT_GIVEN_NAME,	 /* synthetic string field */
	E_CONTACT_FAMILY_NAME,	 /* synthetic string field */
	E_CONTACT_NICKNAME,	 /* string field */

	/* Email fields */
	E_CONTACT_EMAIL_1,	 /* synthetic string field */
	E_CONTACT_EMAIL_2,	 /* synthetic string field */
	E_CONTACT_EMAIL_3,	 /* synthetic string field */
	E_CONTACT_EMAIL_4,       /* synthetic string field */

	E_CONTACT_MAILER,        /* string field */

	/* Address Labels */
	E_CONTACT_ADDRESS_LABEL_HOME,  /* synthetic string field */
	E_CONTACT_ADDRESS_LABEL_WORK,  /* synthetic string field */
	E_CONTACT_ADDRESS_LABEL_OTHER, /* synthetic string field */

	/* Phone fields */
	E_CONTACT_PHONE_ASSISTANT,
	E_CONTACT_PHONE_BUSINESS,
	E_CONTACT_PHONE_BUSINESS_2,
	E_CONTACT_PHONE_BUSINESS_FAX,
	E_CONTACT_PHONE_CALLBACK,
	E_CONTACT_PHONE_CAR,
	E_CONTACT_PHONE_COMPANY,
	E_CONTACT_PHONE_HOME,
	E_CONTACT_PHONE_HOME_2,
	E_CONTACT_PHONE_HOME_FAX,
	E_CONTACT_PHONE_ISDN,
	E_CONTACT_PHONE_MOBILE,
	E_CONTACT_PHONE_OTHER,
	E_CONTACT_PHONE_OTHER_FAX,
	E_CONTACT_PHONE_PAGER,
	E_CONTACT_PHONE_PRIMARY,
	E_CONTACT_PHONE_RADIO,
	E_CONTACT_PHONE_TELEX,
	E_CONTACT_PHONE_TTYTDD,

	/* Organizational fields */
	E_CONTACT_ORG,		 /* string field */
	E_CONTACT_ORG_UNIT,	 /* string field */
	E_CONTACT_OFFICE,	 /* string field */
	E_CONTACT_TITLE,	 /* string field */
	E_CONTACT_ROLE,	 /* string field */
	E_CONTACT_MANAGER,	 /* string field */
	E_CONTACT_ASSISTANT,	 /* string field */

	/* Web fields */
	E_CONTACT_HOMEPAGE_URL,  /* string field */
	E_CONTACT_BLOG_URL,      /* string field */

	/* Contact categories */
	E_CONTACT_CATEGORIES,    /* string field */

	/* Collaboration fields */
	E_CONTACT_CALENDAR_URI,  /* string field */
	E_CONTACT_FREEBUSY_URL,  /* string field */
	E_CONTACT_ICS_CALENDAR,  /* string field */
	E_CONTACT_VIDEO_URL,      /* string field */

	/* misc fields */
	E_CONTACT_SPOUSE,        /* string field */
	E_CONTACT_NOTE,          /* string field */

	E_CONTACT_IM_AIM_HOME_1,       /* Synthetic string field */
	E_CONTACT_IM_AIM_HOME_2,       /* Synthetic string field */
	E_CONTACT_IM_AIM_HOME_3,       /* Synthetic string field */
	E_CONTACT_IM_AIM_WORK_1,       /* Synthetic string field */
	E_CONTACT_IM_AIM_WORK_2,       /* Synthetic string field */
	E_CONTACT_IM_AIM_WORK_3,       /* Synthetic string field */
	E_CONTACT_IM_GROUPWISE_HOME_1, /* Synthetic string field */
	E_CONTACT_IM_GROUPWISE_HOME_2, /* Synthetic string field */
	E_CONTACT_IM_GROUPWISE_HOME_3, /* Synthetic string field */
	E_CONTACT_IM_GROUPWISE_WORK_1, /* Synthetic string field */
	E_CONTACT_IM_GROUPWISE_WORK_2, /* Synthetic string field */
	E_CONTACT_IM_GROUPWISE_WORK_3, /* Synthetic string field */
	E_CONTACT_IM_JABBER_HOME_1,    /* Synthetic string field */
	E_CONTACT_IM_JABBER_HOME_2,    /* Synthetic string field */
	E_CONTACT_IM_JABBER_HOME_3,    /* Synthetic string field */
	E_CONTACT_IM_JABBER_WORK_1,    /* Synthetic string field */
	E_CONTACT_IM_JABBER_WORK_2,    /* Synthetic string field */
	E_CONTACT_IM_JABBER_WORK_3,    /* Synthetic string field */
	E_CONTACT_IM_YAHOO_HOME_1,     /* Synthetic string field */
	E_CONTACT_IM_YAHOO_HOME_2,     /* Synthetic string field */
	E_CONTACT_IM_YAHOO_HOME_3,     /* Synthetic string field */
	E_CONTACT_IM_YAHOO_WORK_1,     /* Synthetic string field */
	E_CONTACT_IM_YAHOO_WORK_2,     /* Synthetic string field */
	E_CONTACT_IM_YAHOO_WORK_3,     /* Synthetic string field */
	E_CONTACT_IM_MSN_HOME_1,       /* Synthetic string field */
	E_CONTACT_IM_MSN_HOME_2,       /* Synthetic string field */
	E_CONTACT_IM_MSN_HOME_3,       /* Synthetic string field */
	E_CONTACT_IM_MSN_WORK_1,       /* Synthetic string field */
	E_CONTACT_IM_MSN_WORK_2,       /* Synthetic string field */
	E_CONTACT_IM_MSN_WORK_3,       /* Synthetic string field */
	E_CONTACT_IM_ICQ_HOME_1,       /* Synthetic string field */
	E_CONTACT_IM_ICQ_HOME_2,       /* Synthetic string field */
	E_CONTACT_IM_ICQ_HOME_3,       /* Synthetic string field */
	E_CONTACT_IM_ICQ_WORK_1,       /* Synthetic string field */
	E_CONTACT_IM_ICQ_WORK_2,       /* Synthetic string field */
	E_CONTACT_IM_ICQ_WORK_3,       /* Synthetic string field */

	/* Convenience field for getting a name from the contact.
	 * Returns the first one of[File-As, Full Name, Org, Email1]
	 * to be set */
	E_CONTACT_REV,     /* string field to hold  time of last update to this vcard */
	E_CONTACT_NAME_OR_ORG,

	/* Address fields */
	E_CONTACT_ADDRESS,       /* Multi-valued structured (EContactAddress) */
	E_CONTACT_ADDRESS_HOME,  /* synthetic structured field (EContactAddress) */
	E_CONTACT_ADDRESS_WORK,  /* synthetic structured field (EContactAddress) */
	E_CONTACT_ADDRESS_OTHER, /* synthetic structured field (EContactAddress) */

	E_CONTACT_CATEGORY_LIST, /* multi-valued */

	/* Photo/Logo */
	E_CONTACT_PHOTO,	 /* structured field (EContactPhoto) */
	E_CONTACT_LOGO,	 /* structured field (EContactPhoto) */

	E_CONTACT_NAME,		 /* structured field (EContactName) */
	E_CONTACT_EMAIL,	 /* Multi-valued */

	/* Instant Messaging fields */
	E_CONTACT_IM_AIM,	 /* Multi-valued */
	E_CONTACT_IM_GROUPWISE,  /* Multi-valued */
	E_CONTACT_IM_JABBER,	 /* Multi-valued */
	E_CONTACT_IM_YAHOO,	 /* Multi-valued */
	E_CONTACT_IM_MSN,	 /* Multi-valued */
	E_CONTACT_IM_ICQ,	 /* Multi-valued */

	E_CONTACT_WANTS_HTML,    /* boolean field */

	/* fields used for describing contact lists.  a contact list
	 * is just a contact with _IS_LIST set to true.  the members
	 * are listed in the _EMAIL field. */
	E_CONTACT_IS_LIST,             /* boolean field */
	E_CONTACT_LIST_SHOW_ADDRESSES, /* boolean field */

	E_CONTACT_BIRTH_DATE,    /* structured field (EContactDate) */
	E_CONTACT_ANNIVERSARY,   /* structured field (EContactDate) */

	/* Security Fields */
	E_CONTACT_X509_CERT,     /* structured field (EContactCert) */

	E_CONTACT_IM_GADUGADU_HOME_1,  /* Synthetic string field */
	E_CONTACT_IM_GADUGADU_HOME_2,  /* Synthetic string field */
	E_CONTACT_IM_GADUGADU_HOME_3,  /* Synthetic string field */
	E_CONTACT_IM_GADUGADU_WORK_1,  /* Synthetic string field */
	E_CONTACT_IM_GADUGADU_WORK_2,  /* Synthetic string field */
	E_CONTACT_IM_GADUGADU_WORK_3,  /* Synthetic string field */

	E_CONTACT_IM_GADUGADU,   /* Multi-valued */

	E_CONTACT_GEO, /* structured field (EContactGeo) */

	E_CONTACT_TEL, /* list of strings */

	E_CONTACT_IM_SKYPE_HOME_1,     /* Synthetic string field */
	E_CONTACT_IM_SKYPE_HOME_2,     /* Synthetic string field */
	E_CONTACT_IM_SKYPE_HOME_3,     /* Synthetic string field */
	E_CONTACT_IM_SKYPE_WORK_1,     /* Synthetic string field */
	E_CONTACT_IM_SKYPE_WORK_2,     /* Synthetic string field */
	E_CONTACT_IM_SKYPE_WORK_3,     /* Synthetic string field */
	E_CONTACT_IM_SKYPE,		/* Multi-valued */

	E_CONTACT_SIP,

	E_CONTACT_IM_GOOGLE_TALK_HOME_1,     /* Synthetic string field */
	E_CONTACT_IM_GOOGLE_TALK_HOME_2,     /* Synthetic string field */
	E_CONTACT_IM_GOOGLE_TALK_HOME_3,     /* Synthetic string field */
	E_CONTACT_IM_GOOGLE_TALK_WORK_1,     /* Synthetic string field */
	E_CONTACT_IM_GOOGLE_TALK_WORK_2,     /* Synthetic string field */
	E_CONTACT_IM_GOOGLE_TALK_WORK_3,     /* Synthetic string field */
	E_CONTACT_IM_GOOGLE_TALK,		/* Multi-valued */

	E_CONTACT_FIELD_LAST,
	E_CONTACT_FIELD_FIRST        = E_CONTACT_UID,

	/* useful constants */
	E_CONTACT_LAST_SIMPLE_STRING = E_CONTACT_NAME_OR_ORG,
	E_CONTACT_FIRST_PHONE_ID     = E_CONTACT_PHONE_ASSISTANT,
	E_CONTACT_LAST_PHONE_ID      = E_CONTACT_PHONE_TTYTDD,
	E_CONTACT_FIRST_EMAIL_ID     = E_CONTACT_EMAIL_1,
	E_CONTACT_LAST_EMAIL_ID      = E_CONTACT_EMAIL_4,
	E_CONTACT_FIRST_ADDRESS_ID   = E_CONTACT_ADDRESS_HOME,
	E_CONTACT_LAST_ADDRESS_ID    = E_CONTACT_ADDRESS_OTHER,
	E_CONTACT_FIRST_LABEL_ID     = E_CONTACT_ADDRESS_LABEL_HOME,
	E_CONTACT_LAST_LABEL_ID      = E_CONTACT_ADDRESS_LABEL_OTHER
} EContactField;


EContactName

typedef struct {
	gchar *family;
	gchar *given;
	gchar *additional;
	gchar *prefixes;
	gchar *suffixes;
} EContactName;


EContactGeo

typedef struct {
	gdouble latitude;
	gdouble longitude;
} EContactGeo;

Since 1.12


EContactPhoto

typedef struct {
	EContactPhotoType type;
	union {
		struct {
			gchar *mime_type;
			gsize length;
			guchar *data;
		} inlined;
		gchar *uri;
	} data;
} EContactPhoto;


EContactAddress

typedef struct {
	gchar *address_format; /* the two letter country code that
				* determines the format/meaning of the
				* following fields */
	gchar *po;
	gchar *ext;
	gchar *street;
	gchar *locality;
	gchar *region;
	gchar *code;
	gchar *country;
} EContactAddress;


EContactDate

typedef struct {
	guint year;
	guint month;
	guint day;
} EContactDate;


EContactCert

typedef struct {
	gsize length;
	gchar *data;
} EContactCert;


e_contact_new ()

EContact *          e_contact_new                       (void);

Creates a new, blank EContact.

Returns :

A new EContact.

e_contact_new_from_vcard ()

EContact *          e_contact_new_from_vcard            (const gchar *vcard);

Creates a new EContact based on a vcard.

vcard :

a string representing a vcard

Returns :

A new EContact.

e_contact_duplicate ()

EContact *          e_contact_duplicate                 (EContact *contact);

Creates a copy of contact.

contact :

an EContact

Returns :

A new EContact identical to contact. [transfer full]

e_contact_get ()

gpointer            e_contact_get                       (EContact *contact,
                                                         EContactField field_id);

Gets the value of contact's field specified by field_id.

contact :

an EContact

field_id :

an EContactField

Returns :

Depends on the field's type, owned by the caller. [transfer full]

e_contact_get_const ()

gconstpointer       e_contact_get_const                 (EContact *contact,
                                                         EContactField field_id);

Gets the value of contact's field specified by field_id, caching the result so it can be freed later.

contact :

an EContact

field_id :

an EContactField

Returns :

Depends on the field's type, owned by the EContact. [transfer none]

e_contact_set ()

void                e_contact_set                       (EContact *contact,
                                                         EContactField field_id,
                                                         gconstpointer value);


e_contact_date_new ()

EContactDate *      e_contact_date_new                  (void);

Creates a new EContactDate struct.

Returns :

A new EContactDate struct.

e_contact_date_from_string ()

EContactDate *      e_contact_date_from_string          (const gchar *str);

Creates a new EContactDate based on str.

str :

a date string in the format YYYY-MM-DD or YYYYMMDD

Returns :

A new EContactDate struct.

e_contact_date_to_string ()

gchar *             e_contact_date_to_string            (EContactDate *dt);

Generates a date string in the format YYYY-MM-DD based on the values of dt.

dt :

an EContactDate

Returns :

A date string, owned by the caller.

e_contact_date_equal ()

gboolean            e_contact_date_equal                (EContactDate *dt1,
                                                         EContactDate *dt2);

Checks if dt1 and dt2 are the same date.

dt1 :

an EContactDate

dt2 :

an EContactDate

Returns :

TRUE if dt1 and dt2 are equal, FALSE otherwise.

e_contact_name_new ()

EContactName *      e_contact_name_new                  (void);

Creates a new EContactName struct.

Returns :

A new EContactName struct.

e_contact_name_to_string ()

gchar *             e_contact_name_to_string            (const EContactName *name);

Generates a string representation of name.

name :

an EContactName

Returns :

The string representation of name.

e_contact_name_from_string ()

EContactName *      e_contact_name_from_string          (const gchar *name_str);

Creates a new EContactName based on the parsed name_str.

name_str :

a string representing a contact's full name

Returns :

A new EContactName struct.

e_contact_name_copy ()

EContactName *      e_contact_name_copy                 (EContactName *n);

Creates a copy of n.

n :

an EContactName

Returns :

A new EContactName identical to n.

e_contact_date_free ()

void                e_contact_date_free                 (EContactDate *date);

Frees the date struct and its contents.

date :

an EContactDate

e_contact_name_free ()

void                e_contact_name_free                 (EContactName *name);

Frees name and its contents.

name :

an EContactName

e_contact_photo_new ()

EContactPhoto *     e_contact_photo_new                 (void);

Creates a new EContactPhoto struct.

Returns :

A new EContactPhoto struct. [transfer full]

Since 3.2


e_contact_photo_get_inlined ()

const guchar *      e_contact_photo_get_inlined         (EContactPhoto *photo,
                                                         gsize *len);

Gets the photo's data.

photo :

an EContactPhoto

len :

the length of the inlined data. [out caller-allocates][transfer none]

Returns :

the inlined image in the EContactPhoto. [transfer none][array length=len]

Since 3.2


e_contact_photo_set_inlined ()

void                e_contact_photo_set_inlined         (EContactPhoto *photo,
                                                         const guchar *data,
                                                         gsize len);

Sets the photo's inlined data.

photo :

an EContactPhoto

data :

the inlined image data. [transfer none][array length=len]

len :

the length of data

Since 3.2


e_contact_photo_get_mime_type ()

const gchar *       e_contact_photo_get_mime_type       (EContactPhoto *photo);

Gets the photo's mime type.

photo :

an EContactPhoto

Returns :

the mime type of the image. [transfer none]

Since 3.2


e_contact_photo_set_mime_type ()

void                e_contact_photo_set_mime_type       (EContactPhoto *photo,
                                                         const gchar *mime_type);

Sets the photo's mime type.

photo :

an EContactPhoto

mime_type :

the mime type

Since 3.2


e_contact_photo_get_uri ()

const gchar *       e_contact_photo_get_uri             (EContactPhoto *photo);

Gets the photo's URI.

photo :

an EContactPhoto

Returns :

the URI of the image. [transfer none]

Since 3.2


e_contact_photo_set_uri ()

void                e_contact_photo_set_uri             (EContactPhoto *photo,
                                                         const gchar *uri);

Sets the photo's URI.

photo :

an EContactPhoto

uri :

the photo's URI

Since 3.2


e_contact_photo_free ()

void                e_contact_photo_free                (EContactPhoto *photo);

Frees the photo struct and its contents.

photo :

an EContactPhoto struct

e_contact_geo_free ()

void                e_contact_geo_free                  (EContactGeo *geo);

Frees the geo struct and its contents.

geo :

an EContactGeo

Since 1.12


e_contact_address_new ()

EContactAddress *   e_contact_address_new               (void);

Creates a new EContactAddress struct.

Returns :

A new EContactAddress struct. [transfer full]

Since 3.2


e_contact_address_free ()

void                e_contact_address_free              (EContactAddress *address);

Frees the address struct and its contents.

address :

an EContactAddress

e_contact_field_name ()

const gchar *       e_contact_field_name                (EContactField field_id);

Gets the string representation of field_id.

field_id :

an EContactField

Returns :

The string representation of field_id, or NULL if it doesn't exist.

e_contact_pretty_name ()

const gchar *       e_contact_pretty_name               (EContactField field_id);

Gets a human-readable, translated string representation of field_id.

field_id :

an EContactField

Returns :

The human-readable representation of field_id, or NULL if it doesn't exist.

e_contact_field_id ()

EContactField       e_contact_field_id                  (const gchar *field_name);

Gets the EContactField corresponding to the field_name.

field_name :

a string representing a contact field

Returns :

An EContactField corresponding to field_name, or 0 if it doesn't exist.

e_contact_field_id_from_vcard ()

EContactField       e_contact_field_id_from_vcard       (const gchar *vcard_field);

Gets the EContactField corresponding to the vcard_field.

vcard_field :

a string representing a vCard field

Returns :

An EContactField corresponding to vcard_field, or 0 if it doesn't exist.

Since 2.26


e_contact_cert_free ()

void                e_contact_cert_free                 (EContactCert *cert);

Frees the cert struct and its contents.

cert :

an EContactCert

e_contact_get_attributes ()

GList *             e_contact_get_attributes            (EContact *contact,
                                                         EContactField field_id);

Gets a list of the vcard attributes for contact's field_id.

contact :

an EContact

field_id :

an EContactField

Returns :

A GList of pointers to EVCardAttribute, owned by the caller. [transfer full][element-type EVCardAttribute]

e_contact_set_attributes ()

void                e_contact_set_attributes            (EContact *contact,
                                                         EContactField field_id,
                                                         GList *attributes);

Sets the vcard attributes for contact's field_id. Attributes are added to the contact in the same order as they are in attributes.

contact :

an EContact

field_id :

an EContactField

attributes :

a GList of pointers to EVCardAttribute. [element-type EVCardAttribute]

e_contact_vcard_attribute ()

const gchar *       e_contact_vcard_attribute           (EContactField field_id);

Gets the vcard attribute corresponding to field_id, as a string.

field_id :

an EContactField

Returns :

The vcard attribute corresponding to field_id, or NULL if it doesn't exist.