GMimeHeader: GMime 2.6 Reference Manual

## GMimeHeader GMimeHeader — Message and MIME part headers |

## Functions

ssize_t | (*GMimeHeaderWriter) ()
void | (*GMimeHeaderForeachFunc) ()
GMimeHeaderIter * | g_mime_header_iter_new ()
void | g_mime_header_iter_free ()
GMimeHeaderIter * | g_mime_header_iter_copy ()
void | g_mime_header_iter_copy_to ()
gboolean | g_mime_header_iter_equal ()
gboolean | g_mime_header_iter_first ()
gboolean | g_mime_header_iter_last ()
gboolean | g_mime_header_iter_next ()
gboolean | g_mime_header_iter_prev ()
gboolean | g_mime_header_iter_is_valid ()
const char * | g_mime_header_iter_get_name ()
const char * | g_mime_header_iter_get_value ()
gboolean | g_mime_header_iter_set_value ()
gboolean | g_mime_header_iter_remove ()
GMimeHeaderList * | g_mime_header_list_new ()
void | g_mime_header_list_destroy ()
void | g_mime_header_list_clear ()
gboolean | g_mime_header_list_contains ()
void | g_mime_header_list_prepend ()
void | g_mime_header_list_append ()
gboolean | g_mime_header_list_remove ()
void | g_mime_header_list_set ()
const char * | g_mime_header_list_get ()
gboolean | g_mime_header_list_get_iter ()
void | g_mime_header_list_foreach ()
void | g_mime_header_list_register_writer ()
ssize_t | g_mime_header_list_write_to_stream ()
char * | g_mime_header_list_to_string ()
GMimeStream * | g_mime_header_list_get_stream ()
void | g_mime_header_list_set_stream ()

## Types and Values

struct | GMimeHeaderIter
| GMimeHeaderList

## Description

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

## Functions

### GMimeHeaderWriter ()

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

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

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

headers | a GMimeHeaderList |

### g_mime_header_list_clear ()

    void
    g_mime_header_list_clear (GMimeHeaderList *headers);

Removes all of the headers from the GMimeHeaderList.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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 specified name.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

headers | a GMimeHeaderList |
stream | a GMimeStream |

## Types and Values

### struct GMimeHeaderIter

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

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

#### Members

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.

## See Also

GMimeObject