Top | ![]() |
![]() |
![]() |
![]() |
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
Example 1. 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 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
e_vcard_is_parsed()
.
void e_vcard_construct (,
EVCard *evcconst
);gchar *str
Constructs the existing evc
, setting its vCard data to str
.
This modifies evc
.
void e_vcard_construct_with_uid (,
EVCard *evcconst
,gchar *strconst
);gchar *uid
Constructs the existing 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
.
Since: 3.4
void e_vcard_construct_full (,
EVCard *evcconst
,gchar *str,
gssize lenconst
);gchar *uid
Similar to e_vcard_construct_with_uid()
, but can also
be used with an str
that is not NULL
evc |
an existing |
|
str |
a vCard string |
|
len |
length of |
|
uid |
a unique ID string. |
[allow-none] |
Since: 3.12
EVCard * e_vcard_new_from_string (const
);gchar *str
Creates a new
gboolean e_vcard_is_parsed ();
EVCard *evc
Check if the evc
has been parsed already, as
Since: 3.2
gchar * e_vcard_to_string (,
EVCard *evcEVCardFormat format
);
Exports evc
to a string representation, specified
by the format
argument.
void e_vcard_dump_structure ();
EVCard *evc
Prints a dump of evc
's structure to stdout. Used for
debugging.
EVCardAttribute * e_vcard_attribute_new (const
,gchar *attr_groupconst
);gchar *attr_name
Creates a new attr_group
may be NULL
void e_vcard_attribute_free ();
EVCardAttribute *attr
Frees an attribute, its values and its parameters.
EVCardAttribute * e_vcard_attribute_copy ();
EVCardAttribute *attr
Makes a copy of attr
.
void e_vcard_remove_attributes (,
EVCard *evcconst
,gchar *attr_groupconst
);gchar *attr_name
Removes all the attributes with group name and attribute name equal to the
passed in values. If attr_group
is NULL
void e_vcard_remove_attribute (,
EVCard *evc);
EVCardAttribute *attr
Removes attr
from evc
and frees it. This takes ownership of attr
.
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
.
Since: 2.32
void e_vcard_append_attribute_with_value (,
EVCard *evcard,
EVCardAttribute *attrconst
);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()
.
evcard |
an |
|
attr |
an |
[transfer full] |
value |
a value to assign to the attribute |
Since: 2.32
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()
.
evcard |
an |
|
attr |
an |
[transfer full] |
... |
a |
Since: 2.32
void e_vcard_add_attribute (,
EVCard *evc);
EVCardAttribute *attr
Prepends attr
to evc
. This takes ownership of attr
.
void e_vcard_add_attribute_with_value (,
EVCard *evcard,
EVCardAttribute *attrconst
);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()
.
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()
.
void e_vcard_attribute_add_value (,
EVCardAttribute *attrconst
);gchar *value
Appends value
to attr
's list of values.
void e_vcard_attribute_add_value_decoded (,
EVCardAttribute *attrconst
,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
void e_vcard_attribute_add_values (,
EVCardAttribute *attr...
);
Appends a list of values to attr
.
void e_vcard_attribute_remove_value (,
EVCardAttribute *attrconst
);gchar *s
Removes value s
from the value list in attr
. The value s
is not freed.
void e_vcard_attribute_remove_values ();
EVCardAttribute *attr
Removes and frees all values from attr
.
void e_vcard_attribute_remove_params ();
EVCardAttribute *attr
Removes and frees all parameters from attr
.
This also resets the
void e_vcard_attribute_remove_param (,
EVCardAttribute *attrconst
);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.
Since: 1.12
void e_vcard_attribute_remove_param_value (,
EVCardAttribute *attrconst
,gchar *param_nameconst
);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.
EVCardAttributeParam * e_vcard_attribute_param_new (const
);gchar *name
Creates a new parameter named name
.
void e_vcard_attribute_param_free ();
EVCardAttributeParam *param
Frees param
and its values.
EVCardAttributeParam * e_vcard_attribute_param_copy ();
EVCardAttributeParam *param
Makes a copy of param
and all its values.
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.
void e_vcard_attribute_add_param_with_value (,
EVCardAttribute *attr,
EVCardAttributeParam *paramconst
);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()
.
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()
.
void e_vcard_attribute_param_add_value (,
EVCardAttributeParam *paramconst
);gchar *value
Appends value
to param
's list of values.
void e_vcard_attribute_param_add_values (,
EVCardAttributeParam *param...
);
Appends a list of values to param
.
void e_vcard_attribute_param_remove_values ();
EVCardAttributeParam *param
Removes and frees all values from param
.
EVCardAttribute * e_vcard_get_attribute (,
EVCard *evcconst
);gchar *name
Get the attribute name
from evc
. The evcard
and should not be freed. If the attribute does not exist, NULL
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 e_vcard_get_attributes()
.
EVCardAttribute * e_vcard_get_attribute_if_parsed (,
EVCard *evcconst
);gchar *name
Similar to e_vcard_get_attribute()
but this method will not attempt to
parse the vCard if it is not already parsed.
Since: 3.4
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.
constgchar * e_vcard_attribute_get_group ();
EVCardAttribute *attr
Gets the group name of attr
.
constgchar * e_vcard_attribute_get_name ();
EVCardAttribute *attr
Gets the name of attr
.
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
e_vcard_attribute_get_value()
in such cases.
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
e_vcard_attribute_get_value_decoded()
in such cases.
gboolean e_vcard_attribute_is_single_valued ();
EVCardAttribute *attr
Checks if attr
has a single value.
gchar * e_vcard_attribute_get_value ();
EVCardAttribute *attr
Gets the value of a single-valued 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 e_vcard_attribute_is_single_valued()
returns
FALSE
e_vcard_attribute_get_values()
in such cases instead.
GString * e_vcard_attribute_get_value_decoded ();
EVCardAttribute *attr
Gets the value of a single-valued 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 e_vcard_attribute_is_single_valued()
returns
FALSE
e_vcard_attribute_get_values_decoded()
in such cases instead.
GList * e_vcard_attribute_get_params ();
EVCardAttribute *attr
Gets the list of parameters (of type attr
. The
list and its contents are owned by attr
, and must not be freed.
GList * e_vcard_attribute_get_param (,
EVCardAttribute *attrconst
);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
constgchar * e_vcard_attribute_param_get_name ();
EVCardAttributeParam *param
Gets the name of param
.
For example, for the only parameter of the vCard attribute:
TEL;TYPE=WORK,VOICE:(111) 555-1212
this would return TYPE
(which is string-equivalent to
EVC_TYPE
).
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:
TEL;TYPE=WORK,VOICE:(111) 555-1212
this would return the list WORK
, VOICE
.
gboolean e_vcard_attribute_has_type (,
EVCardAttribute *attrconst
);gchar *typestr
Checks if attr
has an EVC_TYPE
and typestr
as one of its values.
For example, for the vCard attribute:
TEL;TYPE=WORK,VOICE:(111) 555-1212
the following holds true:
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.
gchar * e_vcard_escape_string (const
);gchar *s
Escapes a string according to RFC2426, section 5.
#define EVC_X_DEST_EMAIL "X-EVOLUTION-DEST-EMAIL"
EVC_X_DEST_EMAIL
is deprecated and should not be used in newly-written code.
#define EVC_X_DEST_NAME "X-EVOLUTION-DEST-NAME"
EVC_X_DEST_NAME
is deprecated and should not be used in newly-written code.
#define E_TYPE_VCARD_PARAM_ATTRIBUTE (e_vcard_attribute_param_get_type ())