GMimeHeaderList: GMime 3.0 Reference Manual

## GMimeHeaderList

GMimeHeaderList — Message and MIME part headers

## Functions

char * | (*GMimeHeaderRawValueFormatter) ()
char * | g_mime_header_format_addrlist ()
char * | g_mime_header_format_content_disposition ()
char * | g_mime_header_format_content_type ()
char * | g_mime_header_format_default ()
char * | g_mime_header_format_message_id ()
char * | g_mime_header_format_received ()
char * | g_mime_header_format_references ()
const char * | g_mime_header_get_name ()
const char * | g_mime_header_get_raw_name ()
gint64 | g_mime_header_get_offset ()
const char * | g_mime_header_get_value ()
void | g_mime_header_set_value ()
const char * | g_mime_header_get_raw_value ()
void | g_mime_header_set_raw_value ()
ssize_t | g_mime_header_write_to_stream ()
GMimeHeaderList * | g_mime_header_list_new ()
int | g_mime_header_list_get_count ()
void | g_mime_header_list_clear ()
gboolean | g_mime_header_list_contains ()
GMimeHeader * | g_mime_header_list_get_header ()
GMimeHeader * | g_mime_header_list_get_header_at ()
void | g_mime_header_list_prepend ()
void | g_mime_header_list_append ()
void | g_mime_header_list_set ()
gboolean | g_mime_header_list_remove ()
void | g_mime_header_list_remove_at ()
ssize_t | g_mime_header_list_write_to_stream ()
char * | g_mime_header_list_to_string ()

## Types and Values

struct | GMimeHeader
struct | GMimeHeaderList

## Object Hierarchy

        GObject
        ├── GMimeHeader
        ╰── GMimeHeaderList

## Description

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

## Functions

### GMimeHeaderRawValueFormatter ()

    char *
    (*GMimeHeaderRawValueFormatter) (GMimeHeader *header,
                                     GMimeFormatOptions *options,
                                     const char *value,
                                     const char *charset);

Function callback for encoding and formatting a header value.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions |
value | an unencoded header value |
charset | a charset |

#### Returns

the encoded and formatted raw header value.

### g_mime_header_format_addrlist ()

    char *
    g_mime_header_format_addrlist (GMimeHeader *header,
                                   GMimeFormatOptions *options,
                                   const char *value,
                                   const char *charset);

Parses the `value` and then re-formats it to conform to the formatting options, folding the value if necessary.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions or `NULL`. | [nullable]
value | a Sender, From, Reply-To, To, Cc, or Bcc header value |
charset | a charset (note: unused) |

#### Returns

a newly allocated string containing the reformatted value.

### g_mime_header_format_content_disposition ()

    char *
    g_mime_header_format_content_disposition
                                   (GMimeHeader *header,
                                    GMimeFormatOptions *options,
                                    const char *value,
                                    const char *charset);

Parses the `value` and then re-formats it to conform to the formatting options, folding the value if necessary.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions or `NULL`. | [nullable]
value | a Content-Disposition header value |
charset | a charset (note: unused) |

#### Returns

a newly allocated string containing the reformatted value.

### g_mime_header_format_content_type ()

    char *
    g_mime_header_format_content_type (GMimeHeader *header,
                                       GMimeFormatOptions *options,
                                       const char *value,
                                       const char *charset);

Parses the `value` and then re-formats it to conform to the formatting options, folding the value if necessary.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions or `NULL`. | [nullable]
value | a Content-Type header value |
charset | a charset (note: unused) |

#### Returns

a newly allocated string containing the reformatted value.

### g_mime_header_format_default ()

    char *
    g_mime_header_format_default (GMimeHeader *header,
                                  GMimeFormatOptions *options,
                                  const char *value,
                                  const char *charset);

Parses the `value` and then re-formats it to conform to the formatting options, folding the value if necessary.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions or `NULL`. | [nullable]
value | a header value |
charset | a charset to use when encoding the `value` |

#### Returns

a newly allocated string containing the reformatted value.

### g_mime_header_format_message_id ()

    char *
    g_mime_header_format_message_id (GMimeHeader *header,
                                     GMimeFormatOptions *options,
                                     const char *value,
                                     const char *charset);

Parses the `value` and then re-formats it to conform to the formatting options, folding the value if necessary.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions or `NULL`. | [nullable]
value | a Message-Id or Content-Id header value |
charset | a charset (note: unused) |

#### Returns

a newly allocated string containing the reformatted value.

### g_mime_header_format_received ()

    char *
    g_mime_header_format_received (GMimeHeader *header,
                                   GMimeFormatOptions *options,
                                   const char *value,
                                   const char *charset);

Parses the `value` and then re-formats it to conform to the formatting options, folding the value if necessary.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions or `NULL`. | [nullable]
value | a Received header value |
charset | a charset (note: unused) |

#### Returns

a newly allocated string containing the reformatted value.

### g_mime_header_format_references ()

    char *
    g_mime_header_format_references (GMimeHeader *header,
                                     GMimeFormatOptions *options,
                                     const char *value,
                                     const char *charset);

Parses the `value` and then re-formats it to conform to the formatting options, folding the value if necessary.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions or `NULL`. | [nullable]
value | a References or In-Reply-To header value |
charset | a charset (note: unused) |

#### Returns

a newly allocated string containing the reformatted value.

### g_mime_header_get_name ()

    const char *
    g_mime_header_get_name (GMimeHeader *header);

Gets the header's name.

#### Parameters

header | a GMimeHeader |

#### Returns

the header name or `NULL` if invalid.

### g_mime_header_get_raw_name ()

    const char *
    g_mime_header_get_raw_name (GMimeHeader *header);

Gets the header's raw name. The raw header name is the complete string up to (but not including) the ':' separating the header's name from its value. This string may be different from the value returned by `g_mime_header_get_name()` if the parsed message's header contained trailing whitespace after the header name, such as: "Subject : this is the subject\r\n".

#### Parameters

header | a GMimeHeader |

#### Returns

the raw header name.

### g_mime_header_get_offset ()

    gint64
    g_mime_header_get_offset (GMimeHeader *header);

Gets the header's stream offset if known.

#### Parameters

header | a GMimeHeader |

#### Returns

the header offset or `-1` if unknown.

### g_mime_header_get_value ()

    const char *
    g_mime_header_get_value (GMimeHeader *header);

Gets the header's unfolded value.

#### Parameters

header | a GMimeHeader |

#### Returns

the header's decoded value or `NULL` if invalid.

### g_mime_header_set_value ()

    void
    g_mime_header_set_value (GMimeHeader *header,
                             GMimeFormatOptions *options,
                             const char *value,
                             const char *charset);

Sets the header's decoded value.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions or `NULL`. | [nullable]
value | the new header value |
charset | a charset |

### g_mime_header_get_raw_value ()

    const char *
    g_mime_header_get_raw_value (GMimeHeader *header);

Gets the header's raw (folded) value.

#### Parameters

header | a GMimeHeader |

#### Returns

the header value or `NULL` if invalid.

### g_mime_header_set_raw_value ()

    void
    g_mime_header_set_raw_value (GMimeHeader *header,
                                 const char *raw_value);

Sets the header's raw value.

#### Parameters

header | a GMimeHeader |
raw_value | the raw value |

### g_mime_header_write_to_stream ()

    ssize_t
    g_mime_header_write_to_stream (GMimeHeader *header,
                                   GMimeFormatOptions *options,
                                   GMimeStream *stream);

Write the header to the specified stream.

#### Parameters

header | a GMimeHeader |
options | a GMimeFormatOptions or `NULL`. | [nullable]
stream | a GMimeStream |

#### Returns

the number of bytes written, or `-1` on fail.

### g_mime_header_list_new ()

    GMimeHeaderList *
    g_mime_header_list_new (GMimeParserOptions *options);

Creates a new GMimeHeaderList object.

#### Parameters

options | a GMimeParserOptions or `NULL`. | [nullable]

#### Returns

a new header list object.

### g_mime_header_list_get_count ()

    int
    g_mime_header_list_get_count (GMimeHeaderList *headers);

Gets the number of headers contained within the header list.

#### Parameters

headers | a GMimeHeaderList |

#### Returns

the number of headers in the header list.

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

    GMimeHeader *
    g_mime_header_list_get_header (GMimeHeaderList *headers,
                                   const char *name);

Gets the first header with the specified name.

#### Parameters

headers | a GMimeHeaderList |
name | header name |

#### Returns

a GMimeHeader for the specified `name` .

[transfer none]

### g_mime_header_list_get_header_at ()

    GMimeHeader *
    g_mime_header_list_get_header_at (GMimeHeaderList *headers,
                                      int index);

Gets the header at the specified `index` within the list.

#### Parameters

headers | a GMimeHeaderList |
index | the 0-based index of the header |

#### Returns

the header at position `index` .

[transfer none]

### g_mime_header_list_prepend ()

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

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.

#### Parameters

headers | a GMimeHeaderList |
name | header name |
value | header value |
charset | a charset |

### g_mime_header_list_append ()

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

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.

#### Parameters

headers | a GMimeHeaderList |
name | header name |
value | header value |
charset | a charset |

### g_mime_header_list_set ()

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

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.

#### Parameters

headers | a GMimeHeaderList |
name | header name |
value | header value |
charset | a charset |

### g_mime_header_list_remove ()

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

Remove the first instance of 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_remove_at ()

    void
    g_mime_header_list_remove_at (GMimeHeaderList *headers,
                                  int index);

Removes the header at the specified `index` from `headers` .

#### Parameters

headers | a GMimeHeaderList |
index | the 0-based index of the header to remove |

### g_mime_header_list_write_to_stream ()

    ssize_t
    g_mime_header_list_write_to_stream (GMimeHeaderList *headers,
                                        GMimeFormatOptions *options,
                                        GMimeStream *stream);

Write the headers to a stream.

#### Parameters

headers | a GMimeHeaderList |
options | a GMimeFormatOptions or `NULL`. | [nullable]
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 (GMimeHeaderList *headers,
                                  GMimeFormatOptions *options);

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

#### Parameters

headers | a GMimeHeaderList |
options | a GMimeFormatOptions or `NULL`. | [nullable]

#### Returns

a string containing the header block.

## Types and Values

### struct GMimeHeader

    struct GMimeHeader;

A message or mime-part header.

#### Members

### struct GMimeHeaderList

    struct GMimeHeaderList;

A list of message or mime-part headers.

## See Also

GMimeObject