EVCard: Evolution-Data-Server Reference Manual

## EVCard EVCard — vCard parsing and interpretation |

## Stability Level

Stable, unless otherwise indicated

## Functions

void | e_vcard_construct ()
void | e_vcard_construct_with_uid ()
void | e_vcard_construct_full ()
EVCard * | e_vcard_new ()
EVCard * | e_vcard_new_from_string ()
gboolean | e_vcard_is_parsed ()
gchar * | e_vcard_to_string ()
void | e_vcard_dump_structure ()
EVCardAttribute * | e_vcard_attribute_new ()
void | e_vcard_attribute_free ()
EVCardAttribute * | e_vcard_attribute_copy ()
void | e_vcard_remove_attributes ()
void | e_vcard_remove_attribute ()
void | e_vcard_append_attribute ()
void | e_vcard_append_attribute_with_value ()
void | e_vcard_append_attribute_with_values ()
void | e_vcard_add_attribute ()
void | e_vcard_add_attribute_with_value ()
void | e_vcard_add_attribute_with_values ()
void | e_vcard_attribute_add_value ()
void | e_vcard_attribute_add_value_decoded ()
void | e_vcard_attribute_add_values ()
void | e_vcard_attribute_remove_value ()
void | e_vcard_attribute_remove_values ()
void | e_vcard_attribute_remove_params ()
void | e_vcard_attribute_remove_param ()
void | e_vcard_attribute_remove_param_value ()
EVCardAttributeParam * | e_vcard_attribute_param_new ()
void | e_vcard_attribute_param_free ()
EVCardAttributeParam * | e_vcard_attribute_param_copy ()
void | e_vcard_attribute_add_param ()
void | e_vcard_attribute_add_param_with_value ()
void | e_vcard_attribute_add_param_with_values ()
void | e_vcard_attribute_param_add_value ()
void | e_vcard_attribute_param_add_values ()
void | e_vcard_attribute_param_remove_values ()
EVCardAttribute * | e_vcard_get_attribute ()
EVCardAttribute * | e_vcard_get_attribute_if_parsed ()
GList * | e_vcard_get_attributes ()
const gchar * | e_vcard_attribute_get_group ()
const gchar * | e_vcard_attribute_get_name ()
GList * | e_vcard_attribute_get_values ()
GList * | e_vcard_attribute_get_values_decoded ()
gboolean | e_vcard_attribute_is_single_valued ()
gchar * | e_vcard_attribute_get_value ()
GString * | e_vcard_attribute_get_value_decoded ()
GList * | e_vcard_attribute_get_params ()
GList * | e_vcard_attribute_get_param ()
const gchar * | e_vcard_attribute_param_get_name ()
GList * | e_vcard_attribute_param_get_values ()
gboolean | e_vcard_attribute_has_type ()
gchar * | e_vcard_escape_string ()
gchar * | e_vcard_unescape_string ()
void | e_vcard_util_set_x_attribute ()
gchar * | e_vcard_util_dup_x_attribute ()

## Types and Values

#define | EVC_ADR
#define | EVC_BDAY
#define | EVC_CALURI
#define | EVC_CATEGORIES
#define | EVC_EMAIL
#define | EVC_ENCODING
#define | EVC_FBURL
#define | EVC_FN
#define | EVC_GEO
#define | EVC_ICSCALENDAR
#define | EVC_KEY
#define | EVC_LABEL
#define | EVC_LOGO
#define | EVC_MAILER
#define | EVC_NICKNAME
#define | EVC_N
#define | EVC_NOTE
#define | EVC_ORG
#define | EVC_PHOTO
#define | EVC_PRODID
#define | EVC_QUOTEDPRINTABLE
#define | EVC_REV
#define | EVC_ROLE
#define | EVC_TEL
#define | EVC_TITLE
#define | EVC_TYPE
#define | EVC_UID
#define | EVC_URL
#define | EVC_VALUE
#define | EVC_VERSION
#define | EVC_X_AIM
#define | EVC_X_ANNIVERSARY
#define | EVC_X_ASSISTANT
#define | EVC_X_BIRTHDAY
#define | EVC_X_BLOG_URL
#define | EVC_X_CALLBACK
#define | EVC_X_COMPANY
#define | EVC_X_DEST_CONTACT_UID
#define | EVC_X_DEST_EMAIL_NUM
#define | EVC_X_DEST_HTML_MAIL
#define | EVC_X_DEST_SOURCE_UID
#define | EVC_X_E164
#define | EVC_X_FILE_AS
#define | EVC_X_GADUGADU
#define | EVC_X_GROUPWISE
#define | EVC_X_ICQ
#define | EVC_X_JABBER
#define | EVC_X_LIST_SHOW_ADDRESSES
#define | EVC_X_LIST
#define | EVC_X_LIST_NAME
#define | EVC_X_MANAGER
#define | EVC_X_MSN
#define | EVC_X_RADIO
#define | EVC_X_SKYPE
#define | EVC_X_GOOGLE_TALK
#define | EVC_X_TWITTER
#define | EVC_X_SIP
#define | EVC_X_SPOUSE
#define | EVC_X_TELEX
#define | EVC_X_TTYTDD
#define | EVC_X_VIDEO_URL
#define | EVC_X_WANTS_HTML
#define | EVC_X_YAHOO
#define | EVC_X_BOOK_UID
#define | EVC_CONTACT_LIST
#define | EVC_PARENT_CL
#define | EVC_CL_UID
#define | EVC_X_DEST_EMAIL
#define | EVC_X_DEST_NAME
enum | EVCardFormat
#define | E_TYPE_VCARD_PARAM_ATTRIBUTE
#define | E_VCARD_21_VALID_PROPERTIES
#define | E_VCARD_21_VALID_PARAMETERS

## Includes

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

## Description

EVCard is a low-level representation of a vCard, as specified in RFCs 2425 and 2426 (for vCard version 3.0); this class only supports versions 2.1 and 3.0 of the vCard standard.

A vCard is an unordered set of attributes (otherwise known as properties), each with one or more values. The number of values an attribute has is determined by its type, and is given in the specification. Each attribute may also have zero or more named parameters, which provide metadata about its value.

For example, the following line from a vCard:

    1
    ADR;TYPE=WORK:;;100 Waters Edge;Baytown;LA;30314;United States of America

is an `ADR` attribute with 6 values giving the different components of the postal address. It has one parameter, `TYPE`, which specifies that it’s a work address rather than a home address.

Using the EVCard API, this data is accessible as follows:

Example 1. Accessing a Multi-Valued Attribute

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    EVCard *vcard;
    EVCardAttribute *attr;
    GList *param_values, *values;

    vcard = e_vcard_new_from_string (
       "BEGIN:VCARD\n"
       "VERSION:3.0\n"
       "ADR;TYPE=WORK:;;100 Waters Edge;Baytown;LA;30314;United States of America\n"
       "END:VCARD\n");
    attr = e_vcard_get_attribute (vcard, "ADR");

    g_assert_cmpstr (e_vcard_attribute_get_name (attr), ==, "ADR");
    g_assert (e_vcard_attribute_is_single_valued (attr) == FALSE);

    param_values = e_vcard_attribute_get_param (attr, "TYPE");
    g_assert_cmpuint (g_list_length (param_values), ==, 1);
    g_assert_cmpstr (param_values->data, ==, "WORK");

    values = e_vcard_attribute_get_values (attr);
    g_assert_cmpuint (g_list_length (values), ==, 6);
    g_assert_cmpstr (values->data, ==, "");
    g_assert_cmpstr (values->next->data, ==, "100 Waters Edge");
    g_assert_cmpstr (values->next->next->data, ==, "Baytown");
    /* etc. */

    g_object_unref (vcard);

If a second `ADR` attribute was present in the vCard, the above example would only ever return the first attribute. To access the values of other attributes of the same type, the entire attribute list must be iterated over using `e_vcard_get_attributes()`, then matching on `e_vcard_attribute_get_name()`.

vCard attribute values may be encoded in the vCard source, using base-64 or quoted-printable encoding. Such encoded values are automatically decoded when parsing the vCard, so the values returned by `e_vcard_attribute_get_value()` do not need further decoding. The ‘decoded’ functions, `e_vcard_attribute_get_value_decoded()` and `e_vcard_attribute_get_values_decoded()` are only relevant when adding attributes which use pre-encoded values and have their `ENCODING` parameter set.

String comparisons in EVCard are almost universally case-insensitive. Attribute names, parameter names and parameter values are all compared case-insensitively. Only attribute values are case sensitive.

EVCard implements lazy parsing of its vCard data, so the first time its attributes are accessed may take slightly longer than normal to allow for the vCard to be parsed. This can be tested by calling `e_vcard_is_parsed()`.

## Functions

### e_vcard_construct ()

    void
    e_vcard_construct (EVCard *evc,
                       const gchar *str);

Constructs the existing EVCard, `evc` , setting its vCard data to `str` .

This modifies `evc` .

#### Parameters

evc | an existing EVCard |
str | a vCard string |

### e_vcard_construct_with_uid ()

    void
    e_vcard_construct_with_uid (EVCard *evc,
                                const gchar *str,
                                const gchar *uid);

Constructs the existing EVCard, `evc` , setting its vCard data to `str` , and adding a new UID attribute with the value given in `uid` (if `uid` is non-`NULL`).

This modifies `evc` .

#### Parameters

evc | an existing EVCard |
str | a vCard string |
uid | a unique ID string. | [allow-none]

Since: 3.4

### e_vcard_construct_full ()

    void
    e_vcard_construct_full (EVCard *evc,
                            const gchar *str,
                            gssize len,
                            const gchar *uid);

Similar to `e_vcard_construct_with_uid()`, but can also be used with an `str` that is not `NULL` terminated.

#### Parameters

evc | an existing EVCard |
str | a vCard string |
len | length of `str` , or -1 if `str` is `NULL` terminated |
uid | a unique ID string. | [allow-none]

Since: 3.12

### e_vcard_new ()

    EVCard *
    e_vcard_new (void);

Creates a new, blank EVCard.

#### Returns

A new, blank EVCard.

[transfer full]

### e_vcard_new_from_string ()

    EVCard *
    e_vcard_new_from_string (const gchar *str);

Creates a new EVCard from the passed-in string representation.

#### Parameters

str | a string representation of the vcard to create |

#### Returns

A new EVCard.

[transfer full]

### e_vcard_is_parsed ()

    gboolean
    e_vcard_is_parsed (EVCard *evc);

Check if the `evc` has been parsed already, as EVCard implements lazy parsing of its vCard data. Used for debugging.

#### Parameters

evc | an EVCard |

#### Returns

`TRUE` if `evc` has been parsed, `FALSE` otherwise.

Since: 3.2

### e_vcard_to_string ()

    gchar *
    e_vcard_to_string (EVCard *evc,
                       EVCardFormat format);

Exports `evc` to a string representation, specified by the `format` argument.

#### Parameters

evc | the EVCard to export |
format | the format to export to |

#### Returns

A newly allocated string representing the vcard.

[transfer full]

### e_vcard_dump_structure ()

    void
    e_vcard_dump_structure (EVCard *evc);

Prints a dump of `evc` 's structure to stdout. Used for debugging.

#### Parameters

evc | the EVCard to dump |

### e_vcard_attribute_new ()

    EVCardAttribute *
    e_vcard_attribute_new (const gchar *attr_group,
                           const gchar *attr_name);

Creates a new EVCardAttribute with the specified group and attribute names. The `attr_group` may be `NULL` or the empty string if no group is needed.

#### Parameters

attr_group | a group name. | [allow-none]
attr_name | an attribute name |

#### Returns

A new EVCardAttribute.

[transfer full]

### e_vcard_attribute_free ()

    void
    e_vcard_attribute_free (EVCardAttribute *attr);

Frees an attribute, its values and its parameters.

#### Parameters

attr | attribute to free. | [transfer full]

### e_vcard_attribute_copy ()

    EVCardAttribute *
    e_vcard_attribute_copy (EVCardAttribute *attr);

Makes a copy of `attr` .

#### Parameters

attr | attribute to copy |

#### Returns

A new EVCardAttribute identical to `attr` .

[transfer full]

### e_vcard_remove_attributes ()

    void
    e_vcard_remove_attributes (EVCard *evc,
                               const gchar *attr_group,
                               const gchar *attr_name);

Removes all the attributes with group name and attribute name equal to the passed in values. If `attr_group` is `NULL` or an empty string, it removes all the attributes with passed in name irrespective of their group names.

#### Parameters

evc | vcard object |
attr_group | group name of attributes to be removed. | [allow-none]
attr_name | name of the arributes to be removed |

### e_vcard_remove_attribute ()

    void
    e_vcard_remove_attribute (EVCard *evc,
                              EVCardAttribute *attr);

Removes `attr` from `evc` and frees it. This takes ownership of `attr` .

#### Parameters

evc | an EVCard |
attr | an EVCardAttribute to remove. | [transfer full]

### e_vcard_append_attribute ()

    void
    e_vcard_append_attribute (EVCard *evc,
                              EVCardAttribute *attr);

Appends `attr` to `evc` to the end of a list of attributes. This takes ownership of `attr` .

#### Parameters

evc | an EVCard |
attr | an EVCardAttribute to append. | [transfer full]

Since: 2.32

### e_vcard_append_attribute_with_value ()

    void
    e_vcard_append_attribute_with_value (EVCard *evcard,
                                         EVCardAttribute *attr,
                                         const gchar *value);

Appends `attr` to `evcard` , setting it to `value` . This takes ownership of `attr` .

This is a convenience wrapper around `e_vcard_attribute_add_value()` and `e_vcard_append_attribute()`.

#### Parameters

evcard | an EVCard |
attr | an EVCardAttribute to append. | [transfer full]
value | a value to assign to the attribute |

Since: 2.32

### e_vcard_append_attribute_with_values ()

    void
    e_vcard_append_attribute_with_values (EVCard *evcard,
                                          EVCardAttribute *attr,
                                          ...);

Appends `attr` to `evcard` , assigning the list of values to it. This takes ownership of `attr` .

This is a convenience wrapper around `e_vcard_attribute_add_value()` and `e_vcard_append_attribute()`.

#### Parameters

evcard | an `EVCard` |
attr | an EVCardAttribute to append. | [transfer full]
... | a `NULL`-terminated list of values to assign to the attribute |

Since: 2.32

### e_vcard_add_attribute ()

    void
    e_vcard_add_attribute (EVCard *evc,
                           EVCardAttribute *attr);

Prepends `attr` to `evc` . This takes ownership of `attr` .

#### Parameters

evc | an EVCard |
attr | an EVCardAttribute to add. | [transfer full]

### e_vcard_add_attribute_with_value ()

    void
    e_vcard_add_attribute_with_value (EVCard *evcard,
                                      EVCardAttribute *attr,
                                      const gchar *value);

Prepends `attr` to `evcard` , setting it to `value` . This takes ownership of `attr` .

This is a convenience wrapper around `e_vcard_attribute_add_value()` and `e_vcard_add_attribute()`.

#### Parameters

evcard | an EVCard |
attr | an EVCardAttribute to add. | [transfer full]
value | a value to assign to the attribute |

### e_vcard_add_attribute_with_values ()

    void
    e_vcard_add_attribute_with_values (EVCard *evcard,
                                       EVCardAttribute *attr,
                                       ...);

Prepends `attr` to `evcard` , assigning the list of values to it. This takes ownership of `attr` .

This is a convenience wrapper around `e_vcard_attribute_add_value()` and `e_vcard_add_attribute()`.

#### Parameters

evcard | an `EVCard` |
attr | an EVCardAttribute to add. | [transfer full]
... | a `NULL`-terminated list of values to assign to the attribute |

### e_vcard_attribute_add_value ()

    void
    e_vcard_attribute_add_value (EVCardAttribute *attr,
                                 const gchar *value);

Appends `value` to `attr` 's list of values.

#### Parameters

attr | an EVCardAttribute |
value | a string value |

### e_vcard_attribute_add_value_decoded ()

    void
    e_vcard_attribute_add_value_decoded (EVCardAttribute *attr,
                                         const gchar *value,
                                         gint len);

Encodes `value` according to the encoding used for `attr` , and appends it to `attr` 's list of values.

This should only be used if the EVCardAttribute has a non-raw encoding (i.e. if it’s encoded in base-64 or quoted-printable encoding).

#### Parameters

attr | an EVCardAttribute |
value | an encoded value |
len | the length of the encoded value, in bytes |

### e_vcard_attribute_add_values ()

    void
    e_vcard_attribute_add_values (EVCardAttribute *attr,
                                  ...);

Appends a list of values to `attr` .

#### Parameters

attr | an EVCardAttribute |
... | a `NULL`-terminated list of strings |

### e_vcard_attribute_remove_value ()

    void
    e_vcard_attribute_remove_value (EVCardAttribute *attr,
                                    const gchar *s);

Removes value `s` from the value list in `attr` . The value `s` is not freed.

#### Parameters

attr | an EVCardAttribute |
s | a value to remove |

### e_vcard_attribute_remove_values ()

    void
    e_vcard_attribute_remove_values (EVCardAttribute *attr);

Removes and frees all values from `attr` .

#### Parameters

attr | an EVCardAttribute |

### e_vcard_attribute_remove_params ()

    void
    e_vcard_attribute_remove_params (EVCardAttribute *attr);

Removes and frees all parameters from `attr` .

This also resets the EVCardAttribute's encoding back to raw.

#### Parameters

attr | an EVCardAttribute |

### e_vcard_attribute_remove_param ()

    void
    e_vcard_attribute_remove_param (EVCardAttribute *attr,
                                    const gchar *param_name);

Removes and frees parameter `param_name` from the attribute `attr` . Parameter names are guaranteed to be unique, so `attr` is guaranteed to have no parameters named `param_name` after this function returns.

#### Parameters

attr | an EVCardAttribute |
param_name | a parameter name |

Since: 1.12

### e_vcard_attribute_remove_param_value ()

    void
    e_vcard_attribute_remove_param_value (EVCardAttribute *attr,
                                          const gchar *param_name,
                                          const gchar *s);

Removes the value `s` from the parameter `param_name` on the attribute `attr` . If `s` was the only value for parameter `param_name` , that parameter is removed entirely from `attr` and freed.

#### Parameters

attr | an EVCardAttribute |
param_name | a parameter name |
s | a value |

### e_vcard_attribute_param_new ()

    EVCardAttributeParam *
    e_vcard_attribute_param_new (const gchar *name);

Creates a new parameter named `name` .

#### Parameters

name | the name of the new parameter |

#### Returns

A new EVCardAttributeParam.

[transfer full]

### e_vcard_attribute_param_free ()

    void
    e_vcard_attribute_param_free (EVCardAttributeParam *param);

Frees `param` and its values.

#### Parameters

param | an EVCardAttributeParam. | [transfer full]

### e_vcard_attribute_param_copy ()

    EVCardAttributeParam *
    e_vcard_attribute_param_copy (EVCardAttributeParam *param);

Makes a copy of `param` and all its values.

#### Parameters

param | an EVCardAttributeParam |

#### Returns

a new EVCardAttributeParam identical to `param` .

[transfer full]

### e_vcard_attribute_add_param ()

    void
    e_vcard_attribute_add_param (EVCardAttribute *attr,
                                 EVCardAttributeParam *param);

Prepends `param` to `attr` 's list of parameters. This takes ownership of `param` (and all its values).

Duplicate parameters have their values merged, so that all parameter names in `attr` are unique. Values are also merged so that uniqueness is preserved.

#### Parameters

attr | an EVCardAttribute |
param | an EVCardAttributeParam to add. | [transfer full]

### e_vcard_attribute_add_param_with_value ()

    void
    e_vcard_attribute_add_param_with_value
                                   (EVCardAttribute *attr,
                                    EVCardAttributeParam *param,
                                    const gchar *value);

Appends `value` to `param` , then prepends `param` to `attr` . This takes ownership of `param` , but not of `value` .

This is a convenience method for `e_vcard_attribute_param_add_value()` and `e_vcard_attribute_add_param()`.

#### Parameters

attr | an EVCardAttribute |
param | an EVCardAttributeParam. | [transfer full]
value | a string value |

### e_vcard_attribute_add_param_with_values ()

    void
    e_vcard_attribute_add_param_with_values
                                   (EVCardAttribute *attr,
                                    EVCardAttributeParam *param,
                                    ...);

Appends the list of values to `param` , then prepends `param` to `attr` . This takes ownership of `param` , but not of the list of values.

This is a convenience method for `e_vcard_attribute_param_add_value()` and `e_vcard_attribute_add_param()`.

#### Parameters

attr | an EVCardAttribute |
param | an EVCardAttributeParam. | [transfer full]
... | a `NULL`-terminated list of strings |

### e_vcard_attribute_param_add_value ()

    void
    e_vcard_attribute_param_add_value (EVCardAttributeParam *param,
                                       const gchar *value);

Appends `value` to `param` 's list of values.

#### Parameters

param | an EVCardAttributeParam |
value | a string value to add |

### e_vcard_attribute_param_add_values ()

    void
    e_vcard_attribute_param_add_values (EVCardAttributeParam *param,
                                        ...);

Appends a list of values to `param` .

#### Parameters

param | an EVCardAttributeParam |
... | a `NULL`-terminated list of strings |

### e_vcard_attribute_param_remove_values ()

    void
    e_vcard_attribute_param_remove_values (EVCardAttributeParam *param);

Removes and frees all values from `param` .

#### Parameters

param | an EVCardAttributeParam |

### e_vcard_get_attribute ()

    EVCardAttribute *
    e_vcard_get_attribute (EVCard *evc,
                           const gchar *name);

Get the attribute `name` from `evc` . The EVCardAttribute is owned by `evcard` and should not be freed. If the attribute does not exist, `NULL` is returned.

This will only return the first attribute with the given `name`. To get other attributes of that name (for example, other `TEL` attributes if a contact has multiple telephone numbers), use `e_vcard_get_attributes()` and iterate over the list searching for matching attributes.

This method iterates over all attributes in the EVCard, so should not be called often. If extracting a large number of attributes from a vCard, it is more efficient to iterate once over the list returned by `e_vcard_get_attributes()`.

#### Parameters

evc | an EVCard |
name | the name of the attribute to get |

#### Returns

An EVCardAttribute if found, or `NULL`.

[transfer none][allow-none]

### e_vcard_get_attribute_if_parsed ()

    EVCardAttribute *
    e_vcard_get_attribute_if_parsed (EVCard *evc,
                                     const gchar *name);

Similar to `e_vcard_get_attribute()` but this method will not attempt to parse the vCard if it is not already parsed.

#### Parameters

evc | an EVCard |
name | the name of the attribute to get |

#### Returns

An EVCardAttribute if found, or `NULL`.

[transfer none][allow-none]

Since: 3.4

### e_vcard_get_attributes ()

    GList *
    e_vcard_get_attributes (EVCard *evcard);

Gets the list of all attributes from `evcard` . The list and its contents are owned by `evcard` , and must not be freed.

#### Parameters

evcard | an EVCard |

#### Returns

A list of attributes of type EVCardAttribute.

[transfer none][element-type EVCardAttribute]

### e_vcard_attribute_get_group ()

    const gchar *
    e_vcard_attribute_get_group (EVCardAttribute *attr);

Gets the group name of `attr` .

#### Parameters

attr | an EVCardAttribute |

#### Returns

The attribute's group name, or `NULL`.

[allow-none]

### e_vcard_attribute_get_name ()

    const gchar *
    e_vcard_attribute_get_name (EVCardAttribute *attr);

Gets the name of `attr` .

#### Parameters

attr | an EVCardAttribute |

#### Returns

The attribute's name.

### e_vcard_attribute_get_values ()

    GList *
    e_vcard_attribute_get_values (EVCardAttribute *attr);

Gets the ordered list of values from `attr` . The list and its contents are owned by `attr` , and must not be freed.

For example, for an `ADR` (postal address) attribute, this will return the components of the postal address.

This may be called on a single-valued attribute (i.e. one for which `e_vcard_attribute_is_single_valued()` returns `TRUE`) and will return a one-element list in that case. Alternatively, use `e_vcard_attribute_get_value()` in such cases.

#### Parameters

attr | an EVCardAttribute |

#### Returns

A list of string values. They will all be non-`NULL`, but may be empty strings. The list itself may be empty.

[transfer none][element-type utf8]

### e_vcard_attribute_get_values_decoded ()

    GList *
    e_vcard_attribute_get_values_decoded (EVCardAttribute *attr);

Gets the ordered list of values from `attr` , decoding them if necessary according to the encoding given in the vCard’s

`ENCODING` attribute. The list and its contents are owned by

`attr` , and must not be freed.

This may be called on a single-valued attribute (i.e. one for which `e_vcard_attribute_is_single_valued()` returns `TRUE`) and will return a one-element list in that case. Alternatively, use `e_vcard_attribute_get_value_decoded()` in such cases.

#### Parameters

attr | an EVCardAttribute |

#### Returns

A list of values of type GString.

[transfer none][element-type GString]

### e_vcard_attribute_is_single_valued ()

    gboolean
    e_vcard_attribute_is_single_valued (EVCardAttribute *attr);

Checks if `attr` has a single value.

#### Parameters

attr | an EVCardAttribute |

#### Returns

`TRUE` if the attribute has exactly one value, `FALSE` otherwise.

### e_vcard_attribute_get_value ()

    gchar *
    e_vcard_attribute_get_value (EVCardAttribute *attr);

Gets the value of a single-valued EVCardAttribute, `attr` .

For example, for a `FN` (full name) attribute, this will return the contact’s full name as a single string.

This will print a warning if called on an EVCardAttribute which is not single-valued (i.e. for which `e_vcard_attribute_is_single_valued()` returns `FALSE`). Use `e_vcard_attribute_get_values()` in such cases instead.

#### Parameters

attr | an EVCardAttribute |

#### Returns

A newly allocated string representing the value, or `NULL` if the attribute has no value.

[allow-none][transfer full]

### e_vcard_attribute_get_value_decoded ()

    GString *
    e_vcard_attribute_get_value_decoded (EVCardAttribute *attr);

Gets the value of a single-valued EVCardAttribute, `attr` , decoding it if necessary according to the encoding given in the vCard’s

`ENCODING` attribute.

This will print a warning if called on an EVCardAttribute which is not single-valued (i.e. for which `e_vcard_attribute_is_single_valued()` returns `FALSE`). Use `e_vcard_attribute_get_values_decoded()` in such cases instead.

#### Parameters

attr | an EVCardAttribute |

#### Returns

A newly allocated GString representing the value, or `NULL` if the attribute has no value.

[allow-none][transfer full]

### e_vcard_attribute_get_params ()

    GList *
    e_vcard_attribute_get_params (EVCardAttribute *attr);

Gets the list of parameters (of type EVCardAttributeParam) from `attr` . The list and its contents are owned by `attr` , and must not be freed.

#### Parameters

attr | an EVCardAttribute |

#### Returns

A list of elements of type EVCardAttributeParam.

[transfer none][element-type EVCardAttributeParam]

### e_vcard_attribute_get_param ()

    GList *
    e_vcard_attribute_get_param (EVCardAttribute *attr,
                                 const gchar *name);

Gets the list of values for the paramater `name` from `attr` . The list and its contents are owned by `attr` , and must not be freed. If no parameter with the given `name` exists, `NULL` is returned.

#### Parameters

attr | an EVCardAttribute |
name | a parameter name |

#### Returns

A list of string elements representing the parameter's values, or `NULL`.

[transfer none][element-type utf8][allow-none]

### e_vcard_attribute_param_get_name ()

    const gchar *
    e_vcard_attribute_param_get_name (EVCardAttributeParam *param);

Gets the name of `param` .

For example, for the only parameter of the vCard attribute:

    1
    TEL;TYPE=WORK,VOICE:(111) 555-1212

this would return `TYPE` (which is string-equivalent to `EVC_TYPE`).

#### Parameters

param | an EVCardAttributeParam |

#### Returns

The name of the parameter.

### e_vcard_attribute_param_get_values ()

    GList *
    e_vcard_attribute_param_get_values (EVCardAttributeParam *param);

Gets the list of values from `param` . The list and its contents are owned by `param` , and must not be freed.

For example, for the `TYPE` parameter of the vCard attribute:

    1
    TEL;TYPE=WORK,VOICE:(111) 555-1212

this would return the list `WORK`, `VOICE`.

#### Parameters

param | an EVCardAttributeParam |

#### Returns

A list of string elements representing the parameter's values.

[transfer none][element-type utf8]

### e_vcard_attribute_has_type ()

    gboolean
    e_vcard_attribute_has_type (EVCardAttribute *attr,
                                const gchar *typestr);

Checks if `attr` has an EVCardAttributeParam with name `EVC_TYPE` and `typestr` as one of its values.

For example, for the vCard attribute:

    1
    TEL;TYPE=WORK,VOICE:(111) 555-1212

the following holds true:

    1
    2
    3
    g_assert (e_vcard_attribute_has_type (attr, "WORK") == TRUE);
    g_assert (e_vcard_attribute_has_type (attr, "voice") == TRUE);
    g_assert (e_vcard_attribute_has_type (attr, "HOME") == FALSE);

Comparisons against `typestr` are case-insensitive.

#### Parameters

attr | an EVCardAttribute |
typestr | a string representing the type |

#### Returns

`TRUE` if such a parameter exists, `FALSE` otherwise.

### e_vcard_escape_string ()

    gchar *
    e_vcard_escape_string (const gchar *s);

Escapes a string according to RFC2426, section 5.

#### Parameters

s | the string to escape |

#### Returns

A newly allocated, escaped string.

[transfer full]

### e_vcard_unescape_string ()

    gchar *
    e_vcard_unescape_string (const gchar *s);

Unescapes a string according to RFC2426, section 5.

#### Parameters

s | the string to unescape |

#### Returns

A newly allocated, unescaped string.

[transfer full]

### e_vcard_util_set_x_attribute ()

    void
    e_vcard_util_set_x_attribute (EVCard *vcard,
                                  const gchar *x_name,
                                  const gchar *value);

Sets an "X-" attribute `x_name` to value `value` in `vcard` , or removes it from `vcard` , when `value` is `NULL`.

#### Parameters

vcard | an EVCard |
x_name | the attribute name, which starts with "X-" |
value | the value to set, or `NULL` to unset. | [nullable]

Since: 3.26

### e_vcard_util_dup_x_attribute ()

    gchar *
    e_vcard_util_dup_x_attribute (EVCard *vcard,
                                  const gchar *x_name);

#### Parameters

vcard | an EVCard |
x_name | the attribute name, which starts with "X-" |

#### Returns

Value of attribute `x_name` , or `NULL`, when there is no such attribute. Free the returned pointer with `g_free()`, when no longer needed.

[nullable][transfer full]

Since: 3.26

## Types and Values

### EVC_ADR

    #define EVC_ADR				"ADR"

### EVC_BDAY

    #define EVC_BDAY			"BDAY"

### EVC_CALURI

    #define EVC_CALURI			"CALURI"

### EVC_CATEGORIES

    #define EVC_CATEGORIES			"CATEGORIES"

### EVC_EMAIL

    #define EVC_EMAIL			"EMAIL"

### EVC_ENCODING

    #define EVC_ENCODING			"ENCODING"

### EVC_FBURL

    #define EVC_FBURL			"FBURL"

### EVC_FN

    #define EVC_FN				"FN"

### EVC_GEO

    #define EVC_GEO				"GEO"

Since: 1.12

### EVC_ICSCALENDAR

    #define EVC_ICSCALENDAR			"ICSCALENDAR"

### EVC_KEY

    #define EVC_KEY				"KEY"

### EVC_LABEL

    #define EVC_LABEL			"LABEL"

### EVC_LOGO

    #define EVC_LOGO			"LOGO"

### EVC_MAILER

    #define EVC_MAILER			"MAILER"

### EVC_NICKNAME

    #define EVC_NICKNAME			"NICKNAME"

### EVC_N

    #define EVC_N				"N"

### EVC_NOTE

    #define EVC_NOTE			"NOTE"

### EVC_ORG

    #define EVC_ORG				"ORG"

### EVC_PHOTO

    #define EVC_PHOTO			"PHOTO"

### EVC_PRODID

    #define EVC_PRODID			"PRODID"

### EVC_QUOTEDPRINTABLE

    #define EVC_QUOTEDPRINTABLE		"QUOTED-PRINTABLE"

### EVC_REV

    #define EVC_REV				"REV"

### EVC_ROLE

    #define EVC_ROLE			"ROLE"

### EVC_TEL

    #define EVC_TEL				"TEL"

### EVC_TITLE

    #define EVC_TITLE			"TITLE"

### EVC_TYPE

    #define EVC_TYPE			"TYPE"

### EVC_UID

    #define EVC_UID				"UID"

### EVC_URL

    #define EVC_URL				"URL"

### EVC_VALUE

    #define EVC_VALUE			"VALUE"

### EVC_VERSION

    #define EVC_VERSION			"VERSION"

### EVC_X_AIM

    #define EVC_X_AIM			"X-AIM"

### EVC_X_ANNIVERSARY

    #define EVC_X_ANNIVERSARY		"X-EVOLUTION-ANNIVERSARY"

### EVC_X_ASSISTANT

    #define EVC_X_ASSISTANT			"X-EVOLUTION-ASSISTANT"

### EVC_X_BIRTHDAY

    #define EVC_X_BIRTHDAY			"X-EVOLUTION-BIRTHDAY"

### EVC_X_BLOG_URL

    #define EVC_X_BLOG_URL			"X-EVOLUTION-BLOG-URL"

### EVC_X_CALLBACK

    #define EVC_X_CALLBACK			"X-EVOLUTION-CALLBACK"

### EVC_X_COMPANY

    #define EVC_X_COMPANY			"X-EVOLUTION-COMPANY"

### EVC_X_DEST_CONTACT_UID

    #define EVC_X_DEST_CONTACT_UID		"X-EVOLUTION-DEST-CONTACT-UID"

### EVC_X_DEST_EMAIL_NUM

    #define EVC_X_DEST_EMAIL_NUM		"X-EVOLUTION-DEST-EMAIL-NUM"

### EVC_X_DEST_HTML_MAIL

    #define EVC_X_DEST_HTML_MAIL		"X-EVOLUTION-DEST-HTML-MAIL"

### EVC_X_DEST_SOURCE_UID

    #define EVC_X_DEST_SOURCE_UID		"X-EVOLUTION-DEST-SOURCE-UID"

### EVC_X_E164

    #define EVC_X_E164			"X-EVOLUTION-E164"

### EVC_X_FILE_AS

    #define EVC_X_FILE_AS			"X-EVOLUTION-FILE-AS"

### EVC_X_GADUGADU

    #define EVC_X_GADUGADU			"X-GADUGADU"

### EVC_X_GROUPWISE

    #define EVC_X_GROUPWISE			"X-GROUPWISE"

### EVC_X_ICQ

    #define EVC_X_ICQ			"X-ICQ"

### EVC_X_JABBER

    #define EVC_X_JABBER			"X-JABBER"

### EVC_X_LIST_SHOW_ADDRESSES

    #define EVC_X_LIST_SHOW_ADDRESSES "X-EVOLUTION-LIST-SHOW-ADDRESSES"

### EVC_X_LIST

    #define EVC_X_LIST			"X-EVOLUTION-LIST"

### EVC_X_LIST_NAME

    #define EVC_X_LIST_NAME			"X-EVOLUTION-LIST-NAME"

Since: 3.2

### EVC_X_MANAGER

    #define EVC_X_MANAGER			"X-EVOLUTION-MANAGER"

### EVC_X_MSN

    #define EVC_X_MSN			"X-MSN"

### EVC_X_RADIO

    #define EVC_X_RADIO			"X-EVOLUTION-RADIO"

### EVC_X_SKYPE

    #define EVC_X_SKYPE			"X-SKYPE"

Since: 2.26

### EVC_X_GOOGLE_TALK

    #define EVC_X_GOOGLE_TALK		"X-GOOGLE-TALK"

Since: 3.2

### EVC_X_TWITTER

    #define EVC_X_TWITTER			"X-TWITTER"

Twitter name(s).

Since: 3.6

### EVC_X_SIP

    #define EVC_X_SIP			"X-SIP"

Since: 2.26

### EVC_X_SPOUSE

    #define EVC_X_SPOUSE			"X-EVOLUTION-SPOUSE"

### EVC_X_TELEX

    #define EVC_X_TELEX			"X-EVOLUTION-TELEX"

### EVC_X_TTYTDD

    #define EVC_X_TTYTDD			"X-EVOLUTION-TTYTDD"

### EVC_X_VIDEO_URL

    #define EVC_X_VIDEO_URL			"X-EVOLUTION-VIDEO-URL"

### EVC_X_WANTS_HTML

    #define EVC_X_WANTS_HTML		"X-MOZILLA-HTML"

### EVC_X_YAHOO

    #define EVC_X_YAHOO			"X-YAHOO"

### EVC_X_BOOK_UID

    #define EVC_X_BOOK_UID			"X-EVOLUTION-BOOK-UID"

Since: 3.6

### EVC_CONTACT_LIST

    #define EVC_CONTACT_LIST		"X-EVOLUTION-CONTACT-LIST-INFO"

Since: 3.2

### EVC_PARENT_CL

    #define EVC_PARENT_CL			"X-EVOLUTION-PARENT-UID"

Since: 3.2

### EVC_CL_UID

    #define EVC_CL_UID			"X-EVOLUTION-CONTACT-LIST-UID"

Since: 3.2

### EVC_X_DEST_EMAIL

    #define EVC_X_DEST_EMAIL		"X-EVOLUTION-DEST-EMAIL"

`EVC_X_DEST_EMAIL` is deprecated and should not be used in newly-written code.

### EVC_X_DEST_NAME

    #define EVC_X_DEST_NAME			"X-EVOLUTION-DEST-NAME"

`EVC_X_DEST_NAME` is deprecated and should not be used in newly-written code.

### enum EVCardFormat

`EVCardFormat` is deprecated and should not be used in newly-written code.

#### Members

EVC_FORMAT_VCARD_21 |  |
EVC_FORMAT_VCARD_30 |  |

### E_TYPE_VCARD_PARAM_ATTRIBUTE

    #define E_TYPE_VCARD_PARAM_ATTRIBUTE  (e_vcard_attribute_param_get_type ())

### E_VCARD_21_VALID_PROPERTIES

    #define             E_VCARD_21_VALID_PROPERTIES

FIXME: Document me!

Since: 3.4

### E_VCARD_21_VALID_PARAMETERS

    #define             E_VCARD_21_VALID_PARAMETERS

FIXME: Document me!

Since: 3.4