GMimeHeader

GMimeHeader — Message and MIME part headers

Functions

Types and Values

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