InternetAddress

## InternetAddress InternetAddress — Internet addresses |

## Synopsis

    enum                InternetAddressType;
                        InternetAddressList;
                        InternetAddress;
    InternetAddress*    internet_address_new                (void);
    InternetAddress*    internet_address_new_name           (const char *name,
                                                             const char *addr);
    InternetAddress*    internet_address_new_group          (const char *name);
    void                internet_address_ref                (InternetAddress *ia);
    void                internet_address_unref              (InternetAddress *ia);
    InternetAddressType internet_address_get_type           (InternetAddress *ia);
    const char*         internet_address_get_name           (InternetAddress *ia);
    void                internet_address_set_name           (InternetAddress *ia,
                                                             const char *name);
    const char*         internet_address_get_addr           (InternetAddress *ia);
    void                internet_address_set_addr           (InternetAddress *ia,
                                                             const char *addr);
    void                internet_address_set_group          (InternetAddress *ia,
                                                             InternetAddressList *group);
    void                internet_address_add_member         (InternetAddress *ia,
                                                             InternetAddress *member);
    const InternetAddressList* internet_address_get_members (InternetAddress *ia);
    InternetAddressList* internet_address_list_prepend      (InternetAddressList *list,
                                                             InternetAddress *ia);
    InternetAddressList* internet_address_list_append       (InternetAddressList *list,
                                                             InternetAddress *ia);
    InternetAddressList* internet_address_list_concat       (InternetAddressList *a,
                                                             InternetAddressList *b);
    int                 internet_address_list_length        (const InternetAddressList *list);
    void                internet_address_list_destroy       (InternetAddressList *list);
    InternetAddressList* internet_address_list_next         (const InternetAddressList *list);
    InternetAddress*    internet_address_list_get_address   (const InternetAddressList *list);
    InternetAddressList* internet_address_parse_string      (const char *string);
    char*               internet_address_to_string          (const InternetAddress *ia,
                                                             gboolean encode);
    char*               internet_address_list_to_string     (const InternetAddressList *list,
                                                             gboolean encode);
    void                internet_address_list_writer        (const InternetAddressList *list,
                                                             GString *str);

## Description

An InternetAddress represents what is commonly referred to as an E-Mail address.

## Details

### enum InternetAddressType

    typedef enum {
    	INTERNET_ADDRESS_NONE,
    	INTERNET_ADDRESS_NAME,
    	INTERNET_ADDRESS_GROUP
    } InternetAddressType;

The type of InternetAddress.

`INTERNET_ADDRESS_NONE` | No type.
`INTERNET_ADDRESS_NAME` | A typical internet address type.
`INTERNET_ADDRESS_GROUP` | An rfc822 group type address.

### InternetAddressList

    typedef struct {
    	struct _InternetAddressList *next;
    	InternetAddress *address;
    } InternetAddressList;

A list of InternetAddress structures.

struct _InternetAddressList *`next`; | Pointer to the next item in the list.
InternetAddress *`address`; | The InternetAddress.

### InternetAddress

    typedef struct {
    	InternetAddressType type;
    	unsigned int refcount;
    	char *name;
    	union {
    		char *addr;
    		InternetAddressList *members;
    	} value;
    } InternetAddress;

A structure representing an rfc822 address.

InternetAddressType `type`; | The type of internet address.
unsigned int `refcount`; | The reference count.
char *`name`; | The name component of the internet address.

### internet_address_new ()

    InternetAddress*    internet_address_new                (void);

Creates a new InternetAddress object

Returns : | a new InternetAddress object.

### internet_address_new_name ()

    InternetAddress*    internet_address_new_name           (const char *name,
                                                             const char *addr);

Creates a new InternetAddress object with name `name` and address `addr`.

`name` : | person's name
`addr` : | person's address
Returns : | a new InternetAddress object.

### internet_address_new_group ()

    InternetAddress*    internet_address_new_group          (const char *name);

Creates a new InternetAddress object with group name `name`.

`name` : | group name
Returns : | a new InternetAddress object.

### internet_address_ref ()

    void                internet_address_ref                (InternetAddress *ia);

Ref's the internet address.

`ia` : | internet address

### internet_address_unref ()

    void                internet_address_unref              (InternetAddress *ia);

Unref's the internet address.

`ia` : | internet address

### internet_address_get_type ()

    InternetAddressType internet_address_get_type           (InternetAddress *ia);

Gets the type of the internet address, which will either be INTERNET_ADDRESS_NAME or INTERNET_ADDRESS_GROUP.

`ia` : | internet address
Returns : | the type of `ia`.

### internet_address_get_name ()

    const char*         internet_address_get_name           (InternetAddress *ia);

Gets the name component of the internet address. If the internet address is a group, it will get the group name.

`ia` : | internet address
Returns : | the name of `ia`.

### internet_address_set_name ()

    void                internet_address_set_name           (InternetAddress *ia,
                                                             const char *name);

Set the name of the internet address.

`ia` : | internet address
`name` : | group or contact's name

### internet_address_get_addr ()

    const char*         internet_address_get_addr           (InternetAddress *ia);

Gets the addr-spec of the internet address.

`ia` : | internet address
Returns : | the address of `ia`.

### internet_address_set_addr ()

    void                internet_address_set_addr           (InternetAddress *ia,
                                                             const char *addr);

Set the internet address's address.

`ia` : | internet address
`addr` : | contact's email address

### internet_address_set_group ()

    void                internet_address_set_group          (InternetAddress *ia,
                                                             InternetAddressList *group);

Set the members of the internet address group.

`ia` : | internet address
`group` : | a list of internet addresses

### internet_address_add_member ()

    void                internet_address_add_member         (InternetAddress *ia,
                                                             InternetAddress *member);

Add a contact to the internet address group.

`ia` : | internet address
`member` : | group member's internet address

### internet_address_get_members ()

    const InternetAddressList* internet_address_get_members (InternetAddress *ia);

Gets the InternetAddressList containing the group members of an rfc822 group address.

`ia` : | internet address
Returns : | the members of `ia`.

### internet_address_list_prepend ()

    InternetAddressList* internet_address_list_prepend      (InternetAddressList *list,
                                                             InternetAddress *ia);

Prepends the internet address `ia` to the list of internet addresses pointed to by `list`.

`list` : | a list of internet addresses
`ia` : | internet address to prepend
Returns : | the resultant list.

### internet_address_list_append ()

    InternetAddressList* internet_address_list_append       (InternetAddressList *list,
                                                             InternetAddress *ia);

Appends the internet address to the list of internet addresses pointed to by `list`.

`list` : | a list of internet addresses
`ia` : | internet address to append
Returns : | the resultant list.

### internet_address_list_concat ()

    InternetAddressList* internet_address_list_concat       (InternetAddressList *a,
                                                             InternetAddressList *b);

Concatenates a copy of list `b` onto the end of list `a`.

`a` : | first list
`b` : | second list
Returns : | the resulting list.

### internet_address_list_length ()

    int                 internet_address_list_length        (const InternetAddressList *list);

Calculates the length of the list of addresses.

`list` : | list of internet addresses
Returns : | the number of internet addresses in `list`.

### internet_address_list_destroy ()

    void                internet_address_list_destroy       (InternetAddressList *list);

Destroys the list of internet addresses.

`list` : | address list

### internet_address_list_next ()

    InternetAddressList* internet_address_list_next         (const InternetAddressList *list);

Advances to the next address node in the InternetAddessList.

`list` : | list of internet addresses
Returns : | the next address node in the InternetAddessList.

### internet_address_list_get_address ()

    InternetAddress*    internet_address_list_get_address   (const InternetAddressList *list);

Gets the InternetAddress currently pointed to in `list`.

`list` : | list of internet addresses
Returns : | the InternetAddress currently pointed to in `list`.

### internet_address_parse_string ()

    InternetAddressList* internet_address_parse_string      (const char *string);

Construct a list of internet addresses from the given string.

`string` : | a string containing internet addresses
Returns : | a linked list of internet addresses. *Must* be free'd by the caller.

### internet_address_to_string ()

    char*               internet_address_to_string          (const InternetAddress *ia,
                                                             gboolean encode);

Allocates a string containing the contents of the InternetAddress object.

`ia` : | Internet Address object
`encode` : | TRUE if the address should be rfc2047 encoded
Returns : | the InternetAddress object as an allocated string in rfc822 format.

### internet_address_list_to_string ()

    char*               internet_address_list_to_string     (const InternetAddressList *list,
                                                             gboolean encode);

Allocates a string buffer containing the rfc822 formatted addresses in `list`.

`list` : | list of internet addresses
`encode` : | `TRUE` if the address should be rfc2047 encoded
Returns : | a string containing the list of addresses in rfc822 format.

### internet_address_list_writer ()

    void                internet_address_list_writer        (const InternetAddressList *list,
                                                             GString *str);

Writes the rfc2047-encoded rfc822 formatted addresses in `list` to `string`, folding appropriately.

`list` : | list of internet addresses
`str` : | string to write to