## GMimeHeader GMimeHeader — Message and MIME part headers |

## Synopsis

    struct              GMimeHeaderIter;
                        GMimeHeaderList;
    ssize_t             (*GMimeHeaderWriter)                (GMimeStream *stream,
                                                             const char *name,
                                                             const char *value);
    void                (*GMimeHeaderForeachFunc)           (const char *name,
                                                             const char *value,
                                                             gpointer user_data);
    GMimeHeaderIter *   g_mime_header_iter_new              (void);
    void                g_mime_header_iter_free             (GMimeHeaderIter *iter);
    GMimeHeaderIter *   g_mime_header_iter_copy             (GMimeHeaderIter *iter);
    void                g_mime_header_iter_copy_to          (GMimeHeaderIter *src,
                                                             GMimeHeaderIter *dest);
    gboolean            g_mime_header_iter_equal            (GMimeHeaderIter *iter1,
                                                             GMimeHeaderIter *iter2);
    gboolean            g_mime_header_iter_first            (GMimeHeaderIter *iter);
    gboolean            g_mime_header_iter_last             (GMimeHeaderIter *iter);
    gboolean            g_mime_header_iter_next             (GMimeHeaderIter *iter);
    gboolean            g_mime_header_iter_prev             (GMimeHeaderIter *iter);
    gboolean            g_mime_header_iter_is_valid         (GMimeHeaderIter *iter);
    const char *        g_mime_header_iter_get_name         (GMimeHeaderIter *iter);
    const char *        g_mime_header_iter_get_value        (GMimeHeaderIter *iter);
    gboolean            g_mime_header_iter_set_value        (GMimeHeaderIter *iter,
                                                             const char *value);
    gboolean            g_mime_header_iter_remove           (GMimeHeaderIter *iter);
    GMimeHeaderList *   g_mime_header_list_new              (void);
    void                g_mime_header_list_destroy          (GMimeHeaderList *headers);
    void                g_mime_header_list_clear            (GMimeHeaderList *headers);
    gboolean            g_mime_header_list_contains         (const GMimeHeaderList *headers,
                                                             const char *name);
    void                g_mime_header_list_prepend          (GMimeHeaderList *headers,
                                                             const char *name,
                                                             const char *value);
    void                g_mime_header_list_append           (GMimeHeaderList *headers,
                                                             const char *name,
                                                             const char *value);
    gboolean            g_mime_header_list_remove           (GMimeHeaderList *headers,
                                                             const char *name);
    void                g_mime_header_list_set              (GMimeHeaderList *headers,
                                                             const char *name,
                                                             const char *value);
    const char *        g_mime_header_list_get              (const GMimeHeaderList *headers,
                                                             const char *name);
    gboolean            g_mime_header_list_get_iter         (GMimeHeaderList *headers,
                                                             GMimeHeaderIter *iter);
    void                g_mime_header_list_foreach          (const GMimeHeaderList *headers,
                                                             GMimeHeaderForeachFunc func,
                                                             gpointer user_data);
    void                g_mime_header_list_register_writer  (GMimeHeaderList *headers,
                                                             const char *name,
                                                             GMimeHeaderWriter writer);
    ssize_t             g_mime_header_list_write_to_stream  (const GMimeHeaderList *headers,
                                                             GMimeStream *stream);
    char *              g_mime_header_list_to_string        (const GMimeHeaderList *headers);
    GMimeStream *       g_mime_header_list_get_stream       (GMimeHeaderList *headers);
    void                g_mime_header_list_set_stream       (GMimeHeaderList *headers,
                                                             GMimeStream *stream);

## Description

A GMimeHeader is a collection of rfc822 header fields and their values.

## Details

### struct GMimeHeaderIter

    struct GMimeHeaderIter {
    	GMimeHeaderList *hdrlist;
    	GMimeHeader *cursor;
    	guint32 version;
    };

A message or mime-part header iterator. All members should be considered private.

GMimeHeaderList *`hdrlist`; | a GMimeHeaderList
GMimeHeader *`cursor`; | a GMimeHeader
guint32 `version`; | the version of `hdrlist` when initialized

### GMimeHeaderList

    typedef struct _GMimeHeaderList GMimeHeaderList;

A message or mime-part header.

### GMimeHeaderWriter ()

    ssize_t             (*GMimeHeaderWriter)                (GMimeStream *stream,
                                                             const char *name,
                                                             const char *value);

Function signature for the callback to `g_mime_header_list_register_writer()`.

`stream` : | The output stream.
`name` : | The field name.
`value` : | The field value.
Returns : | the number of bytes written or `-1` on error.

### GMimeHeaderForeachFunc ()

    void                (*GMimeHeaderForeachFunc)           (const char *name,
                                                             const char *value,
                                                             gpointer user_data);

Function signature for the callback to `g_mime_header_list_foreach()`.

`name` : | The field name.
`value` : | The field value.
`user_data` : | The user-supplied callback data.

### g_mime_header_iter_new ()

    GMimeHeaderIter *   g_mime_header_iter_new              (void);

Dynamically allocates a GMimeHeaderIter on the heap. This is intended for use in language bindings but may also be useful in applications as well. You must free this iter with `g_mime_header_iter_free()`.

Returns : | a newly-allocated GMimeHeaderIter.

### g_mime_header_iter_free ()

    void                g_mime_header_iter_free             (GMimeHeaderIter *iter);

Frees a dynamically-allocated GMimeHeaderIter as created by `g_mime_header_iter_new()` or `g_mime_header_iter_copy()`.

`iter` : | a GMimeHeaderIter

### g_mime_header_iter_copy ()

    GMimeHeaderIter *   g_mime_header_iter_copy             (GMimeHeaderIter *iter);

Creates a dynamically allocated header iterator as a copy of `iter`. You must free this iter with `g_mime_header_iter_free()`.

`iter` : | a GMimeHeaderIter
Returns : | a newly-allocated copy of `iter`.

### g_mime_header_iter_copy_to ()

    void                g_mime_header_iter_copy_to          (GMimeHeaderIter *src,
                                                             GMimeHeaderIter *dest);

Copies `src` to `dest`.

`src` : | a GMimeHeaderIter
`dest` : | a GMimeHeaderIter

### g_mime_header_iter_equal ()

    gboolean            g_mime_header_iter_equal            (GMimeHeaderIter *iter1,
                                                             GMimeHeaderIter *iter2);

Check that `iter1` and `iter2` reference the same header.

`iter1` : | a GMimeHeaderIter
`iter2` : | a GMimeHeaderIter
Returns : | `TRUE` if `iter1` and `iter2` refer to the same header or `FALSE` otherwise.

### g_mime_header_iter_first ()

    gboolean            g_mime_header_iter_first            (GMimeHeaderIter *iter);

Updates `iter` to point to the first header.

`iter` : | a GMimeHeaderIter
Returns : | `TRUE` on success or `FALSE` otherwise.

### g_mime_header_iter_last ()

    gboolean            g_mime_header_iter_last             (GMimeHeaderIter *iter);

Updates `iter` to point to the last header.

`iter` : | a GMimeHeaderIter
Returns : | `TRUE` on success or `FALSE` otherwise.

### g_mime_header_iter_next ()

    gboolean            g_mime_header_iter_next             (GMimeHeaderIter *iter);

Advances to the next header.

`iter` : | a GMimeHeaderIter
Returns : | `TRUE` on success or `FALSE` otherwise.

### g_mime_header_iter_prev ()

    gboolean            g_mime_header_iter_prev             (GMimeHeaderIter *iter);

Advances to the previous header.

`iter` : | a GMimeHeaderIter
Returns : | `TRUE` on success or `FALSE` otherwise.

### g_mime_header_iter_is_valid ()

    gboolean            g_mime_header_iter_is_valid         (GMimeHeaderIter *iter);

Checks if a GMimeHeaderIter is valid. An iterator may become invalid if the GMimeHeaderList that the iterator refers to changes.

`iter` : | a GMimeHeaderIter
Returns : | `TRUE` if `iter` is still valid or `FALSE` otherwise.

### g_mime_header_iter_get_name ()

    const char *        g_mime_header_iter_get_name         (GMimeHeaderIter *iter);

Gets the current header's name.

`iter` : | a GMimeHeaderIter
Returns : | the header name or `NULL` if invalid.

### g_mime_header_iter_get_value ()

    const char *        g_mime_header_iter_get_value        (GMimeHeaderIter *iter);

Gets the current header's value.

`iter` : | a GMimeHeaderIter
Returns : | the header's raw, unprocessed value or `NULL` if invalid. Note: The returned value should be decoded with a function such as `g_mime_utils_header_decode_text()` before displaying to the user.

### g_mime_header_iter_set_value ()

    gboolean            g_mime_header_iter_set_value        (GMimeHeaderIter *iter,
                                                             const char *value);

Sets the current header's value to the new value.

`iter` : | a GMimeHeaderIter
`value` : | new header value
Returns : | `TRUE` if the value was set or `FALSE` otherwise (indicates invalid iter). Note: `value` should be encoded with a function such as `g_mime_utils_header_encode_text()`.

### g_mime_header_iter_remove ()

    gboolean            g_mime_header_iter_remove           (GMimeHeaderIter *iter);

Removes the current header and advances to the next header.

Note: If you remove the last header in the list, then `iter` will become invalid regardless of whether or not other headers remain.

`iter` : | a GMimeHeaderIter
Returns : | `TRUE` on success or `FALSE` otherwise.

### g_mime_header_list_new ()

    GMimeHeaderList *   g_mime_header_list_new              (void);

Creates a new GMimeHeaderList object.

Returns : | a new header list object.

### g_mime_header_list_destroy ()

    void                g_mime_header_list_destroy          (GMimeHeaderList *headers);

Destroy the header list.

`headers` : | a GMimeHeaderList

### g_mime_header_list_clear ()

    void                g_mime_header_list_clear            (GMimeHeaderList *headers);

Removes all of the headers from the GMimeHeaderList.

`headers` : | a GMimeHeaderList

### g_mime_header_list_contains ()

    gboolean            g_mime_header_list_contains         (const GMimeHeaderList *headers,
                                                             const char *name);

Checks whether or not a header exists.

`headers` : | a GMimeHeaderList
`name` : | header name
Returns : | `TRUE` if the specified header exists or `FALSE` otherwise.

### g_mime_header_list_prepend ()

    void                g_mime_header_list_prepend          (GMimeHeaderList *headers,
                                                             const char *name,
                                                             const char *value);

Prepends a header. If `value` is `NULL`, a space will be set aside for it (useful for setting the order of headers before values can be obtained for them) otherwise the header will be unset.

Note: `value` should be encoded with a function such as `g_mime_utils_header_encode_text()`.

`headers` : | a GMimeHeaderList
`name` : | header name
`value` : | header value

### g_mime_header_list_append ()

    void                g_mime_header_list_append           (GMimeHeaderList *headers,
                                                             const char *name,
                                                             const char *value);

Appends a header. If `value` is `NULL`, a space will be set aside for it (useful for setting the order of headers before values can be obtained for them) otherwise the header will be unset.

Note: `value` should be encoded with a function such as `g_mime_utils_header_encode_text()`.

`headers` : | a GMimeHeaderList
`name` : | header name
`value` : | header value

### g_mime_header_list_remove ()

    gboolean            g_mime_header_list_remove           (GMimeHeaderList *headers,
                                                             const char *name);

Remove the specified header.

`headers` : | a GMimeHeaderList
`name` : | header name
Returns : | `TRUE` if the header was successfully removed or `FALSE` if the specified header could not be found.

### g_mime_header_list_set ()

    void                g_mime_header_list_set              (GMimeHeaderList *headers,
                                                             const char *name,
                                                             const char *value);

Set the value of the specified header. If `value` is `NULL` and the header, `name`, had not been previously set, a space will be set aside for it (useful for setting the order of headers before values can be obtained for them) otherwise the header will be unset.

Note: If there are multiple headers with the specified field name, the first instance of the header will be replaced and further instances will be removed.

Additionally, `value` should be encoded with a function such as `g_mime_utils_header_encode_text()`.

`headers` : | a GMimeHeaderList
`name` : | header name
`value` : | header value

### g_mime_header_list_get ()

    const char *        g_mime_header_list_get              (const GMimeHeaderList *headers,
                                                             const char *name);

Gets the value of the first header with the name requested.

`headers` : | a GMimeHeaderList
`name` : | header name
Returns : | the value of the header requested. Note: The returned value should be decoded with a function such as `g_mime_utils_header_decode_text()` before displaying to the user.

### g_mime_header_list_get_iter ()

    gboolean            g_mime_header_list_get_iter         (GMimeHeaderList *headers,
                                                             GMimeHeaderIter *iter);

Initializes an iterator for traversing `headers`.

`headers` : | a GMimeHeaderList
`iter` : | a GMimeHeaderIter. [out]
Returns : | a `TRUE` if successful or `FALSE` if there are no headers to traverse.

### g_mime_header_list_foreach ()

    void                g_mime_header_list_foreach          (const GMimeHeaderList *headers,
                                                             GMimeHeaderForeachFunc func,
                                                             gpointer user_data);

Calls `func` for each header name/value pair.

`headers` : | A GMimeHeaderList
`func` : | function to be called for each header. [scope call]
`user_data` : | User data to be passed to the func.

### g_mime_header_list_register_writer ()

    void                g_mime_header_list_register_writer  (GMimeHeaderList *headers,
                                                             const char *name,
                                                             GMimeHeaderWriter writer);

Changes the function used to write `name` headers to `writer` (or the default if `writer` is `NULL`). This is useful if you want to change the default header folding style for a particular header.

`headers` : | a GMimeHeaderList
`name` : | header name
`writer` : | writer function

### g_mime_header_list_write_to_stream ()

    ssize_t             g_mime_header_list_write_to_stream  (const GMimeHeaderList *headers,
                                                             GMimeStream *stream);

Write the headers to a stream.

`headers` : | a GMimeHeaderList
`stream` : | output stream
Returns : | the number of bytes written or `-1` on fail.

### g_mime_header_list_to_string ()

    char *              g_mime_header_list_to_string        (const GMimeHeaderList *headers);

Allocates a string buffer containing the raw rfc822 headers contained in `headers`.

`headers` : | a GMimeHeaderList
Returns : | a string containing the header block.

### g_mime_header_list_get_stream ()

    GMimeStream *       g_mime_header_list_get_stream       (GMimeHeaderList *headers);

Gets the raw stream representing `headers`.

`headers` : | a GMimeHeaderList
Returns : | a GMimeStream if set or `NULL` otherwise. [transfer none]

### g_mime_header_list_set_stream ()

    void                g_mime_header_list_set_stream       (GMimeHeaderList *headers,
                                                             GMimeStream *stream);

Set the raw header stream.

`headers` : | a GMimeHeaderList
`stream` : | a GMimeStream

## See Also

GMimeObject