gmime-utils: GMime 3.0 Reference Manual

## gmime-utils gmime-utils — MIME utility functions |

## Functions

GDateTime * | g_mime_utils_header_decode_date ()
char * | g_mime_utils_header_format_date ()
char * | g_mime_utils_generate_message_id ()
char * | g_mime_utils_decode_message_id ()
char * | g_mime_utils_header_printf ()
char * | g_mime_utils_quote_string ()
void | g_mime_utils_unquote_string ()
gboolean | g_mime_utils_text_is_8bit ()
GMimeContentEncoding | g_mime_utils_best_encoding ()
char * | g_mime_utils_decode_8bit ()
char * | g_mime_utils_header_decode_text ()
char * | g_mime_utils_header_encode_text ()
char * | g_mime_utils_header_decode_phrase ()
char * | g_mime_utils_header_encode_phrase ()
char * | g_mime_utils_structured_header_fold ()
char * | g_mime_utils_unstructured_header_fold ()
char * | g_mime_utils_header_unfold ()

## Description

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

## Functions

### g_mime_utils_header_decode_date ()

    GDateTime *
    g_mime_utils_header_decode_date (const char *str);

Parses the rfc822 date string.

#### Parameters

str | input date string |

#### Returns

the GDateTime representation of the date string specified by `str` or `NULL` on error.

[nullable][transfer full]

### g_mime_utils_header_format_date ()

    char *
    g_mime_utils_header_format_date (GDateTime *date);

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

#### Parameters

date | a GDateTime |

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

#### Parameters

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.

#### Parameters

message_id | string containing a message-id |

#### Returns

the addr-spec portion of the msg-id.

### g_mime_utils_header_printf ()

    char *
    g_mime_utils_header_printf (GMimeParserOptions *options,
                                GMimeFormatOptions *format,
                                const char *text,
                                ...);

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

#### Parameters

options | a GMimeParserOptions or `NULL`. | [nullable]
format | a GMimeFormatOptions or `NULL`. | [nullable]
text | text with printf-style formatters |
... | arguments |

#### Returns

an allocated string containing the folded header specified by `text` 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 rfc2822.

#### Parameters

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 'specials' as defined by rfc2822.

### g_mime_utils_unquote_string ()

    void
    g_mime_utils_unquote_string (char *str);

Unquotes and unescapes a string.

#### Parameters

str | input string |

### g_mime_utils_text_is_8bit ()

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

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

#### Parameters

text | text to check for 8bit chars. | [array length=len][element-type guint8]
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 (const unsigned char *text,
                                size_t len);

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

#### Parameters

text | text to encode. | [array length=len][element-type guint8]
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 (GMimeParserOptions *options,
                              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.

#### Parameters

options | a GMimeParserOptions or `NULL`. | [nullable]
text | input text in unknown 8bit/multibyte character set. | [array length=len][element-type guint8]
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 (GMimeParserOptions *options,
                                     const char *text);

Decodes an rfc2047 encoded 'text' header.

#### Parameters

text | header text to decode |
options | a GMimeParserOptions or `NULL`. | [nullable]

#### 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 (GMimeFormatOptions *options,
                                     const char *text,
                                     const char *charset);

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

#### Parameters

options | a GMimeFormatOptions or `NULL`. | [nullable]
text | text to encode |
charset | the charset to use or `NULL` to use the default. | [nullable]

#### Returns

the encoded header. Useful for encoding headers like "Subject".

### g_mime_utils_header_decode_phrase ()

    char *
    g_mime_utils_header_decode_phrase (GMimeParserOptions *options,
                                       const char *phrase);

Decodes an rfc2047 encoded 'phrase' header.

#### Parameters

phrase | header to decode |
options | a GMimeParserOptions or `NULL`. | [nullable]

#### 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 (GMimeFormatOptions *options,
                                       const char *phrase,
                                       const char *charset);

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

#### Parameters

options | a GMimeFormatOptions or `NULL`. | [nullable]
phrase | phrase to encode |
charset | the charset to use or `NULL` to use the default. | [nullable]

#### Returns

the encoded 'phrase'. Useful for encoding internet addresses.

### g_mime_utils_structured_header_fold ()

    char *
    g_mime_utils_structured_header_fold (GMimeParserOptions *options,
                                         GMimeFormatOptions *format,
                                         const char *header);

Folds a structured header according to the rules in rfc822.

#### Parameters

options | a GMimeParserOptions or `NULL`. | [nullable]
format | a GMimeFormatOptions or `NULL`. | [nullable]
header | header field and value string |

#### Returns

an allocated string containing the folded header.

### g_mime_utils_unstructured_header_fold ()

    char *
    g_mime_utils_unstructured_header_fold (GMimeParserOptions *options,
                                           GMimeFormatOptions *format,
                                           const char *header);

Folds an unstructured header according to the rules in rfc822.

#### Parameters

options | a GMimeParserOptions or `NULL`. | [nullable]
format | a GMimeFormatOptions or `NULL`. | [nullable]
header | header field and value string |

#### Returns

an allocated string containing the folded header.

### g_mime_utils_header_unfold ()

    char *
    g_mime_utils_header_unfold (const char *value);

Unfolds a raw header value according to the rules in rfc822.

#### Parameters

value | raw header value |

#### Returns

an allocated string containing the unfolded header value.