Camel.Address

CamelAddress is a simple object used to wrap various address types in a common base abstract api.

It provides structured access to an indexed array/list of addresses.

An existing address can be copied using camel_address_new_clone, this will create a matching instance of the address and copy its content accross.

CamelAddress *camel_address_new_clone(const CamelAddress *addr);

There are some other utility functions for concatenating addresses, or copying the contents of addresses.

int camel_address_cat(CamelAddress *dest, const CamelAddress *source);
int camel_address_copy(CamelAddress *dest, const CamelAddress *source);

It is up to the implementing sub-classes to add accessor methods, but the base class provides a length accessor and a remove method. Addresses can be removed by index, or use -1 to remove all addresses.

int camel_address_length(CamelAddress *addr);
void camel_address_remove(CamelAddress *addr, int index);

There are two ways most addresses are used. Either for display purposes for the user, or in a raw internet form. In CamelAddress these are known as the formatted form or the encoded form respectively.

The formatted form is a UTF-8 string representation of the addresses contained in the object. The formatting is not guaranteed to be reversible, but an unformat function will try to reconstruct the original address list from the string.

int camel_address_unformat(CamelAddress *addr, const char *raw);
char *camel_address_format(CamelAddress *addr);

The encoded format depends on the address type. This represents the raw transmission version of the address, and the encoding process should be fully bi-directional.

int camel_address_decode(CamelAddress *addr, const char *raw);
char *camel_address_encode(CamelAddress *addr);

Camel.InternetAddress

This is an RFC822 address type. It could be called CamelRFC822Address, I guess. Each address consists of an optional 'real-name' part, together with a required 'addr-spec' part.

The encoded version of a CamelInternetAddress is encoded as per RFC822 and RFC2047, with one caveat. Address groups are not supported; they are flattened into the base address list by the decoding method. If you need more control, you could use the underlying Camel.MimeUtils functions for your parsing and formatting. Those functions will also be slightly more efficient, so you may prefer to use them if you are working with large amounts of data.

Creating an address is simple:

CamelInternetAddress *camel_internet_address_new(void);

You can add addresses to the end of the list, or retrieve addresses by index. The get method returns whether that index exists, so is a convenient way to write a loop without having to keep track of the count and length of the address. NULL is used to indicate no real-name part for an address. The name is supplied in UTF-8.

int camel_internet_address_add(CamelInternetAddress *addr, const char *name, const char *address);
gboolean camel_internet_address_get(const CamelInternetAddress *addr, int index, const char **namep, const char **addressp);

Addresses can be looked up by name or address. The corresponding address or name part can be retrieved, or the return value used to indicate the index of the match.

int camel_internet_address_find_name(CamelInternetAddress *addr, const char *name, const char **addressp);
int camel_internet_address_find_address(CamelInternetAddress *addr, const char *address, const char **namep);

And finally there are some class-static functions which can be used by other code to perform encoding or formatting functions of individual address parts.

char *camel_internet_address_encode_address(int *len, const char *name, const char *addr);
char *camel_internet_address_format_address(const char *real, const char *addr);

Internal Note

Internally, each address is stored in a split, decoded format, which is then stored in a GPtrArray.

The actual decoding and encoding of raw addresses is performed by the Camel.MimeUtils address functions.

Example: Creating a mail address header

This example shows how an address can be built up, and then converted into a raw header for mail creation.

        CamelInternetAddress *cia;
        char *enc;
 
        cia = camel_internet_address_new();
        camel_internet_address_add(cia, "Not Zed", "notzed@somecompany.com"); 
        camel_internet_address_add(cia, "Not Him", "nothim@some.othercompany.com");
        enc = camel_address_encode((CamelAddress *)cia);
        camel_medium_add_header(medium, "X-List-CC", enc);
        g_free(enc);
        camel_object_unref(cia);

Note that you would always use the normal address interfaces in a Camel.DataWrapper#Camel.MimeMessage for adding the standard headers, but this could be used to add custom headers.

Example: Parse a mail address header

This example whos how you could reverse the process in the previous example.

        CamelInternetAddress *cia;
        const char *name, *addr;
        int i;
 
        cia = camel_internet_address_new();
        camel_address_decode(cia, enc);
        printf("Addresses:\n");
        for (i=0;camel_internet_address_get(cia, i, &name, &addr);i++) {
                printf("addr=%s", addr);
                if (name)
                        printf(" name=%s\n", name);
                else
                        printf("\n");
        }
        camel_object_unref(cia);

It also shows how the accessor method can be used in loops, and how to convert a single raw address

Camel.NNTPAddress

CamelNNTPAddress is used for storing/parsing/formatting lists of newsgroup names. These are just ASCII based, so no encoding is required.

As such, the interface is a bit simpler:

 CamelNNTPAddress *camel_nntp_address_new(void);
 int camel_nntp_address_add(CamelNNTPAddress *, const char *);
 gboolean camel_nntp_address_get(const CamelNNTPAddress *, int, const char **);