VCard


Object Hierarchy:

Object hierarchy for VCard

Description:

[ CCode ( type_id = "e_vcard_get_type ()" ) ]
public class VCard : Object

VCard 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:

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 VCard API, this data is accessible as follows:

Accessing a Multi-Valued Attribute:

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 get_attributes, then matching on 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 get_value do not need further decoding. The ‘decoded’ functions, get_value_decoded and get_values_decoded are only relevant when adding attributes which use pre-encoded values and have their ENCODING parameter set.

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

VCard 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 is_parsed.

All known sub-classes:

Namespace: E

Content:

Static methods:

Creation methods:

Methods:

Inherited Members: