## EDestination

EDestination —

## Synopsis

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

## Object Hierarchy

      GObject
       +----EDestination

## Signals

    "changed"   void        user_function      (EDestination *edestination,
                                                gpointer      user_data)         : Run last

## Description

## Details

### EDestination

    typedef struct _EDestination 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`.

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

    char*       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_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_exportv ()

    char*       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_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_get_address ()

    const char* e_destination_get_address       (const EDestination *dest);

Gets the formatted name and e-mail address, or in the case of lists, the formatted list of e-mail addresses, from `dest`.

`dest` : | an EDestination
Returns : | A formatted destination string, or `NULL` if the destination was empty.

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

### e_destination_get_contact_uid ()

    const char* 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 ()

    const char* 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_email_num ()

    int         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_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_get_name ()

    const char* 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_source_uid ()

    const char* 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_textrep ()

    const char* 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 ()

    char*       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_import ()

    EDestination* e_destination_import          (const char *str);

Creates an EDestination from an XML document.

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

### e_destination_importv ()

    EDestination** e_destination_importv        (const char *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.

### 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_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_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_list_get_dests ()

    const GList* e_destination_list_get_dests   (const EDestination *dest);

If `dest` is a list, gets the list of destinations. 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`.

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

    EDestination* e_destination_new             (void);

Creates a new EDestination with blank values.

Returns : | A newly created EDestination.

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

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

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

### e_destination_set_contact ()

    void        e_destination_set_contact       (EDestination *dest,
                                                 EContact *contact,
                                                 int 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 char *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_email ()

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

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

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

### 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_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_name ()

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

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

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

### e_destination_set_raw ()

    void        e_destination_set_raw           (EDestination *dest,
                                                 const char *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

## Signal Details

### The "changed" signal

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

`edestination` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.