EDestination

## EDestination EDestination |

## Synopsis

    struct              EDestination;
    EDestination *      e_destination_new                   (void);
    EDestination *      e_destination_copy                  (const EDestination *dest);
    gboolean            e_destination_empty                 (const EDestination *dest);
    gboolean            e_destination_equal                 (const EDestination *a,
                                                             const EDestination *b);
    void                e_destination_set_contact           (EDestination *dest,
                                                             EContact *contact,
                                                             gint email_num);
    void                e_destination_set_contact_uid       (EDestination *dest,
                                                             const gchar *uid,
                                                             gint email_num);
    void                e_destination_set_client            (EDestination *dest,
                                                             EBookClient *client);
    EContact *          e_destination_get_contact           (const EDestination *dest);
    const gchar *       e_destination_get_source_uid        (const EDestination *dest);
    const gchar *       e_destination_get_contact_uid       (const EDestination *dest);
    gint                e_destination_get_email_num         (const EDestination *dest);
    void                e_destination_set_name              (EDestination *dest,
                                                             const gchar *name);
    void                e_destination_set_email             (EDestination *dest,
                                                             const gchar *email);
    const gchar *       e_destination_get_name              (const EDestination *dest);
    const gchar *       e_destination_get_email             (const EDestination *dest);
    const gchar *       e_destination_get_address           (const EDestination *dest);
    gboolean            e_destination_is_evolution_list     (const EDestination *dest);
    gboolean            e_destination_list_show_addresses   (const EDestination *dest);
    const GList *       e_destination_list_get_dests        (const EDestination *dest);
    const GList *       e_destination_list_get_root_dests   (const EDestination *dest);
    gboolean            e_destination_is_ignored            (const EDestination *dest);
    void                e_destination_set_ignored           (EDestination *dest,
                                                             gboolean ignored);
    void                e_destination_set_html_mail_pref    (EDestination *dest,
                                                             gboolean flag);
    gboolean            e_destination_get_html_mail_pref    (const EDestination *dest);
    gboolean            e_destination_is_auto_recipient     (const EDestination *dest);
    void                e_destination_set_auto_recipient    (EDestination *dest,
                                                             gboolean value);
    void                e_destination_set_raw               (EDestination *dest,
                                                             const gchar *raw);
    const gchar *       e_destination_get_textrep           (const EDestination *dest,
                                                             gboolean include_email);
    gchar *             e_destination_get_textrepv          (EDestination **destv);
    gchar *             e_destination_export                (const EDestination *dest);
    gchar *             e_destination_exportv               (EDestination **destv);
    EDestination *      e_destination_import                (const gchar *str);
    EDestination **     e_destination_importv               (const gchar *str);
    void                e_destination_export_to_vcard_attribute
                                                            (EDestination *dest,
                                                             EVCardAttribute *attr);
    void                e_destination_freev                 (EDestination **destv);

    void                e_destination_set_book              (EDestination *dest,
                                                             EBook *book);

## Object Hierarchy

      GObject
       +----EDestination

## Signals

      "changed"                                        : Run Last

## Description

## Details

### struct EDestination

    struct EDestination;

### e_destination_new ()

    EDestination *      e_destination_new                   (void);

Creates a new EDestination with blank values.

Returns : | A newly created EDestination.

### e_destination_copy ()

    EDestination *      e_destination_copy                  (const EDestination *dest);

Creates a new EDestination identical to `dest`.

`dest` : | an EDestination
Returns : | A newly created EDestination, identical to `dest`. [transfer full]

### e_destination_empty ()

    gboolean            e_destination_empty                 (const EDestination *dest);

Checks if `dest` is blank.

`dest` : | an EDestination
Returns : | `TRUE` if `dest` is empty, `FALSE` otherwise.

### e_destination_equal ()

    gboolean            e_destination_equal                 (const EDestination *a,
                                                             const EDestination *b);

Checks if `a` and `b` are equal.

`a` : | an EDestination
`b` : | an EDestination
Returns : | `TRUE` if the destinations are equal, `FALSE` otherwise.

### e_destination_set_contact ()

    void                e_destination_set_contact           (EDestination *dest,
                                                             EContact *contact,
                                                             gint email_num);

Sets `dest` to point to one of `contact`'s e-mail addresses indicated by `email_num`.

`dest` : | an EDestination
`contact` : | an EContact
`email_num` : | an email index

### e_destination_set_contact_uid ()

    void                e_destination_set_contact_uid       (EDestination *dest,
                                                             const gchar *uid,
                                                             gint email_num);

Sets `dest` to point to one of the contact specified by `uid`'s e-mail addresses indicated by `email_num`.

`dest` : | an EDestination
`uid` : | a unique contact ID
`email_num` : | an email index

### e_destination_set_client ()

    void                e_destination_set_client            (EDestination *dest,
                                                             EBookClient *client);

Specify the source `dest`'s contact comes from. This is useful if you need to update the contact later.

`dest` : | an EDestination
`client` : | an EBookClient

Since 3.2

### e_destination_get_contact ()

    EContact *          e_destination_get_contact           (const EDestination *dest);

Gets the contact `dest` is pointing to, if any.

`dest` : | an EDestination
Returns : | An EContact, or `NULL` if none was set. [transfer none]

### e_destination_get_source_uid ()

    const gchar *       e_destination_get_source_uid        (const EDestination *dest);

Gets the unique source ID `dest` is pointing to, if any. The source ID specifies which address book `dest`'s contact came from.

`dest` : | an EDestination
Returns : | A unique source ID, or `NULL` if none was set.

### e_destination_get_contact_uid ()

    const gchar *       e_destination_get_contact_uid       (const EDestination *dest);

Gets the unique contact ID `dest` is pointing to, if any.

`dest` : | an EDestination
Returns : | A unique contact ID, or `NULL` if none was set.

### e_destination_get_email_num ()

    gint                e_destination_get_email_num         (const EDestination *dest);

Gets the index of the e-mail address of the contact that `dest` is pointing to, if any.

`dest` : | an EDestination
Returns : | The e-mail index, or -1 if none was set.

### e_destination_set_name ()

    void                e_destination_set_name              (EDestination *dest,
                                                             const gchar *name);

Sets the full name of `dest`'s addressee.

`dest` : | an EDestination
`name` : | the destination's full name

### e_destination_set_email ()

    void                e_destination_set_email             (EDestination *dest,
                                                             const gchar *email);

Sets the e-mail address of `dest`'s addressee.

`dest` : | an EDestination
`email` : | the destination's e-mail address

### e_destination_get_name ()

    const gchar *       e_destination_get_name              (const EDestination *dest);

Gets the full name of `dest`'s addressee, or if the addressee is a contact list, the name the list was filed under.

`dest` : | an EDestination
Returns : | The full name of the addressee, or `NULL` if none was set.

### e_destination_get_email ()

    const gchar *       e_destination_get_email             (const EDestination *dest);

Gets the e-mail address of `dest`'s addressee.

`dest` : | an EDestination
Returns : | An e-mail address, or an empty string if none was set.

### e_destination_get_address ()

    const gchar *       e_destination_get_address           (const EDestination *dest);

Gets the encoded name and email address, or in the case of lists, the encoded list of email addresses, from `dest`. The returned string is suitable for use in an email header, but not for displaying to users.

`dest` : | an EDestination
Returns : | an encoded destination string suitable for use in an email header, or `NULL` if the destination was empty

### e_destination_is_evolution_list ()

    gboolean            e_destination_is_evolution_list     (const EDestination *dest);

Checks if `dest` is a list of addresses.

`dest` : | an EDestination
Returns : | `TRUE` if destination is a list, `FALSE` if it is an individual.

### e_destination_list_show_addresses ()

    gboolean            e_destination_list_show_addresses   (const EDestination *dest);

If `dest` is a list, checks if the addresses in the list should be presented to the user during interaction.

`dest` : | an EDestination
Returns : | `TRUE` if addresses should be shown, `FALSE` otherwise.

### e_destination_list_get_dests ()

    const GList *       e_destination_list_get_dests        (const EDestination *dest);

If `dest` is a list, gets recursively list of all destinations. Everything returned from this function belongs to `dest` and thus should not be freed.

`dest` : | an EDestination
Returns : | A list of elements of type EDestination, or `NULL`. [element-type EDestination][transfer none]

Since 3.2

### e_destination_list_get_root_dests ()

    const GList *       e_destination_list_get_root_dests   (const EDestination *dest);

If `dest` is a list, gets the list of EDestinations assigned directly to `dest`. The list and its elements belong to `dest`, and should not be freed.

`dest` : | an EDestination
Returns : | A list of elements of type EDestination, or `NULL`. [element-type EDestination][transfer none]

Since 3.2

### e_destination_is_ignored ()

    gboolean            e_destination_is_ignored            (const EDestination *dest);

Check if `dest` is to be ignored.

`dest` : | an EDestination
Returns : | `TRUE` if this destination should be ignored, else `FALSE`.

### e_destination_set_ignored ()

    void                e_destination_set_ignored           (EDestination *dest,
                                                             gboolean ignored);

Set the ignore flag on a EDestination.

`dest` : | an EDestination
`ignored` : | `TRUE` if this EDestination should be ignored.

### e_destination_set_html_mail_pref ()

    void                e_destination_set_html_mail_pref    (EDestination *dest,
                                                             gboolean flag);

Specifies whether `dest` wants to get mail formatted as HTML.

`dest` : | an EDestination
`flag` : | whether the destination wants HTML mail

### e_destination_get_html_mail_pref ()

    gboolean            e_destination_get_html_mail_pref    (const EDestination *dest);

Check if `dest` wants to get mail formatted as HTML.

`dest` : | an EDestination
Returns : | `TRUE` if destination wants HTML, `FALSE` if not.

### e_destination_is_auto_recipient ()

    gboolean            e_destination_is_auto_recipient     (const EDestination *dest);

Checks if `dest` is flagged as an automatic recipient, meaning it was not explicitly specified by the user. This can be used to hide it from some UI elements.

`dest` : | an EDestination
Returns : | `TRUE` if destination is an auto recipient, `FALSE` otherwise.

### e_destination_set_auto_recipient ()

    void                e_destination_set_auto_recipient    (EDestination *dest,
                                                             gboolean value);

Sets the flag indicating if `dest` is an automatic recipient, meaning it was not explicitly specified by the user. This can be used to hide it from some UI elements.

`dest` : | an EDestination
`value` : | the auto recipient flag

### e_destination_set_raw ()

    void                e_destination_set_raw               (EDestination *dest,
                                                             const gchar *raw);

Sets `dest` to point to the name and e-mail address resulting from parsing the supplied string. Useful for user input.

`dest` : | an EDestination
`raw` : | an unparsed string

### e_destination_get_textrep ()

    const gchar *       e_destination_get_textrep           (const EDestination *dest,
                                                             gboolean include_email);

Generates a textual representation of `dest`, suitable for referring to the destination during user interaction.

`dest` : | an EDestination
`include_email` : | whether to include the e-mail address
Returns : | A textual representation of the destination.

### e_destination_get_textrepv ()

    gchar *             e_destination_get_textrepv          (EDestination **destv);

Generates a joint text representation of all the EDestination elements in `destv`.

`destv` : | `NULL`-terminated array of pointers to EDestination
Returns : | The text representation of `destv`.

### e_destination_export ()

    gchar *             e_destination_export                (const EDestination *dest);

Exports a destination to an XML document.

`dest` : | an EDestination
Returns : | An XML string, allocated with g_malloc.

### e_destination_exportv ()

    gchar *             e_destination_exportv               (EDestination **destv);

Exports multiple EDestination elements to a single XML document.

`destv` : | a `NULL`-terminated array of pointers to EDestination
Returns : | An XML string, allocated with g_malloc.

### e_destination_import ()

    EDestination *      e_destination_import                (const gchar *str);

Creates an EDestination from an XML document.

`str` : | an XML string
Returns : | An EDestination, or `NULL` if the document was not well-formed. [transfer full]

### e_destination_importv ()

    EDestination **     e_destination_importv               (const gchar *str);

Creates an array of pointers to EDestination elements from an XML document.

`str` : | an XML string
Returns : | A `NULL`-terminated array of pointers to EDestination elements. [transfer full]

### e_destination_export_to_vcard_attribute ()

    void                e_destination_export_to_vcard_attribute
                                                            (EDestination *dest,
                                                             EVCardAttribute *attr);

Exports the contact information from `dest` to parameters and values in `attr`, suitable for an address book.

`dest` : | an EDestination
`attr` : | an EVCardAttribute

### e_destination_freev ()

    void                e_destination_freev                 (EDestination **destv);

Unrefs the elements of `destv` and frees `destv` itself.

`destv` : | a `NULL`-terminated array of pointers to EDestination

### e_destination_set_book ()

    void                e_destination_set_book              (EDestination *dest,
                                                             EBook *book);

### Warning

`e_destination_set_book` has been deprecated since version 3.2 and should not be used in newly-written code. Use `e_destination_set_client()` instead.

Specify the source `dest`'s contact comes from. This is useful if you need to update the contact later.

`dest` : | an EDestination
`book` : | an EBook

## Signal Details

### The `"changed"` signal

    void                user_function                      (EDestination *edestination,
                                                            gpointer      user_data)         : Run Last