EContact: Evolution-Data-Server Reference Manual

## EContact EContact — A convenience interface for interacting with contacts |

## Functions

EContact * | e_contact_new ()
EContact * | e_contact_new_from_vcard ()
EContact * | e_contact_new_from_vcard_with_uid ()
EContact * | e_contact_duplicate ()
gpointer | e_contact_get ()
gconstpointer | e_contact_get_const ()
void | e_contact_set ()
GList * | e_contact_get_attributes ()
GList * | e_contact_get_attributes_set ()
void | e_contact_set_attributes ()
EContactDate * | e_contact_date_new ()
EContactDate * | e_contact_date_from_string ()
gchar * | e_contact_date_to_string ()
gboolean | e_contact_date_equal ()
void | e_contact_date_free ()
EContactName * | e_contact_name_new ()
gchar * | e_contact_name_to_string ()
EContactName * | e_contact_name_from_string ()
EContactName * | e_contact_name_copy ()
void | e_contact_name_free ()
EContactPhoto * | e_contact_photo_new ()
void | e_contact_photo_free ()
EContactPhoto * | e_contact_photo_copy ()
const guchar * | e_contact_photo_get_inlined ()
void | e_contact_photo_set_inlined ()
const gchar * | e_contact_photo_get_mime_type ()
void | e_contact_photo_set_mime_type ()
const gchar * | e_contact_photo_get_uri ()
void | e_contact_photo_set_uri ()
gboolean | e_contact_inline_local_photos ()
EContactGeo * | e_contact_geo_new ()
void | e_contact_geo_free ()
EContactCert * | e_contact_cert_new ()
void | e_contact_cert_free ()
EContactAddress * | e_contact_address_new ()
void | e_contact_address_free ()
GList * | e_contact_attr_list_copy ()
void | e_contact_attr_list_free ()
GType | e_contact_field_type ()
const gchar * | e_contact_field_name ()
const gchar * | e_contact_pretty_name ()
const gchar * | e_contact_vcard_attribute ()
gboolean | e_contact_field_is_string ()
EContactField | e_contact_field_id ()
EContactField | e_contact_field_id_from_vcard ()

## Types and Values

enum | EContactField
| EContactGeo
enum | EContactPhotoType

## Object Hierarchy

        GBoxed
        ├── EContactAddress
        ├── EContactCert
        ├── EContactDate
        ├── EContactGeo
        ├── EContactName
        ╰── EContactPhoto
        GObject
        ╰── EVCard
            ╰── EContact

## Includes

    #include <libebook-contacts/libebook-contacts.h>

## Description

This subclass of EVCard is a convenient interface for interacting with vCards. The EBookClient, EBookClientView and EBookClientCursor return vCards in the form of an EContact for your convenience.

## Functions

### 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.

#### Parameters

vcard | a string representing a vcard |

#### Returns

A new EContact.

### e_contact_new_from_vcard_with_uid ()

    EContact *
    e_contact_new_from_vcard_with_uid (const gchar *vcard,
                                       const gchar *uid);

Creates a new EContact based on a vcard and a predefined UID.

#### Parameters

vcard | a string representing a vcard |
uid | a contact UID |

#### Returns

A new EContact.

Since: 3.4

### e_contact_duplicate ()

    EContact *
    e_contact_duplicate (EContact *contact);

Creates a copy of `contact` .

#### Parameters

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` .

#### Parameters

contact | an EContact |
field_id | an EContactField |

#### Returns

Depends on the field's type, owned by the caller. This may be `NULL` if the field isn't set.

[transfer full][nullable]

### 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. Use `e_contact_field_is_string()` to check whether the field can be used here.

#### Parameters

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

Sets the value of `contact` 's field specified by `field_id` to `value` .

#### Parameters

contact | an EContact |
field_id | an EContactField |
value | a value whose type depends on the `field_id` |

### 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` .

#### Parameters

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

    GList *
    e_contact_get_attributes_set (EContact *contact,
                                  const EContactField field_ids[],
                                  gint size);

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

#### Parameters

contact | an EContact |
field_ids | an array of EContactField. | [array length=size]
size | number of elements in field_ids |

#### Returns

A GList of pointers to EVCardAttribute, owned by the caller.

[transfer full][element-type EVCardAttribute]

Since: 3.16

### 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` .

#### Parameters

contact | an EContact |
field_id | an EContactField |
attributes | a GList of pointers to EVCardAttribute. | [element-type EVCardAttribute]

### 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` .

#### Parameters

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

#### Returns

A new EContactDate struct.

[transfer full]

### 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` .

#### Parameters

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.

#### Parameters

dt1 | an EContactDate |
dt2 | an EContactDate |

#### Returns

`TRUE` if `dt1` and `dt2` are equal, `FALSE` otherwise.

### e_contact_date_free ()

    void
    e_contact_date_free (EContactDate *date);

Frees the `date` struct and its contents.

#### Parameters

date | an EContactDate |

### 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` .

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

n | an EContactName |

#### Returns

A new EContactName identical to `n` .

[transfer full]

### e_contact_name_free ()

    void
    e_contact_name_free (EContactName *name);

Frees `name` and its contents.

#### Parameters

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

    void
    e_contact_photo_free (EContactPhoto *photo);

Frees the `photo` struct and its contents.

#### Parameters

photo | an EContactPhoto struct |

### e_contact_photo_copy ()

    EContactPhoto *
    e_contact_photo_copy (EContactPhoto *photo);

Creates a copy of `photo` .

#### Parameters

photo | an EContactPhoto |

#### Returns

A new EContactPhoto struct identical to `photo` .

[transfer full]

Since: 3.8

### e_contact_photo_get_inlined ()

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

Gets the `photo` 's data.

#### Parameters

photo | an EContactPhoto |
len | the length of the inlined data. | [out]

#### Returns

the inlined image in the EContactPhoto, or `NULL` if it has not been set.

[transfer none][array length=len][nullable]

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.

#### Parameters

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.

#### Parameters

photo | an EContactPhoto |

#### Returns

the MIME type of the image, or `NULL` if it has not been set.

[transfer none][nullable]

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.

#### Parameters

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.

#### Parameters

photo | an EContactPhoto |

#### Returns

the URI of the image, or `NULL` if it has not been set.

[transfer none][nullable]

Since: 3.2

### e_contact_photo_set_uri ()

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

Sets the `photo` 's URI.

#### Parameters

photo | an EContactPhoto |
uri | the `photo` 's URI |

Since: 3.2

### e_contact_inline_local_photos ()

    gboolean
    e_contact_inline_local_photos (EContact *contact,
                                   GError **error);

Tries to modify any EContactPhoto fields which are stored on the local file system as type `E_CONTACT_PHOTO_TYPE_URI` to be inlined and stored as `E_CONTACT_PHOTO_TYPE_INLINED` instead.

#### Parameters

contact | an EContact |
error | the location to store any GError which might occur |

#### Returns

`TRUE` if there were no errors, upon error `FALSE` is returned and `error` is set.

Since: 3.4

### e_contact_geo_new ()

    EContactGeo *
    e_contact_geo_new (void);

Creates an EContactGeo struct with all coordinates set to 0.

#### Returns

A new EContactGeo struct.

[transfer full]

Since: 3.8

### e_contact_geo_free ()

    void
    e_contact_geo_free (EContactGeo *geo);

Frees the `geo` struct and its contents.

#### Parameters

geo | an EContactGeo |

Since: 1.12

### e_contact_cert_new ()

    EContactCert *
    e_contact_cert_new (void);

Creates an EContactCert struct with all values set to 0.

#### Returns

A new EContactCert struct.

[transfer full]

Since: 3.8

### e_contact_cert_free ()

    void
    e_contact_cert_free (EContactCert *cert);

Frees the `cert` struct and its contents.

#### Parameters

cert | an EContactCert |

### 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.

#### Parameters

address | an EContactAddress |

### e_contact_attr_list_copy ()

    GList *
    e_contact_attr_list_copy (GList *list);

Copies a list of allocated strings, specifically for the EContactAttrList boxed type used for multi valued contact fields.

#### Parameters

list | A GList of strings. | [element-type utf8]

#### Returns

A copy of `list` .

[transfer full][element-type utf8]

Since: 3.8

### e_contact_attr_list_free ()

    void
    e_contact_attr_list_free (GList *list);

Frees a list of allocated strings, specifically for the EContactAttrList boxed type used for multi valued contact fields.

#### Parameters

list | A GList of strings. | [element-type utf8]

Since: 3.8

### e_contact_field_type ()

    GType
    e_contact_field_type (EContactField field_id);

Gets the GType used for this contact field, this indicates what kind of value can be passed to `e_contact_set()`.

#### Parameters

field_id | an EContactField |

#### Returns

The GType used for `field_id` , or `G_TYPE_INVALID` if it doesn't exist.

Since: 3.8

### e_contact_field_name ()

    const gchar *
    e_contact_field_name (EContactField field_id);

Gets the string representation of `field_id` .

#### Parameters

field_id | an EContactField |

#### Returns

The string representation of `field_id`

### e_contact_pretty_name ()

    const gchar *
    e_contact_pretty_name (EContactField field_id);

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

#### Parameters

field_id | an EContactField |

#### Returns

The human-readable representation of `field_id`

### e_contact_vcard_attribute ()

    const gchar *
    e_contact_vcard_attribute (EContactField field_id);

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

#### Parameters

field_id | an EContactField |

#### Returns

The vcard attribute corresponding to `field_id`

### e_contact_field_is_string ()

    gboolean
    e_contact_field_is_string (EContactField field_id);

Returns whether the `field_id` is of a string type, thus it can be used with `e_contact_get_const()`.

#### Parameters

field_id | an EContactField |

#### Returns

Whether the `field_id` is of a string type.

Since: 3.16

### e_contact_field_id ()

    EContactField
    e_contact_field_id (const gchar *field_name);

Gets the EContactField corresponding to the `field_name` .

#### Parameters

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` .

#### Parameters

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

## Types and Values

### enum EContactField

#### Members

E_CONTACT_UID |  |
E_CONTACT_FILE_AS |  |
E_CONTACT_BOOK_UID |  |
E_CONTACT_FULL_NAME |  |
E_CONTACT_GIVEN_NAME |  |
E_CONTACT_FAMILY_NAME |  |
E_CONTACT_NICKNAME |  |
E_CONTACT_EMAIL_1 |  |
E_CONTACT_EMAIL_2 |  |
E_CONTACT_EMAIL_3 |  |
E_CONTACT_EMAIL_4 |  |
E_CONTACT_MAILER |  |
E_CONTACT_ADDRESS_LABEL_HOME |  |
E_CONTACT_ADDRESS_LABEL_WORK |  |
E_CONTACT_ADDRESS_LABEL_OTHER |  |
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 |  |
E_CONTACT_ORG |  |
E_CONTACT_ORG_UNIT |  |
E_CONTACT_OFFICE |  |
E_CONTACT_TITLE |  |
E_CONTACT_ROLE |  |
E_CONTACT_MANAGER |  |
E_CONTACT_ASSISTANT |  |
E_CONTACT_HOMEPAGE_URL |  |
E_CONTACT_BLOG_URL |  |
E_CONTACT_CATEGORIES |  |
E_CONTACT_CALENDAR_URI |  |
E_CONTACT_FREEBUSY_URL |  |
E_CONTACT_ICS_CALENDAR |  |
E_CONTACT_VIDEO_URL |  |
E_CONTACT_SPOUSE |  |
E_CONTACT_NOTE |  |
E_CONTACT_IM_AIM_HOME_1 |  |
E_CONTACT_IM_AIM_HOME_2 |  |
E_CONTACT_IM_AIM_HOME_3 |  |
E_CONTACT_IM_AIM_WORK_1 |  |
E_CONTACT_IM_AIM_WORK_2 |  |
E_CONTACT_IM_AIM_WORK_3 |  |
E_CONTACT_IM_GROUPWISE_HOME_1 |  |
E_CONTACT_IM_GROUPWISE_HOME_2 |  |
E_CONTACT_IM_GROUPWISE_HOME_3 |  |
E_CONTACT_IM_GROUPWISE_WORK_1 |  |
E_CONTACT_IM_GROUPWISE_WORK_2 |  |
E_CONTACT_IM_GROUPWISE_WORK_3 |  |
E_CONTACT_IM_JABBER_HOME_1 |  |
E_CONTACT_IM_JABBER_HOME_2 |  |
E_CONTACT_IM_JABBER_HOME_3 |  |
E_CONTACT_IM_JABBER_WORK_1 |  |
E_CONTACT_IM_JABBER_WORK_2 |  |
E_CONTACT_IM_JABBER_WORK_3 |  |
E_CONTACT_IM_YAHOO_HOME_1 |  |
E_CONTACT_IM_YAHOO_HOME_2 |  |
E_CONTACT_IM_YAHOO_HOME_3 |  |
E_CONTACT_IM_YAHOO_WORK_1 |  |
E_CONTACT_IM_YAHOO_WORK_2 |  |
E_CONTACT_IM_YAHOO_WORK_3 |  |
E_CONTACT_IM_MSN_HOME_1 |  |
E_CONTACT_IM_MSN_HOME_2 |  |
E_CONTACT_IM_MSN_HOME_3 |  |
E_CONTACT_IM_MSN_WORK_1 |  |
E_CONTACT_IM_MSN_WORK_2 |  |
E_CONTACT_IM_MSN_WORK_3 |  |
E_CONTACT_IM_ICQ_HOME_1 |  |
E_CONTACT_IM_ICQ_HOME_2 |  |
E_CONTACT_IM_ICQ_HOME_3 |  |
E_CONTACT_IM_ICQ_WORK_1 |  |
E_CONTACT_IM_ICQ_WORK_2 |  |
E_CONTACT_IM_ICQ_WORK_3 |  |
E_CONTACT_REV |  |
E_CONTACT_NAME_OR_ORG |  |
E_CONTACT_ADDRESS |  |
E_CONTACT_ADDRESS_HOME |  |
E_CONTACT_ADDRESS_WORK |  |
E_CONTACT_ADDRESS_OTHER |  |
E_CONTACT_CATEGORY_LIST |  |
E_CONTACT_PHOTO |  |
E_CONTACT_LOGO |  |
E_CONTACT_NAME |  |
E_CONTACT_EMAIL |  |
E_CONTACT_IM_AIM |  |
E_CONTACT_IM_GROUPWISE |  |
E_CONTACT_IM_JABBER |  |
E_CONTACT_IM_YAHOO |  |
E_CONTACT_IM_MSN |  |
E_CONTACT_IM_ICQ |  |
E_CONTACT_WANTS_HTML |  |
E_CONTACT_IS_LIST |  |
E_CONTACT_LIST_SHOW_ADDRESSES |  |
E_CONTACT_BIRTH_DATE |  |
E_CONTACT_ANNIVERSARY |  |
E_CONTACT_X509_CERT |  |
E_CONTACT_PGP_CERT |  |
E_CONTACT_IM_GADUGADU_HOME_1 |  |
E_CONTACT_IM_GADUGADU_HOME_2 |  |
E_CONTACT_IM_GADUGADU_HOME_3 |  |
E_CONTACT_IM_GADUGADU_WORK_1 |  |
E_CONTACT_IM_GADUGADU_WORK_2 |  |
E_CONTACT_IM_GADUGADU_WORK_3 |  |
E_CONTACT_IM_GADUGADU |  |
E_CONTACT_GEO |  |
E_CONTACT_TEL |  |
E_CONTACT_IM_SKYPE_HOME_1 |  |
E_CONTACT_IM_SKYPE_HOME_2 |  |
E_CONTACT_IM_SKYPE_HOME_3 |  |
E_CONTACT_IM_SKYPE_WORK_1 |  |
E_CONTACT_IM_SKYPE_WORK_2 |  |
E_CONTACT_IM_SKYPE_WORK_3 |  |
E_CONTACT_IM_SKYPE |  |
E_CONTACT_SIP |  |
E_CONTACT_IM_GOOGLE_TALK_HOME_1 |  |
E_CONTACT_IM_GOOGLE_TALK_HOME_2 |  |
E_CONTACT_IM_GOOGLE_TALK_HOME_3 |  |
E_CONTACT_IM_GOOGLE_TALK_WORK_1 |  |
E_CONTACT_IM_GOOGLE_TALK_WORK_2 |  |
E_CONTACT_IM_GOOGLE_TALK_WORK_3 |  |
E_CONTACT_IM_GOOGLE_TALK |  |
E_CONTACT_IM_TWITTER |  |
E_CONTACT_IM_MATRIX_HOME_1 |  |
E_CONTACT_IM_MATRIX_HOME_2 |  |
E_CONTACT_IM_MATRIX_HOME_3 |  |
E_CONTACT_IM_MATRIX_WORK_1 |  |
E_CONTACT_IM_MATRIX_WORK_2 |  |
E_CONTACT_IM_MATRIX_WORK_3 |  |
E_CONTACT_IM_MATRIX |  |
E_CONTACT_FIELD_LAST |  |
E_CONTACT_FIELD_FIRST |  |
E_CONTACT_LAST_SIMPLE_STRING |  |
E_CONTACT_FIRST_PHONE_ID |  |
E_CONTACT_LAST_PHONE_ID |  |
E_CONTACT_FIRST_EMAIL_ID |  |
E_CONTACT_LAST_EMAIL_ID |  |
E_CONTACT_FIRST_ADDRESS_ID |  |
E_CONTACT_LAST_ADDRESS_ID |  |
E_CONTACT_FIRST_LABEL_ID |  |
E_CONTACT_LAST_LABEL_ID |  |

### EContactGeo

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

#### Members

gdouble `latitude`; | latitude |
gdouble `longitude`; | longitude |

Since: 1.12

### enum EContactPhotoType

#### Members

E_CONTACT_PHOTO_TYPE_INLINED |  |
E_CONTACT_PHOTO_TYPE_URI |  |