gmime-encodings

gmime-encodings — MIME encoding functions

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

 

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.