EVCard

EVCard — vCard parsing and interpretation

Stability Level

Stable, unless otherwise indicated

Synopsis

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

#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
struct              EVCard;
void                e_vcard_construct                   (EVCard *evc,
                                                         const gchar *str);
void                e_vcard_construct_with_uid          (EVCard *evc,
                                                         const gchar *str,
                                                         const gchar *uid);
EVCard *            e_vcard_new                         (void);
EVCard *            e_vcard_new_from_string             (const gchar *str);
gboolean            e_vcard_is_parsed                   (EVCard *evc);
gchar *             e_vcard_to_string                   (EVCard *evc,
                                                         EVCardFormat format);
void                e_vcard_dump_structure              (EVCard *evc);
EVCardAttribute *   e_vcard_attribute_new               (const gchar *attr_group,
                                                         const gchar *attr_name);
void                e_vcard_attribute_free              (EVCardAttribute *attr);
EVCardAttribute *   e_vcard_attribute_copy              (EVCardAttribute *attr);
void                e_vcard_remove_attributes           (EVCard *evc,
                                                         const gchar *attr_group,
                                                         const gchar *attr_name);
void                e_vcard_remove_attribute            (EVCard *evc,
                                                         EVCardAttribute *attr);
void                e_vcard_append_attribute            (EVCard *evc,
                                                         EVCardAttribute *attr);
void                e_vcard_append_attribute_with_value (EVCard *evcard,
                                                         EVCardAttribute *attr,
                                                         const gchar *value);
void                e_vcard_append_attribute_with_values
                                                        (EVCard *evcard,
                                                         EVCardAttribute *attr,
                                                         ...);
void                e_vcard_add_attribute               (EVCard *evc,
                                                         EVCardAttribute *attr);
void                e_vcard_add_attribute_with_value    (EVCard *evcard,
                                                         EVCardAttribute *attr,
                                                         const gchar *value);
void                e_vcard_add_attribute_with_values   (EVCard *evcard,
                                                         EVCardAttribute *attr,
                                                         ...);
void                e_vcard_attribute_add_value         (EVCardAttribute *attr,
                                                         const gchar *value);
void                e_vcard_attribute_add_value_decoded (EVCardAttribute *attr,
                                                         const gchar *value,
                                                         gint len);
void                e_vcard_attribute_add_values        (EVCardAttribute *attr,
                                                         ...);
void                e_vcard_attribute_remove_value      (EVCardAttribute *attr,
                                                         const gchar *s);
void                e_vcard_attribute_remove_values     (EVCardAttribute *attr);
void                e_vcard_attribute_remove_params     (EVCardAttribute *attr);
void                e_vcard_attribute_remove_param      (EVCardAttribute *attr,
                                                         const gchar *param_name);
void                e_vcard_attribute_remove_param_value
                                                        (EVCardAttribute *attr,
                                                         const gchar *param_name,
                                                         const gchar *s);
EVCardAttributeParam * e_vcard_attribute_param_new      (const gchar *name);
void                e_vcard_attribute_param_free        (EVCardAttributeParam *param);
EVCardAttributeParam * e_vcard_attribute_param_copy     (EVCardAttributeParam *param);
void                e_vcard_attribute_add_param         (EVCardAttribute *attr,
                                                         EVCardAttributeParam *param);
void                e_vcard_attribute_add_param_with_value
                                                        (EVCardAttribute *attr,
                                                         EVCardAttributeParam *param,
                                                         const gchar *value);
void                e_vcard_attribute_add_param_with_values
                                                        (EVCardAttribute *attr,
                                                         EVCardAttributeParam *param,
                                                         ...);
void                e_vcard_attribute_param_add_value   (EVCardAttributeParam *param,
                                                         const gchar *value);
void                e_vcard_attribute_param_add_values  (EVCardAttributeParam *param,
                                                         ...);
void                e_vcard_attribute_param_remove_values
                                                        (EVCardAttributeParam *param);
EVCardAttribute *   e_vcard_get_attribute               (EVCard *evc,
                                                         const gchar *name);
EVCardAttribute *   e_vcard_get_attribute_if_parsed     (EVCard *evc,
                                                         const gchar *name);
GList *             e_vcard_get_attributes              (EVCard *evcard);
const gchar *       e_vcard_attribute_get_group         (EVCardAttribute *attr);
const gchar *       e_vcard_attribute_get_name          (EVCardAttribute *attr);
GList *             e_vcard_attribute_get_values        (EVCardAttribute *attr);
GList *             e_vcard_attribute_get_values_decoded
                                                        (EVCardAttribute *attr);
gboolean            e_vcard_attribute_is_single_valued  (EVCardAttribute *attr);
gchar *             e_vcard_attribute_get_value         (EVCardAttribute *attr);
GString *           e_vcard_attribute_get_value_decoded (EVCardAttribute *attr);
GList *             e_vcard_attribute_get_params        (EVCardAttribute *attr);
GList *             e_vcard_attribute_get_param         (EVCardAttribute *attr,
                                                         const gchar *name);
const gchar *       e_vcard_attribute_param_get_name    (EVCardAttributeParam *param);
GList *             e_vcard_attribute_param_get_values  (EVCardAttributeParam *param);
gboolean            e_vcard_attribute_has_type          (EVCardAttribute *attr,
                                                         const gchar *typestr);
gchar *             e_vcard_escape_string               (const gchar *s);
gchar *             e_vcard_unescape_string             (const gchar *s);
                    EVCardAttribute;
                    EVCardAttributeParam;

Object Hierarchy

  GObject
   +----EVCard
         +----EContact
  GBoxed
   +----EVCardAttribute
  GBoxed
   +----EVCardAttributeParam

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

Details

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"

Warning

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"

Warning

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


enum EVCardFormat

typedef enum {
	EVC_FORMAT_VCARD_21,
	EVC_FORMAT_VCARD_30
} EVCardFormat;

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


struct EVCard

struct EVCard;

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.

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.

evc :

an existing EVCard

str :

a vCard string

uid :

a unique ID string. [allow-none]

Since 3.4


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.

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.

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.

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.

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.

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.

attr :

attribute to free. [transfer full]

e_vcard_attribute_copy ()

EVCardAttribute *   e_vcard_attribute_copy              (EVCardAttribute *attr);

Makes a copy of attr.

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.

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.

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.

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

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

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.

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

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

Note

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

s :

the string to unescape

Returns :

A newly allocated, unescaped string. [transfer full]

EVCardAttribute

typedef struct _EVCardAttribute EVCardAttribute;

EVCardAttributeParam

typedef struct _EVCardAttributeParam EVCardAttributeParam;