gmime-encodings: GMime 3.0 Reference Manual

## gmime-encodings gmime-encodings — MIME encoding functions |

## Functions

GMimeContentEncoding | g_mime_content_encoding_from_string ()
const char * | g_mime_content_encoding_to_string ()
void | g_mime_encoding_init_encode ()
void | g_mime_encoding_init_decode ()
void | g_mime_encoding_reset ()
size_t | g_mime_encoding_outlen ()
size_t | g_mime_encoding_step ()
size_t | g_mime_encoding_flush ()
#define | GMIME_BASE64_ENCODE_LEN()
size_t | g_mime_encoding_base64_decode_step ()
size_t | g_mime_encoding_base64_encode_step ()
size_t | g_mime_encoding_base64_encode_close ()
#define | GMIME_UUENCODE_LEN()
size_t | g_mime_encoding_uudecode_step ()
size_t | g_mime_encoding_uuencode_step ()
size_t | g_mime_encoding_uuencode_close ()
#define | GMIME_QP_ENCODE_LEN()
size_t | g_mime_encoding_quoted_decode_step ()
size_t | g_mime_encoding_quoted_encode_step ()
size_t | g_mime_encoding_quoted_encode_close ()

## Types and Values

enum | GMimeContentEncoding
enum | GMimeEncodingConstraint
struct | GMimeEncoding
#define | GMIME_UUDECODE_STATE_INIT
#define | GMIME_UUDECODE_STATE_BEGIN
#define | GMIME_UUDECODE_STATE_END

## Description

Utility functions to encode or decode MIME Content-Transfer-Encodings.

## Functions

### g_mime_content_encoding_from_string ()

    GMimeContentEncoding
    g_mime_content_encoding_from_string (const char *str);

Gets the appropriate GMimeContentEncoding enumeration value based on the input string.

#### Parameters

str | a string representing a Content-Transfer-Encoding value |

#### Returns

the GMimeContentEncoding specified by `str` or GMIME_CONTENT_ENCODING_DEFAULT on error.

### g_mime_content_encoding_to_string ()

    const char *
    g_mime_content_encoding_to_string (GMimeContentEncoding encoding);

Gets the string value of the content encoding.

#### Parameters

encoding | a GMimeContentEncoding |

#### Returns

the encoding type as a string or `NULL` on error. Available values for the encoding are: GMIME_CONTENT_ENCODING_DEFAULT, GMIME_CONTENT_ENCODING_7BIT, GMIME_CONTENT_ENCODING_8BIT, GMIME_CONTENT_ENCODING_BINARY, GMIME_CONTENT_ENCODING_BASE64, GMIME_CONTENT_ENCODING_QUOTEDPRINTABLE and GMIME_CONTENT_ENCODING_UUENCODE.

### g_mime_encoding_init_encode ()

    void
    g_mime_encoding_init_encode (GMimeEncoding *state,
                                 GMimeContentEncoding encoding);

Initializes a GMimeEncoding state machine for encoding to `encoding` .

#### Parameters

state | a GMimeEncoding to initialize |
encoding | a GMimeContentEncoding to use |

### g_mime_encoding_init_decode ()

    void
    g_mime_encoding_init_decode (GMimeEncoding *state,
                                 GMimeContentEncoding encoding);

Initializes a GMimeEncoding state machine for decoding from `encoding` .

#### Parameters

state | a GMimeEncoding to initialize |
encoding | a GMimeContentEncoding to use |

### g_mime_encoding_reset ()

    void
    g_mime_encoding_reset (GMimeEncoding *state);

Resets the state of the GMimeEncoding.

#### Parameters

state | a GMimeEncoding to reset |

### g_mime_encoding_outlen ()

    size_t
    g_mime_encoding_outlen (GMimeEncoding *state,
                            size_t inlen);

Given the input length, `inlen` , calculate the needed output length to perform an encoding or decoding step.

#### Parameters

state | a GMimeEncoding |
inlen | an input length |

#### Returns

the maximum number of bytes needed to encode or decode a buffer of `inlen` bytes.

### g_mime_encoding_step ()

    size_t
    g_mime_encoding_step (GMimeEncoding *state,
                          const char *inbuf,
                          size_t inlen,
                          char *outbuf);

Incrementally encodes or decodes (depending on `state` ) an input stream by 'stepping' through a block of input at a time.

You should make sure `outbuf` is large enough by calling `g_mime_encoding_outlen()` to find out how large `outbuf` might need to be.

#### Parameters

state | a GMimeEncoding |
inbuf | an input buffer to encode or decode |
inlen | input buffer length |
outbuf | an output buffer |

#### Returns

the number of bytes written to `outbuf` .

### g_mime_encoding_flush ()

    size_t
    g_mime_encoding_flush (GMimeEncoding *state,
                           const char *inbuf,
                           size_t inlen,
                           char *outbuf);

Completes the incremental encode or decode of the input stream (see `g_mime_encoding_step()` for details).

#### Parameters

state | a GMimeEncoding |
inbuf | an input buffer to encode or decode |
inlen | input buffer length |
outbuf | an output buffer |

#### Returns

the number of bytes written to `outbuf` .

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

#### Parameters

x | Length of the input data to encode |

#### Returns

the number of output bytes needed to base64 encode an input buffer of size `x` .

### g_mime_encoding_base64_decode_step ()

    size_t
    g_mime_encoding_base64_decode_step (const unsigned char *inbuf,
                                        size_t inlen,
                                        unsigned char *outbuf,
                                        int *state,
                                        guint32 *save);

Decodes a chunk of base64 encoded data.

#### Parameters

inbuf | input buffer |
inlen | input buffer length |
outbuf | output buffer |
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 `outbuf` ).

### g_mime_encoding_base64_encode_step ()

    size_t
    g_mime_encoding_base64_encode_step (const unsigned char *inbuf,
                                        size_t inlen,
                                        unsigned char *outbuf,
                                        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).

#### Parameters

inbuf | input buffer |
inlen | input buffer length |
outbuf | output buffer |
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_encoding_base64_encode_close ()

    size_t
    g_mime_encoding_base64_encode_close (const unsigned char *inbuf,
                                         size_t inlen,
                                         unsigned char *outbuf,
                                         int *state,
                                         guint32 *save);

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

#### Parameters

inbuf | input buffer |
inlen | input buffer length |
outbuf | output buffer |
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_UUENCODE_LEN()

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

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

#### Parameters

x | Length of the input data to encode |

#### Returns

the number of output bytes needed to uuencode an input buffer of size `x` .

### g_mime_encoding_uudecode_step ()

    size_t
    g_mime_encoding_uudecode_step (const unsigned char *inbuf,
                                   size_t inlen,
                                   unsigned char *outbuf,
                                   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.

#### Parameters

inbuf | input buffer |
inlen | input buffer length |
outbuf | output buffer |
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_encoding_uuencode_step ()

    size_t
    g_mime_encoding_uuencode_step (const unsigned char *inbuf,
                                   size_t inlen,
                                   unsigned char *outbuf,
                                   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).

#### Parameters

inbuf | input buffer |
inlen | input buffer length |
outbuf | 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_encoding_uuencode_close ()

    size_t
    g_mime_encoding_uuencode_close (const unsigned char *inbuf,
                                    size_t inlen,
                                    unsigned char *outbuf,
                                    unsigned char *uubuf,
                                    int *state,
                                    guint32 *save);

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

#### Parameters

inbuf | input buffer |
inlen | input buffer length |
outbuf | output buffer |
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) / 24) * 74) + 74))

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

#### Parameters

x | Length of the input data to encode |

#### Returns

the number of output bytes needed to encode an input buffer of size `x` using the quoted-printable encoding.

### g_mime_encoding_quoted_decode_step ()

    size_t
    g_mime_encoding_quoted_decode_step (const unsigned char *inbuf,
                                        size_t inlen,
                                        unsigned char *outbuf,
                                        int *state,
                                        guint32 *save);

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

#### Parameters

inbuf | input buffer |
inlen | input buffer length |
outbuf | output buffer |
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_encoding_quoted_encode_step ()

    size_t
    g_mime_encoding_quoted_encode_step (const unsigned char *inbuf,
                                        size_t inlen,
                                        unsigned char *outbuf,
                                        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).

#### Parameters

inbuf | input buffer |
inlen | input buffer length |
outbuf | output buffer |
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_encoding_quoted_encode_close ()

    size_t
    g_mime_encoding_quoted_encode_close (const unsigned char *inbuf,
                                         size_t inlen,
                                         unsigned char *outbuf,
                                         int *state,
                                         guint32 *save);

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

#### Parameters

inbuf | input buffer |
inlen | input buffer length |
outbuf | output buffer |
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.

## Types and Values

### enum GMimeContentEncoding

A Content-Transfer-Encoding enumeration.

#### Members

GMIME_CONTENT_ENCODING_DEFAULT | Default transfer encoding. |
GMIME_CONTENT_ENCODING_7BIT | 7bit text transfer encoding. |
GMIME_CONTENT_ENCODING_8BIT | 8bit text transfer encoding. |
GMIME_CONTENT_ENCODING_BINARY | Binary transfer encoding. |
GMIME_CONTENT_ENCODING_BASE64 | Base64 transfer encoding. |
GMIME_CONTENT_ENCODING_QUOTEDPRINTABLE | Quoted-printable transfer encoding. |
GMIME_CONTENT_ENCODING_UUENCODE | Uuencode transfer encoding. |

### enum GMimeEncodingConstraint

Used with functions like `g_mime_filter_best_encoding()` and `g_mime_object_encode()` as the 'constraint' argument. These values provide a means of letting the filter know what the encoding constraints are for the stream.

#### Members

GMIME_ENCODING_CONSTRAINT_7BIT | The stream data must fit within the 7bit ASCII range. |
GMIME_ENCODING_CONSTRAINT_8BIT | The stream data may have bytes with the high bit set, but no null bytes. |
GMIME_ENCODING_CONSTRAINT_BINARY | The stream may contain any binary data. |

### struct GMimeEncoding

    struct GMimeEncoding {
    	GMimeContentEncoding encoding;
    	unsigned char uubuf[60];
    	gboolean encode;
    	guint32 save;
    	int state;
    };

A context used for encoding or decoding data.

#### Members

GMimeContentEncoding `encoding`; | the type of encoding |
unsigned char `uubuf`[60]; | a temporary buffer needed when uuencoding data |
gboolean `encode`; | `TRUE` if encoding or `FALSE` if decoding |
guint32 `save`; | saved bytes from the previous step |
int `state`; | current encder/decoder state |

### GMIME_UUDECODE_STATE_INIT

    #define GMIME_UUDECODE_STATE_INIT   (0)

Initial state for the `g_mime_encoding_uudecode_step()` function.

### GMIME_UUDECODE_STATE_BEGIN

    #define GMIME_UUDECODE_STATE_BEGIN  (1 << 16)

State for the `g_mime_encoding_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_encoding_uudecode_step()` function, denoting that the end of the UU encoded block has been found.