| Top |
GBoxed ├── EVCardAttribute ╰── EVCardAttributeParam GObject ╰── EVCard ╰── EContact
EVCard is a low-level representation of a vCard, as specified in RFCs 2425 and 2426 (for vCard version 3.0) and RFC 6350 (for vCard version 4.0) with some of its extensions; this class only supports versions 2.1, 3.0 and 4.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_true (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().
EVCard *
e_vcard_new_from_string (const gchar *str);
Creates a new EVCard from the passed-in string representation.
void e_vcard_construct (EVCard *evc,const gchar *str);
Constructs the existing EVCard, evc
, setting its vCard data to str
.
This modifies evc
.
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
.
Since: 3.4
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.
evc |
an existing EVCard |
|
str |
a vCard string |
|
len |
length of |
|
uid |
a unique ID string. |
[nullable] |
Since: 3.12
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.
Since: 3.2
gchar *
e_vcard_to_string (EVCard *self);
Exports self
to a string representation. To use a specific vCard version
use e_vcard_convert_to_string().
Since: 3.60
EVCardVersion
e_vcard_get_version (EVCard *self);
Gets a vCard version of the self
. The E_VCARD_VERSION_UNKNOWN
is returned only if there is a VERSION attribute, but with an unknown
value. Otherwise an E_VCARD_VERSION_40 is used as a fallback version.
Since: 3.60
EVCard * e_vcard_convert (EVCard *self,EVCardVersion to_version);
Converts the self
into the vCard version to_version
and returns a converted
copy of the self
. When the to_version
matches the version of the self
,
then does nothing and returns NULL.
the self
converted to to_version
,
or NULL, when it is in this version already.
[transfer full][nullable]
Since: 3.60
gchar * e_vcard_convert_to_string (EVCard *self,EVCardVersion version);
Exports evc
to a string representation conforming to vCard
version version
.
Since: 3.60
gboolean (*EVCardForeachFunc) (EVCard *vcard,EVCardAttribute *attr,gpointer user_data);
A callback prototype for e_vcard_foreach() and e_vcard_foreach_remove().
the value depends on the function it is used with; see its documentation for more information
Since: 3.60
void e_vcard_foreach (EVCard *self,EVCardForeachFlags flags,EVCardForeachFunc func,gpointer user_data);
Calls func
for each attribute in the self
. The func
returns TRUE to
continue the walk-through, or FALSE to stop.
self |
an EVCard |
|
flags |
a bit-or of EVCardForeachFlags |
|
func |
an EVCardForeachFunc callback function. |
[scope call][closure user_data] |
user_data |
user data passed to the |
Since: 3.60
guint e_vcard_foreach_remove (EVCard *self,EVCardForeachFunc func,gpointer user_data);
Removes all attributes the func
returns TRUE for.
self |
an EVCard |
|
func |
an EVCardForeachFunc callback function. |
[scope call][closure user_data] |
user_data |
user data passed to the |
Since: 3.60
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.
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 *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.
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 *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().
See also e_vcard_append_attribute_with_value_take(), e_vcard_add_attribute_with_value()
evcard |
an EVCard |
|
attr |
an EVCardAttribute to append. |
[transfer full] |
value |
a value to assign to the attribute |
Since: 2.32
void e_vcard_append_attribute_with_value_take (EVCard *evcard,EVCardAttribute *attr,gchar *value);
Appends attr
to evcard
, setting it to value
. This takes ownership of
attr
and the value
.
This is a convenience wrapper around e_vcard_attribute_add_value_take() and
e_vcard_append_attribute().
See also e_vcard_append_attribute_with_value(), e_vcard_add_attribute_with_value()
evcard |
an EVCard |
|
attr |
an EVCardAttribute to append. |
[transfer full] |
value |
a value to assign to the attribute. |
[transfer full] |
Since: 3.60
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 EVCardAttribute to append. |
[transfer full] |
... |
a |
Since: 2.32
void e_vcard_append_attributes (EVCard *self,const GList *attrs);
Appends EVCardAttribute structures from attrs
to self
. The respective
attributes are copied, thus the caller is responsible to take care
of the attrs
and its content.
self |
an EVCard |
|
attrs |
a GList of EVCardAttribute. |
[element-type EVCardAttribute][transfer none] |
Since: 3.60
void e_vcard_append_attributes_take (EVCard *self,GList *attrs);
Appends EVCardAttribute structures from attrs
to self
. The self
assumes ownership of both the attrs
and the respective attributes
stored in it.
self |
an EVCard |
|
attrs |
a GList of EVCardAttribute. |
[element-type EVCardAttribute][transfer full] |
Since: 3.60
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 *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().
See also e_vcard_add_attribute_with_value_take(), e_vcard_append_attribute_with_value()
evcard |
an EVCard |
|
attr |
an EVCardAttribute to add. |
[transfer full] |
value |
a value to assign to the attribute |
void e_vcard_add_attribute_with_value_take (EVCard *evcard,EVCardAttribute *attr,gchar *value);
Prepends attr
to evcard
, setting it to value
. This takes ownership of
the attr
and the value
.
This is a convenience wrapper around e_vcard_attribute_add_value_take() and
e_vcard_add_attribute().
See also e_vcard_add_attribute_with_value(), e_vcard_append_attribute_with_value()
evcard |
an EVCard |
|
attr |
an EVCardAttribute to add. |
[transfer full] |
value |
a value to assign to the attribute. |
[transfer full] |
Since: 3.60
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().
evcard |
an |
|
attr |
an EVCardAttribute to add. |
[transfer full] |
... |
a |
void e_vcard_attribute_add_value (EVCardAttribute *attr,const gchar *value);
Appends value
to attr
's list of values.
See also e_vcard_attribute_add_value_take().
void e_vcard_attribute_add_value_take (EVCardAttribute *attr,gchar *value);
Appends value
to attr
's list of values, assuming ownership
of the value
.
See also e_vcard_attribute_add_value().
Since: 3.60
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).
void e_vcard_attribute_add_values (EVCardAttribute *attr,...);
Appends a list of values to attr
.
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.
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 EVCardAttribute's encoding back to raw.
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.
Since: 1.12
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.
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 *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().
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 *param,const 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 *evc,const gchar *name);
Get the attribute name
from evc
. The EVCardAttribute is owned by
evc
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().
GList * e_vcard_get_attributes_by_name (EVCard *self,const gchar *name);
Returns all attributes of the name name
stored in the self
.
See also e_vcard_get_attribute(), which returns the first
found attribute only.
The returned EVCardAttribute -s are owned by the self
and
they are valid until the self
changes. The returned GList
should be freed with g_list_free(), when no longer needed.
a new GList
of EVCardAttribute objects, which are named name
and stored in the self
, or NULL,
when the self
does not contain any such attribute. The attributes are in the list
in the order as they appear in the self
.
[transfer container][nullable][element-type EVCardAttribute]
Since: 3.60
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.
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.
const gchar *
e_vcard_attribute_get_group (EVCardAttribute *attr);
Gets the group name of attr
.
const gchar *
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) and will return a
one-element list in that case. Alternatively, use
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) and will return a
one-element list in that case. Alternatively, use
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 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.
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.
guint
e_vcard_attribute_get_n_values (EVCardAttribute *attr);
Gets how many values the attr
holds.
Since: 3.60
const gchar * e_vcard_attribute_get_nth_value (EVCardAttribute *attr,guint index);
Gets the value at index index
(counting from zero), of the attr
.
The value is owned by the attr
and is valid until the attr
changes
or is freed. The index
can be out of bounds, then a NULL is returned.
Use
to check how many values
the e_vcard_attribute_get_n_values()attr
has stored.
Since: 3.60
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.
A list of elements of type EVCardAttributeParam.
[transfer none][element-type EVCardAttributeParam]
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.
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).
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.
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_true (e_vcard_attribute_has_type (attr, "WORK") == TRUE); g_assert_true (e_vcard_attribute_has_type (attr, "voice") == TRUE); g_assert_true (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.
gchar *
e_vcard_unescape_string (const gchar *s);
Unescapes a string according to RFC2426, section 5.
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.
vcard |
an EVCard |
|
x_name |
the attribute name, which starts with "X-" |
|
value |
the value to set, or |
[nullable] |
Since: 3.26
gchar * e_vcard_util_dup_x_attribute (EVCard *vcard,const gchar *x_name);
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]
Since: 3.26
void
e_vcard_dump_structure (EVCard *evc);
Prints a dump of evc
's structure to stdout. Used for
debugging.
EVCardVersion
e_vcard_version_from_string (const gchar *str);
Converts the str
into one of the EVCardVersion. If the string
does not match any of the known values the E_VCARD_VERSION_UNKNOWN
is returned.
Since: 3.60
const gchar *
e_vcard_version_to_string (EVCardVersion version);
Converts the version
into its string representation.
Returns NULL, when the version
does not match any
known value (the E_VCARD_VERSION_UNKNOWN corresponds
to the "unknown" string).
Since: 3.60
#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 EVC_X_EVOLUTION_CLIENTPIDMAP E_VCARD_X_EVOLUTION_PREFIX (EVC_CLIENTPIDMAP)
#define EVC_X_EVOLUTION_CALADRURI E_VCARD_X_EVOLUTION_PREFIX (EVC_CALADRURI)
#define EVC_X_EVOLUTION_BIRTHPLACE E_VCARD_X_EVOLUTION_PREFIX (EVC_BIRTHPLACE)
#define EVC_X_EVOLUTION_DEATHPLACE E_VCARD_X_EVOLUTION_PREFIX (EVC_DEATHPLACE)
#define EVC_X_EVOLUTION_DEATHDATE E_VCARD_X_EVOLUTION_PREFIX (EVC_DEATHDATE)
#define EVC_X_EVOLUTION_EXPERTISE E_VCARD_X_EVOLUTION_PREFIX (EVC_EXPERTISE)
#define EVC_X_EVOLUTION_ORG_DIRECTORY E_VCARD_X_EVOLUTION_PREFIX (EVC_ORG_DIRECTORY)
#define EVC_X_EVOLUTION_CONTACT_URI E_VCARD_X_EVOLUTION_PREFIX (EVC_CONTACT_URI)
#define EVC_X_EVOLUTION_GRAMGENDER E_VCARD_X_EVOLUTION_PREFIX (EVC_GRAMGENDER)
#define EVC_X_SOCIALPROFILE "X-SOCIALPROFILE" /* RFC 9554 mentions it being used by others */
#define EVC_X_EVOLUTION_MEDIATYPE E_VCARD_X_EVOLUTION_PREFIX (EVC_MEDIATYPE)