## gmime-utils

gmime-utils — MIME utility functions

## Synopsis

                        GMimeReferences;
    time_t              g_mime_utils_header_decode_date     (const char *str,
                                                             int *tz_offset);
    char*               g_mime_utils_header_format_date     (time_t date,
                                                             int tz_offset);
    char*               g_mime_utils_generate_message_id    (const char *fqdn);
    char*               g_mime_utils_decode_message_id      (const char *message_id);
    const char*         g_mime_references_get_message_id    (const GMimeReferences *ref);
    const GMimeReferences* g_mime_references_get_next       (const GMimeReferences *ref);
    GMimeReferences*    g_mime_references_decode            (const char *text);
    void                g_mime_references_append            (GMimeReferences **refs,
                                                             const char *msgid);
    void                g_mime_references_clear             (GMimeReferences **refs);
    void                g_mime_references_free              (GMimeReferences *refs);
    char*               g_mime_utils_header_fold            (const char *str);
    char*               g_mime_utils_header_printf          (const char *format,
                                                             ...);
    char*               g_mime_utils_quote_string           (const char *str);
    void                g_mime_utils_unquote_string         (char *str);
    gboolean            g_mime_utils_text_is_8bit           (unsigned char *text,
                                                             size_t len);
    GMimeContentEncoding g_mime_utils_best_encoding         (unsigned char *text,
                                                             size_t len);
    char*               g_mime_utils_decode_8bit            (const char *text,
                                                             size_t len);
    char*               g_mime_utils_header_decode_text     (const char *text);
    char*               g_mime_utils_header_encode_text     (const char *text);
    char*               g_mime_utils_header_decode_phrase   (const char *phrase);
    char*               g_mime_utils_header_encode_phrase   (const char *phrase);
    char*               g_mime_utils_structured_header_fold (const char *str);
    char*               g_mime_utils_unstructured_header_fold
                                                            (const char *str);

## Description

Utility functions to parse, encode and decode various MIME tokens and encodings.

## Details

### GMimeReferences

    typedef struct {
    	GMimeReferences *next;
    	char *msgid;
    } GMimeReferences;

A List of references, as per the References or In-Reply-To header fields.

GMimeReferences *`next`; | Pointer to the next reference.
char *`msgid`; | Reference message-id.

### g_mime_utils_header_decode_date ()

    time_t              g_mime_utils_header_decode_date     (const char *str,
                                                             int *tz_offset);

Decodes the rfc822 date string and saves the GMT offset into `tz_offset` if non-NULL.

`str` : | input date string
`tz_offset` : | timezone offset
Returns : | the time_t representation of the date string specified by `str` or (time_t) `0` on error. If `tz_offset` is non-NULL, the value of the timezone offset will be stored.

### g_mime_utils_header_format_date ()

    char*               g_mime_utils_header_format_date     (time_t date,
                                                             int tz_offset);

Allocates a string buffer containing the rfc822 formatted date string represented by `time` and `tz_offset`.

`date` : | time_t date representation
`tz_offset` : | Timezone offset
Returns : | a valid string representation of the date.

### g_mime_utils_generate_message_id ()

    char*               g_mime_utils_generate_message_id    (const char *fqdn);

Generates a unique Message-Id.

`fqdn` : | Fully qualified domain name
Returns : | a unique string in an addr-spec format suitable for use as a Message-Id.

### g_mime_utils_decode_message_id ()

    char*               g_mime_utils_decode_message_id      (const char *message_id);

Decodes a msg-id as defined by rfc822.

`message_id` : | string containing a message-id
Returns : | the addr-spec portion of the msg-id.

### g_mime_references_get_message_id ()

    const char*         g_mime_references_get_message_id    (const GMimeReferences *ref);

Gets the Message-Id reference from the GMimeReferences node.

`ref` : | a GMimeReferences list
Returns : | the Message-Id reference from the GMimeReferences node.

### g_mime_references_get_next ()

    const GMimeReferences* g_mime_references_get_next       (const GMimeReferences *ref);

Advances to the next reference node in the GMimeReferences list.

`ref` : | a GMimeReferences list
Returns : | the next reference node in the GMimeReferences list.

### g_mime_references_decode ()

    GMimeReferences*    g_mime_references_decode            (const char *text);

Decodes a list of msg-ids as in the References and/or In-Reply-To headers defined in rfc822.

`text` : | string containing a list of msg-ids
Returns : | a list of referenced msg-ids.

### g_mime_references_append ()

    void                g_mime_references_append            (GMimeReferences **refs,
                                                             const char *msgid);

Appends a reference to msgid to the list of references.

`refs` : | the address of a GMimeReferences list
`msgid` : | a message-id string

### g_mime_references_clear ()

    void                g_mime_references_clear             (GMimeReferences **refs);

Clears the GMimeReferences list and resets it to `NULL`.

`refs` : | address of a GMimeReferences list

### g_mime_references_free ()

    void                g_mime_references_free              (GMimeReferences *refs);

Frees the GMimeReferences list.

`refs` : | a GMimeReferences list

### g_mime_utils_header_fold ()

    char*               g_mime_utils_header_fold            (const char *str);

Folds a structured header according to the rules in rfc822.

`str` : | input string
Returns : | an allocated string containing the folded header.

### g_mime_utils_header_printf ()

    char*               g_mime_utils_header_printf          (const char *format,
                                                             ...);

Allocates a buffer containing a formatted header specified by the `Varargs`.

`format` : | string format
`...` : | arguments
Returns : | an allocated string containing the folded header specified by `format` and the following arguments.

### g_mime_utils_quote_string ()

    char*               g_mime_utils_quote_string           (const char *str);

Quotes `string` as needed according to the rules in rfc2045.

`str` : | input string
Returns : | an allocated string containing the escaped and quoted (if needed to be) input string. The decision to quote the string is based on whether or not the input string contains any 'tspecials' as defined by rfc2045.

### g_mime_utils_unquote_string ()

    void                g_mime_utils_unquote_string         (char *str);

Unquotes and unescapes a string.

`str` : | input string

### g_mime_utils_text_is_8bit ()

    gboolean            g_mime_utils_text_is_8bit           (unsigned char *text,
                                                             size_t len);

Determines if `text` contains 8bit characters within the first `len` bytes.

`text` : | text to check for 8bit chars
`len` : | text length
Returns : | `TRUE` if the text contains 8bit characters or `FALSE` otherwise.

### g_mime_utils_best_encoding ()

    GMimeContentEncoding g_mime_utils_best_encoding         (unsigned char *text,
                                                             size_t len);

Determines the best content encoding for the first `len` bytes of `text`.

`text` : | text to encode
`len` : | text length
Returns : | a GMimeContentEncoding that is determined to be the best encoding type for the specified block of text. ("best" in this particular case means smallest output size)

### g_mime_utils_decode_8bit ()

    char*               g_mime_utils_decode_8bit            (const char *text,
                                                             size_t len);

Attempts to convert text in an unknown 8bit/multibyte charset into UTF-8 by finding the charset which will convert the most bytes into valid UTF-8 characters as possible. If no exact match can be found, it will choose the best match and convert invalid byte sequences into question-marks (?) in the returned string buffer.

`text` : | input text in unknown 8bit/multibyte character set
`len` : | input text length
Returns : | a UTF-8 string representation of `text`.

### g_mime_utils_header_decode_text ()

    char*               g_mime_utils_header_decode_text     (const char *text);

Decodes an rfc2047 encoded 'text' header.

Note: See `g_mime_set_user_charsets()` for details on how charset conversion is handled for unencoded 8bit text and/or wrongly specified rfc2047 encoded-word tokens.

`text` : | header text to decode
Returns : | a newly allocated UTF-8 string representing the the decoded header.

### g_mime_utils_header_encode_text ()

    char*               g_mime_utils_header_encode_text     (const char *text);

Encodes a 'text' header according to the rules in rfc2047.

`text` : | text to encode
Returns : | the encoded header. Useful for encoding headers like "Subject".

### g_mime_utils_header_decode_phrase ()

    char*               g_mime_utils_header_decode_phrase   (const char *phrase);

Decodes an rfc2047 encoded 'phrase' header.

Note: See `g_mime_set_user_charsets()` for details on how charset conversion is handled for unencoded 8bit text and/or wrongly specified rfc2047 encoded-word tokens.

`phrase` : | header to decode
Returns : | a newly allocated UTF-8 string representing the the decoded header.

### g_mime_utils_header_encode_phrase ()

    char*               g_mime_utils_header_encode_phrase   (const char *phrase);

Encodes a 'phrase' header according to the rules in rfc2047.

`phrase` : | phrase to encode
Returns : | the encoded 'phrase'. Useful for encoding internet addresses.

### g_mime_utils_structured_header_fold ()

    char*               g_mime_utils_structured_header_fold (const char *str);

Folds a structured header according to the rules in rfc822.

`str` : | input string
Returns : | an allocated string containing the folded header.

### g_mime_utils_unstructured_header_fold ()

    char*               g_mime_utils_unstructured_header_fold
                                                            (const char *str);

Folds an unstructured header according to the rules in rfc822.

`str` : | input string
Returns : | an allocated string containing the folded header.