gmime-utils

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

## Synopsis

    enum                GMimePartEncodingType;
                        GMimeReferences;
    time_t              g_mime_utils_header_decode_date     (const char *in,
                                                             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);
    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);
    GMimeReferences*    g_mime_references_next              (const GMimeReferences *ref);
    char*               g_mime_utils_header_fold            (const char *in);
    char*               g_mime_utils_header_printf          (const char *format,
                                                             ...);
    char*               g_mime_utils_quote_string           (const char *string);
    void                g_mime_utils_unquote_string         (char *string);
    gboolean            g_mime_utils_text_is_8bit           (unsigned char *text,
                                                             size_t len);
    GMimePartEncodingType 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 *in);
    char*               g_mime_utils_header_encode_text     (const char *in);
    char*               g_mime_utils_header_decode_phrase   (const char *in);
    char*               g_mime_utils_header_encode_phrase   (const char *in);
    char*               g_mime_utils_8bit_header_decode     (unsigned char *in);
    char*               g_mime_utils_8bit_header_encode     (unsigned char *in);
    char*               g_mime_utils_8bit_header_encode_phrase
                                                            (unsigned char *in);
    char*               g_mime_utils_structured_header_fold (const char *in);
    char*               g_mime_utils_unstructured_header_fold
                                                            (const char *in);
    #define             GMIME_BASE64_ENCODE_LEN             (x)
    size_t              g_mime_utils_base64_decode_step     (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_utils_base64_encode_step     (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_utils_base64_encode_close    (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);
    #define             GMIME_UUDECODE_STATE_INIT
    #define             GMIME_UUDECODE_STATE_BEGIN
    #define             GMIME_UUDECODE_STATE_END
    #define             GMIME_UUENCODE_LEN                  (x)
    size_t              g_mime_utils_uudecode_step          (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_utils_uuencode_step          (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             unsigned char *uubuf,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_utils_uuencode_close         (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             unsigned char *uubuf,
                                                             int *state,
                                                             guint32 *save);
    #define             GMIME_QP_ENCODE_LEN                 (x)
    size_t              g_mime_utils_quoted_decode_step     (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_utils_quoted_encode_step     (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_utils_quoted_encode_close    (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);

## Description

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

## Details

### enum GMimePartEncodingType

    typedef enum {
    	GMIME_PART_ENCODING_DEFAULT,
    	GMIME_PART_ENCODING_7BIT,
    	GMIME_PART_ENCODING_8BIT,
    	GMIME_PART_ENCODING_BINARY,
    	GMIME_PART_ENCODING_BASE64,
    	GMIME_PART_ENCODING_QUOTEDPRINTABLE,
    	GMIME_PART_ENCODING_UUENCODE,
    	GMIME_PART_NUM_ENCODINGS
    } GMimePartEncodingType;

A Content-Transfer-Encoding type.

`GMIME_PART_ENCODING_DEFAULT` | Default transfer encoding.
`GMIME_PART_ENCODING_7BIT` | 7bit text transfer encoding.
`GMIME_PART_ENCODING_8BIT` | 8bit text transfer encoding.
`GMIME_PART_ENCODING_BINARY` | Binary transfer encoding.
`GMIME_PART_ENCODING_BASE64` | Base64 transfer encoding.
`GMIME_PART_ENCODING_QUOTEDPRINTABLE` | Quoted-printable transfer encoding.
`GMIME_PART_ENCODING_UUENCODE` | Uuencode transfer encoding.
`GMIME_PART_NUM_ENCODINGS` | The number of available transfer encoding enum values.

### 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 *in,
                                                             int *tz_offset);

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

`in` : | input date string
`tz_offset` : | timezone offset
Returns : | the time_t representation of the date string specified by `in` 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_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_next ()

    GMimeReferences*    g_mime_references_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_utils_header_fold ()

    char*               g_mime_utils_header_fold            (const char *in);

Folds a structured header according to the rules in rfc822.

`in` : | input header 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 *string);

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

`string` : | 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 *string);

Unquotes and unescapes a string.

`string` : | 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 ()

    GMimePartEncodingType 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 GMimePartEncodingType that is determined to be the best encoding type for the specified block of text. ("best" in this particular case means best compression)

### 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 *in);

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.

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

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

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

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.

`in` : | 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 *in);

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

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

### g_mime_utils_8bit_header_decode ()

    char*               g_mime_utils_8bit_header_decode     (unsigned char *in);

### Warning

`g_mime_utils_8bit_header_decode` is deprecated and should not be used in newly-written code.

Decodes an rfc2047 encoded header.

WARNING: This function is deprecated. Use `g_mime_utils_header_decode_text()` instead.

`in` : | header to decode
Returns : | the decoded header (which will be in UTF-8 if at all possible).

### g_mime_utils_8bit_header_encode ()

    char*               g_mime_utils_8bit_header_encode     (unsigned char *in);

### Warning

`g_mime_utils_8bit_header_encode` is deprecated and should not be used in newly-written code.

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

WARNING: This function is deprecated. Use `g_mime_utils_header_encode_text()` instead.

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

### g_mime_utils_8bit_header_encode_phrase ()

    char*               g_mime_utils_8bit_header_encode_phrase
                                                            (unsigned char *in);

### Warning

`g_mime_utils_8bit_header_encode_phrase` is deprecated and should not be used in newly-written code.

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

WARNING: This function is deprecated. Use `g_mime_utils_header_encode_phrase()` instead.

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

Folds a structured header according to the rules in rfc822.

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

### g_mime_utils_unstructured_header_fold ()

    char*               g_mime_utils_unstructured_header_fold
                                                            (const char *in);

Folds an unstructured header according to the rules in rfc822.

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

### GMIME_BASE64_ENCODE_LEN()

    #define GMIME_BASE64_ENCODE_LEN(x) ((size_t) (((((x) + 2) / 57) * 77) + 77))

Calculates the maximum number of bytes needed to base64 encode the full input buffer of length `x`.

`x` : | Length of the input data to encode

### g_mime_utils_base64_decode_step ()

    size_t              g_mime_utils_base64_decode_step     (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);

Decodes a chunk of base64 encoded data.

`in` : | input stream
`inlen` : | max length of data to decode
`out` : | output stream
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been decoded
Returns : | the number of bytes decoded (which have been dumped in `out`).

### g_mime_utils_base64_encode_step ()

    size_t              g_mime_utils_base64_encode_step     (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);

Base64 encodes a chunk of data. Performs an 'encode step', only encodes blocks of 3 characters to the output at a time, saves left-over state in state and save (initialise to 0 on first invocation).

`in` : | input stream
`inlen` : | length of the input
`out` : | output string
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been encoded
Returns : | the number of bytes encoded.

### g_mime_utils_base64_encode_close ()

    size_t              g_mime_utils_base64_encode_close    (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);

Base64 encodes the input stream to the output stream. Call this when finished encoding data with `g_mime_utils_base64_encode_step()` to flush off the last little bit.

`in` : | input stream
`inlen` : | length of the input
`out` : | output string
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been encoded
Returns : | the number of bytes encoded.

### GMIME_UUDECODE_STATE_INIT

    #define GMIME_UUDECODE_STATE_INIT   (0)

Initial state for the `g_mime_utils_uudecode_step()` function.

### GMIME_UUDECODE_STATE_BEGIN

    #define GMIME_UUDECODE_STATE_BEGIN  (1 << 16)

State for the `g_mime_utils_uudecode_step()` function, denoting that the 'begin' line has been found.

### GMIME_UUDECODE_STATE_END

    #define GMIME_UUDECODE_STATE_END    (1 << 17)

State for the `g_mime_utils_uudecode_step()` function, denoting that the end of the UU encoded block has been found.

### GMIME_UUENCODE_LEN()

    #define GMIME_UUENCODE_LEN(x)      ((size_t) (((((x) + 2) / 45) * 62) + 62))

Calculates the maximum number of bytes needed to uuencode the full input buffer of length `x`.

`x` : | Length of the input data to encode

### g_mime_utils_uudecode_step ()

    size_t              g_mime_utils_uudecode_step          (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);

Uudecodes a chunk of data. Performs a 'decode step' on a chunk of uuencoded data. Assumes the "begin mode filename" line has been stripped off.

`in` : | input stream
`inlen` : | max length of data to decode
`out` : | output stream
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been decoded
Returns : | the number of bytes decoded.

### g_mime_utils_uuencode_step ()

    size_t              g_mime_utils_uuencode_step          (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             unsigned char *uubuf,
                                                             int *state,
                                                             guint32 *save);

Uuencodes a chunk of data. Performs an 'encode step', only encodes blocks of 45 characters to the output at a time, saves left-over state in `uubuf`, `state` and `save` (initialize to 0 on first invocation).

`in` : | input stream
`inlen` : | input stream length
`out` : | output stream
`uubuf` : | temporary buffer of 60 bytes
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been encoded
Returns : | the number of bytes encoded.

### g_mime_utils_uuencode_close ()

    size_t              g_mime_utils_uuencode_close         (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             unsigned char *uubuf,
                                                             int *state,
                                                             guint32 *save);

Uuencodes a chunk of data. Call this when finished encoding data with `g_mime_utils_uuencode_step()` to flush off the last little bit.

`in` : | input stream
`inlen` : | input stream length
`out` : | output stream
`uubuf` : | temporary buffer of 60 bytes
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been encoded
Returns : | the number of bytes encoded.

### GMIME_QP_ENCODE_LEN()

    #define GMIME_QP_ENCODE_LEN(x)     ((size_t) ((((x) + 1) * 3) + 1))

Calculates the maximum number of bytes needed to encode the full input buffer of length `x` using the quoted-printable encoding.

`x` : | Length of the input data to encode

### g_mime_utils_quoted_decode_step ()

    size_t              g_mime_utils_quoted_decode_step     (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);

Decodes a block of quoted-printable encoded data. Performs a 'decode step' on a chunk of QP encoded data.

`in` : | input stream
`inlen` : | max length of data to decode
`out` : | output stream
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been decoded
Returns : | the number of bytes decoded.

### g_mime_utils_quoted_encode_step ()

    size_t              g_mime_utils_quoted_encode_step     (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);

Quoted-printable encodes a block of text. Performs an 'encode step', saves left-over state in state and save (initialise to -1 on first invocation).

`in` : | input stream
`inlen` : | length of the input
`out` : | output string
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been encoded
Returns : | the number of bytes encoded.

### g_mime_utils_quoted_encode_close ()

    size_t              g_mime_utils_quoted_encode_close    (unsigned char *in,
                                                             size_t inlen,
                                                             unsigned char *out,
                                                             int *state,
                                                             guint32 *save);

Quoted-printable encodes a block of text. Call this when finished encoding data with `g_mime_utils_quoted_encode_step()` to flush off the last little bit.

`in` : | input stream
`inlen` : | length of the input
`out` : | output string
`state` : | holds the number of bits that are stored in `save`
`save` : | leftover bits that have not yet been encoded
Returns : | the number of bytes encoded.