gmime-encodings

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

## Synopsis

    enum                GMimeContentEncoding;
    GMimeContentEncoding g_mime_content_encoding_from_string
                                                            (const char *str);
    const char *        g_mime_content_encoding_to_string   (GMimeContentEncoding encoding);
    enum                GMimeEncodingConstraint;
                        GMimeEncoding;
    void                g_mime_encoding_init_encode         (GMimeEncoding *state,
                                                             GMimeContentEncoding encoding);
    void                g_mime_encoding_init_decode         (GMimeEncoding *state,
                                                             GMimeContentEncoding encoding);
    void                g_mime_encoding_reset               (GMimeEncoding *state);
    size_t              g_mime_encoding_outlen              (GMimeEncoding *state,
                                                             size_t inlen);
    size_t              g_mime_encoding_step                (GMimeEncoding *state,
                                                             const char *inbuf,
                                                             size_t inlen,
                                                             char *outbuf);
    size_t              g_mime_encoding_flush               (GMimeEncoding *state,
                                                             const char *inbuf,
                                                             size_t inlen,
                                                             char *outbuf);
    #define             GMIME_BASE64_ENCODE_LEN             (x)
    size_t              g_mime_encoding_base64_decode_step  (const unsigned char *inbuf,
                                                             size_t inlen,
                                                             unsigned char *outbuf,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_encoding_base64_encode_step  (const unsigned char *inbuf,
                                                             size_t inlen,
                                                             unsigned char *outbuf,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_encoding_base64_encode_close (const unsigned char *inbuf,
                                                             size_t inlen,
                                                             unsigned char *outbuf,
                                                             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_encoding_uudecode_step       (const unsigned char *inbuf,
                                                             size_t inlen,
                                                             unsigned char *outbuf,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_encoding_uuencode_step       (const unsigned char *inbuf,
                                                             size_t inlen,
                                                             unsigned char *outbuf,
                                                             unsigned char *uubuf,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_encoding_uuencode_close      (const unsigned char *inbuf,
                                                             size_t inlen,
                                                             unsigned char *outbuf,
                                                             unsigned char *uubuf,
                                                             int *state,
                                                             guint32 *save);
    #define             GMIME_QP_ENCODE_LEN                 (x)
    size_t              g_mime_encoding_quoted_decode_step  (const unsigned char *inbuf,
                                                             size_t inlen,
                                                             unsigned char *outbuf,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_encoding_quoted_encode_step  (const unsigned char *inbuf,
                                                             size_t inlen,
                                                             unsigned char *outbuf,
                                                             int *state,
                                                             guint32 *save);
    size_t              g_mime_encoding_quoted_encode_close (const unsigned char *inbuf,
                                                             size_t inlen,
                                                             unsigned char *outbuf,
                                                             int *state,
                                                             guint32 *save);

## Description

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

## Details

### enum GMimeContentEncoding

    typedef enum {
    	GMIME_CONTENT_ENCODING_DEFAULT,
    	GMIME_CONTENT_ENCODING_7BIT,
    	GMIME_CONTENT_ENCODING_8BIT,
    	GMIME_CONTENT_ENCODING_BINARY,
    	GMIME_CONTENT_ENCODING_BASE64,
    	GMIME_CONTENT_ENCODING_QUOTEDPRINTABLE,
    	GMIME_CONTENT_ENCODING_UUENCODE
    } GMimeContentEncoding;

A Content-Transfer-Encoding enumeration.

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

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

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

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

### enum GMimeEncodingConstraint

    typedef enum {
    	GMIME_ENCODING_CONSTRAINT_7BIT,
    	GMIME_ENCODING_CONSTRAINT_8BIT,
    	GMIME_ENCODING_CONSTRAINT_BINARY
    } 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.

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

### GMimeEncoding

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

A context used for encoding or decoding data.

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

### g_mime_encoding_init_encode ()

    void                g_mime_encoding_init_encode         (GMimeEncoding *state,
                                                             GMimeContentEncoding encoding);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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