gmime-utils

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

## Functions

time_t | 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 ()
const char * | g_mime_references_get_message_id ()
const GMimeReferences * | g_mime_references_get_next ()
GMimeReferences * | g_mime_references_decode ()
void | g_mime_references_append ()
void | g_mime_references_clear ()
void | g_mime_references_free ()
char * | g_mime_utils_header_fold ()
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 ()

## Types and Values

struct | GMimeReferences

## Description

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

## Functions

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

#### Parameters

str | input date string |
tz_offset | timezone offset. | [out]

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

#### Parameters

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.

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

    const char *
    g_mime_references_get_message_id (const GMimeReferences *ref);

Gets the Message-Id reference from the GMimeReferences node.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

refs | address of a GMimeReferences list |

### g_mime_references_free ()

    void
    g_mime_references_free (GMimeReferences *refs);

Frees the GMimeReferences list.

#### Parameters

refs | a GMimeReferences list |

### g_mime_utils_header_fold ()

    char *
    g_mime_utils_header_fold (const char *header);

Folds a structured header according to the rules in rfc822.

#### Parameters

header | header field and value string |

#### Returns

an allocated string containing the folded header.

WARNING: This function is obsolete. Use `g_mime_utils_structured_header_fold()` instead.

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

#### Parameters

format | string format |
Varargs | 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.

#### 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 'tspecials' as defined by rfc2045.

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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 *header);

Folds a structured header according to the rules in rfc822.

#### Parameters

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 (const char *header);

Folds an unstructured header according to the rules in rfc822.

#### Parameters

header | header field and value string |

#### Returns

an allocated string containing the folded header.

## Types and Values

### struct GMimeReferences

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

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

#### Members

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