EVCard

## EVCard EVCard — Contact data in the VCard format. |

## Synopsis

                EVCard;
    enum        EVCardFormat;
                EVCardAttribute;
                EVCardAttributeParam;
    EVCard*     e_vcard_new                     (void);
    EVCard*     e_vcard_new_from_string         (const char *str);
    char*       e_vcard_to_string               (EVCard *evc,
                                                 EVCardFormat format);
    void        e_vcard_dump_structure          (EVCard *evc);
    EVCardAttribute* e_vcard_attribute_new      (const char *attr_group,
                                                 const char *attr_name);
    void        e_vcard_attribute_free          (EVCardAttribute *attr);
    EVCardAttribute* e_vcard_attribute_copy     (EVCardAttribute *attr);
    void        e_vcard_remove_attributes       (EVCard *evc,
                                                 const char *attr_group,
                                                 const char *attr_name);
    void        e_vcard_remove_attribute        (EVCard *evc,
                                                 EVCardAttribute *attr);
    void        e_vcard_add_attribute           (EVCard *evc,
                                                 EVCardAttribute *attr);
    void        e_vcard_add_attribute_with_value
                                                (EVCard *evcard,
                                                 EVCardAttribute *attr,
                                                 const char *value);
    void        e_vcard_add_attribute_with_values
                                                (EVCard *evcard,
                                                 EVCardAttribute *attr,
                                                 ...);
    void        e_vcard_attribute_add_value     (EVCardAttribute *attr,
                                                 const char *value);
    void        e_vcard_attribute_add_value_decoded
                                                (EVCardAttribute *attr,
                                                 const char *value,
                                                 int len);
    void        e_vcard_attribute_add_values    (EVCardAttribute *attr,
                                                 ...);
    void        e_vcard_attribute_remove_values (EVCardAttribute *attr);
    void        e_vcard_attribute_remove_params (EVCardAttribute *attr);
    EVCardAttributeParam* e_vcard_attribute_param_new
                                                (const char *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 char *value);
    void        e_vcard_attribute_add_param_with_values
                                                (EVCardAttribute *attr,
                                                 EVCardAttributeParam *param,
                                                 ...);
    void        e_vcard_attribute_param_add_value
                                                (EVCardAttributeParam *param,
                                                 const char *value);
    void        e_vcard_attribute_param_add_values
                                                (EVCardAttributeParam *param,
                                                 ...);
    void        e_vcard_attribute_param_remove_values
                                                (EVCardAttributeParam *param);
    const char* e_vcard_attribute_param_get_name
                                                (EVCardAttributeParam *param);
    GList*      e_vcard_attribute_param_get_values
                                                (EVCardAttributeParam *param);
    EVCardAttribute* e_vcard_get_attribute      (EVCard *evc,
                                                 const char *name);
    GList*      e_vcard_get_attributes          (EVCard *evcard);
    const char* e_vcard_attribute_get_group     (EVCardAttribute *attr);
    const char* e_vcard_attribute_get_name      (EVCardAttribute *attr);
    GList*      e_vcard_attribute_get_values    (EVCardAttribute *attr);
    GList*      e_vcard_attribute_get_values_decoded
                                                (EVCardAttribute *attr);
    GList*      e_vcard_attribute_get_params    (EVCardAttribute *attr);
    char*       e_vcard_attribute_get_value     (EVCardAttribute *attr);
    GString*    e_vcard_attribute_get_value_decoded
                                                (EVCardAttribute *attr);
    gboolean    e_vcard_attribute_has_type      (EVCardAttribute *attr,
                                                 const char *typestr);
    gboolean    e_vcard_attribute_is_single_valued
                                                (EVCardAttribute *attr);
    char*       e_vcard_escape_string           (const char *s);
    char*       e_vcard_unescape_string         (const char *s);
    #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_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_FILE_AS
    #define     EVC_X_ICQ
    #define     EVC_X_JABBER
    #define     EVC_X_LIST_SHOW_ADDRESSES
    #define     EVC_X_LIST
    #define     EVC_X_MANAGER
    #define     EVC_X_MSN
    #define     EVC_X_SPOUSE
    #define     EVC_X_WANTS_HTML
    #define     EVC_X_YAHOO
    #define     EVC_X_BOOK_URI
    #define     EVC_X_CALLBACK
    #define     EVC_X_COMPANY
    #define     EVC_X_DEST_CONTACT_UID
    #define     EVC_X_DEST_EMAIL
    #define     EVC_X_DEST_EMAIL_NUM
    #define     EVC_X_DEST_HTML_MAIL
    #define     EVC_X_DEST_NAME
    #define     EVC_X_DEST_SOURCE_UID
    #define     EVC_X_GROUPWISE
    #define     EVC_X_RADIO
    #define     EVC_X_TELEX
    #define     EVC_X_TTYTDD
    #define     EVC_X_VIDEO_URL

## Object Hierarchy

      GObject
       +----EVCard
             +----EContact

## Description

Does the low-level parsing work for contact information. This data is more conveniently accessed through the EContact object.

## Details

### EVCard

    typedef struct _EVCard EVCard;

### enum EVCardFormat

    typedef enum {
    	EVC_FORMAT_VCARD_21,
    	EVC_FORMAT_VCARD_30
    } EVCardFormat;

### EVCardAttribute

    typedef struct _EVCardAttribute EVCardAttribute;

### EVCardAttributeParam

    typedef struct _EVCardAttributeParam EVCardAttributeParam;

### e_vcard_new ()

    EVCard*     e_vcard_new                     (void);

Creates a new, blank EVCard.

Returns : | A new, blank EVCard.

### e_vcard_new_from_string ()

    EVCard*     e_vcard_new_from_string         (const char *str);

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

`str` : | a string representation of the vcard to create
Returns : | A new EVCard.

### e_vcard_to_string ()

    char*       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.

### 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 char *attr_group,
                                                 const char *attr_name);

Creates a new EVCardAttribute with the specified group and attribute names.

`attr_group` : | a group name
`attr_name` : | an attribute name
Returns : | A new EVCardAttribute.

### e_vcard_attribute_free ()

    void        e_vcard_attribute_free          (EVCardAttribute *attr);

Frees an attribute, its values and its parameters.

`attr` : | attribute to free

### 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`.

### e_vcard_remove_attributes ()

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

Removes all the attributes with group name and attribute name equal to 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
`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.

`evc` : | an EVCard
`attr` : | an EVCardAttribute to remove

### e_vcard_add_attribute ()

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

Adds `attr` to `evc`.

`evc` : | an EVCard
`attr` : | an EVCardAttribute to add

### e_vcard_add_attribute_with_value ()

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

Adds `attr` to `evcard`, setting it to `value`.

`evcard` : | an EVCard
`attr` : | an EVCardAttribute to add
`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,
                                                 ...);

Adds `attr` to `evcard`, assigning the list of values to it.

`evcard` : | an `EVCard`
`attr` : | an EVCardAttribute to add
`...` : | 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 char *value);

Adds `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 char *value,
                                                 int len);

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

`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,
                                                 ...);

Adds a list of values to `attr`.

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

### e_vcard_attribute_remove_values ()

    void        e_vcard_attribute_remove_values (EVCardAttribute *attr);

Removes all values from `attr`.

`attr` : | an EVCardAttribute

### e_vcard_attribute_remove_params ()

    void        e_vcard_attribute_remove_params (EVCardAttribute *attr);

Removes all parameters from `attr`.

`attr` : | an EVCardAttribute

### e_vcard_attribute_param_new ()

    EVCardAttributeParam* e_vcard_attribute_param_new
                                                (const char *name);

Creates a new parameter named `name`.

`name` : | the name of the new parameter
Returns : | A new EVCardAttributeParam.

### e_vcard_attribute_param_free ()

    void        e_vcard_attribute_param_free    (EVCardAttributeParam *param);

Frees `param` and its values.

`param` : | an EVCardAttributeParam

### e_vcard_attribute_param_copy ()

    EVCardAttributeParam* e_vcard_attribute_param_copy
                                                (EVCardAttributeParam *param);

Makes a copy of `param`.

`param` : | an EVCardAttributeParam
Returns : | a new EVCardAttributeParam identical to `param`.

### e_vcard_attribute_add_param ()

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

Adds `param` to `attr`'s list of parameters.

`attr` : | an EVCardAttribute
`param` : | an EVCardAttributeParam to add

### e_vcard_attribute_add_param_with_value ()

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

Adds `value` to `param`, then adds `param` to `attr`.

`attr` : | an EVCardAttribute
`param` : | an EVCardAttributeParam
`value` : | a string value

### e_vcard_attribute_add_param_with_values ()

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

Adds the list of values to `param`, then adds `param` to `attr`.

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

### e_vcard_attribute_param_add_value ()

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

Adds `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,
                                                 ...);

Adds 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_attribute_param_get_name ()

    const char* e_vcard_attribute_param_get_name
                                                (EVCardAttributeParam *param);

Gets the name of `param`.

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

`param` : | an EVCardAttributeParam
Returns : | A list of string elements representing the parameter's values.

### e_vcard_get_attribute ()

    EVCardAttribute* e_vcard_get_attribute      (EVCard *evc,
                                                 const char *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.

`evc` : | an EVCard
`name` : | the name of the attribute to get
Returns : | An EVCardAttribute if found, or NULL.

### e_vcard_get_attributes ()

    GList*      e_vcard_get_attributes          (EVCard *evcard);

Gets the list of 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.

### e_vcard_attribute_get_group ()

    const char* e_vcard_attribute_get_group     (EVCardAttribute *attr);

Gets the group name of `attr`.

`attr` : | an EVCardAttribute
Returns : | The attribute's group name.

### e_vcard_attribute_get_name ()

    const char* 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 list of values from `attr`. The list and its contents are owned by `attr`, and must not be freed.

`attr` : | an EVCardAttribute
Returns : | A list of string values.

### e_vcard_attribute_get_values_decoded ()

    GList*      e_vcard_attribute_get_values_decoded
                                                (EVCardAttribute *attr);

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

`attr` : | an EVCardAttribute
Returns : | A list of values of type GString.

### e_vcard_attribute_get_params ()

    GList*      e_vcard_attribute_get_params    (EVCardAttribute *attr);

Gets the list of parameters 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.

### e_vcard_attribute_get_value ()

    char*       e_vcard_attribute_get_value     (EVCardAttribute *attr);

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

`attr` : | an EVCardAttribute
Returns : | A newly allocated string representing the value.

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

Note: this function seems currently to be unused. Could be removed.

`attr` : | an EVCardAttribute
Returns : | A newly allocated GString representing the value.

### e_vcard_attribute_has_type ()

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

Checks if `attr` has an EVCardAttributeParam of the specified type.

`attr` : | an EVCardAttribute
`typestr` : | a string representing the type
Returns : | `TRUE` if such a parameter exists, `FALSE` otherwise.

### 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_escape_string ()

    char*       e_vcard_escape_string           (const char *s);

Escapes a string according to RFC2426, section 5.

`s` : | the string to escape
Returns : | A newly allocated, escaped string.

### e_vcard_unescape_string ()

    char*       e_vcard_unescape_string         (const char *s);

Unescapes a string according to RFC2426, section 5.

`s` : | the string to unescape
Returns : | A newly allocated, unescaped string.

### EVC_ADR

    #define EVC_ADR             "ADR"

### EVC_BDAY

    #define EVC_BDAY            "BDAY"

Birthday

### EVC_CALURI

    #define EVC_CALURI          "CALURI"

Calendar URL

### EVC_CATEGORIES

    #define EVC_CATEGORIES      "CATEGORIES"

Categories

### EVC_EMAIL

    #define EVC_EMAIL           "EMAIL"

Email address

### EVC_ENCODING

    #define EVC_ENCODING        "ENCODING"

### EVC_FBURL

    #define EVC_FBURL           "FBURL"

### EVC_FN

    #define EVC_FN              "FN"

### EVC_ICSCALENDAR

    #define EVC_ICSCALENDAR     "ICSCALENDAR" /* XXX should this be X-EVOLUTION-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"

Nickname

### EVC_N

    #define EVC_N               "N"

### EVC_NOTE

    #define EVC_NOTE            "NOTE"

### EVC_ORG

    #define EVC_ORG             "ORG"

Organisation

### EVC_PHOTO

    #define EVC_PHOTO           "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"

Role

### EVC_TEL

    #define EVC_TEL             "TEL"

Telephone

### EVC_TITLE

    #define EVC_TITLE           "TITLE"

Title

### EVC_TYPE

    #define EVC_TYPE            "TYPE"

### EVC_UID

    #define EVC_UID             "UID"

Unique ID

### EVC_URL

    #define EVC_URL             "URL"

Home page URL

### EVC_VALUE

    #define EVC_VALUE           "VALUE"

### EVC_VERSION

    #define EVC_VERSION         "VERSION"

### EVC_X_AIM

    #define EVC_X_AIM              "X-AIM"

AIM ID

### EVC_X_ANNIVERSARY

    #define EVC_X_ANNIVERSARY      "X-EVOLUTION-ANNIVERSARY"

Wedding anniversary

### EVC_X_ASSISTANT

    #define EVC_X_ASSISTANT        "X-EVOLUTION-ASSISTANT"

Assistant

### EVC_X_BIRTHDAY

    #define EVC_X_BIRTHDAY         "X-EVOLUTION-BIRTHDAY"

Birthday

### EVC_X_BLOG_URL

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

Blog URL

### EVC_X_FILE_AS

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

File As

### EVC_X_ICQ

    #define EVC_X_ICQ              "X-ICQ"

ICQ number

### EVC_X_JABBER

    #define EVC_X_JABBER           "X-JABBER"

Jabber ID

### 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_MANAGER

    #define EVC_X_MANAGER       	"X-EVOLUTION-MANAGER"

Mananger

### EVC_X_MSN

    #define EVC_X_MSN           	"X-MSN"

MSN ID

### EVC_X_SPOUSE

    #define EVC_X_SPOUSE        	"X-EVOLUTION-SPOUSE"

Spouse

### EVC_X_WANTS_HTML

    #define EVC_X_WANTS_HTML    	"X-MOZILLA-HTML"

Wants HTML mail

### EVC_X_YAHOO

    #define EVC_X_YAHOO         	"X-YAHOO"

Yahoo ID

### EVC_X_BOOK_URI

    #define EVC_X_BOOK_URI     	"X-EVOLUTION-BOOK-URI"

### 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

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

### 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_NAME

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

### EVC_X_DEST_SOURCE_UID

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

### EVC_X_GROUPWISE

    #define EVC_X_GROUPWISE     	"X-GROUPWISE"

### EVC_X_RADIO

    #define EVC_X_RADIO         	"X-EVOLUTION-RADIO"

### 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"

## See Also

e-contact