Functions

charset_best (inbuf, inlen)

charset_canon_name (charset)

charset_iconv_name (charset)

charset_iso_to_windows (isocharset)

charset_language (charset)

charset_locale_name ()

charset_map_init ()

charset_map_shutdown ()

charset_name (charset)

check_version (major, minor, micro)

content_encoding_from_string (str)

content_encoding_to_string (encoding)

encoding_base64_decode_step (inbuf, inlen, outbuf, state, save)

encoding_base64_encode_close (inbuf, inlen, outbuf, state, save)

encoding_base64_encode_step (inbuf, inlen, outbuf, state, save)

encoding_quoted_decode_step (inbuf, inlen, outbuf, state, save)

encoding_quoted_encode_close (inbuf, inlen, outbuf, state, save)

encoding_quoted_encode_step (inbuf, inlen, outbuf, state, save)

encoding_uudecode_step (inbuf, inlen, outbuf, state, save)

encoding_uuencode_close (inbuf, inlen, outbuf, uubuf, state, save)

encoding_uuencode_step (inbuf, inlen, outbuf, uubuf, state, save)

format_options_get_default ()

iconv_locale_to_utf8 (str)

iconv_locale_to_utf8_length (str, n)

iconv_utf8_to_locale (str)

iconv_utf8_to_locale_length (str, n)

init ()

locale_charset ()

locale_language ()

parser_options_get_default ()

references_parse (options, text)

shutdown ()

utils_best_encoding (text)

utils_decode_8bit (options, text)

utils_decode_message_id (message_id)

utils_generate_message_id (fqdn)

utils_header_decode_date (str)

utils_header_decode_phrase (options, phrase)

utils_header_decode_text (options, text)

utils_header_encode_phrase (options, phrase, charset)

utils_header_encode_text (options, text, charset)

utils_header_format_date (date)

utils_header_unfold (value)

utils_quote_string (str)

utils_structured_header_fold (options, format, header)

utils_text_is_8bit (text)

utils_unquote_string (str)

utils_unstructured_header_fold (options, format, header)

ydecode_step (inbuf, inlen, outbuf, state, pcrc, crc)

yencode_close (inbuf, inlen, outbuf, state, pcrc, crc)

yencode_step (inbuf, inlen, outbuf, state, pcrc, crc)

Details

GMime.charset_best(inbuf, inlen)
Parameters:

  • inbuf (str) – a UTF-8 text buffer

  • inlen (int) – input buffer length

Returns:

the charset name best suited for the input text or None if it is ascii-safe.

Return type:

str or None

Computes the best charset to use to encode this text buffer.

GMime.charset_canon_name(charset)
Parameters:

charset (str) – charset name

Returns:

a canonical charset name for charset.

Return type:

str

Attempts to find a canonical charset name for charset.

Note: Will normally return the same value as GMime.Charset.iconv_name() unless the system iconv does not use the canonical ISO charset names (such as using ISO8859-1 rather than the canonical form ISO-8859-1).

GMime.charset_iconv_name(charset)
Parameters:

charset (str) – charset name

Returns:

an iconv-friendly charset name for charset.

Return type:

str

Attempts to find an iconv-friendly charset name for charset.

GMime.charset_iso_to_windows(isocharset)
Parameters:

isocharset (str) – ISO-8859-# charset

Returns:

equivalent Windows charset.

Return type:

str

Maps the ISO-8859-# charset to the equivalent Windows-CP125# charset.

GMime.charset_language(charset)
Parameters:

charset (str) – charset name

Returns:

a language code that is specific to charset, or None on fail.

Return type:

str or None

Attempts to find a specific language code that is specific to charset. Currently only handles CJK and Russian/Ukranian charset->lang mapping. Everything else will return None.

GMime.charset_locale_name()
Returns:

the user’s locale charset (or iso-8859-1 by default).

Return type:

str

Gets the user’s locale charset (or iso-8859-1 by default).

Note: This function is deprecated. Use GMime.locale_charset() instead.

GMime.charset_map_init()

Initializes character set maps.

Note: GMime.init() calls this routine for you.

GMime.charset_map_shutdown()

Frees internal lookup tables created in GMime.Charset.map_init().

GMime.charset_name(charset)
Parameters:

charset (str) – charset name

Returns:

an iconv-friendly charset name for charset.

Return type:

str

Attempts to find an iconv-friendly charset name for charset.

Note: This function is deprecated. Use GMime.Charset.iconv_name() instead.

GMime.check_version(major, minor, micro)
Parameters:

  • major (int) – Minimum major version

  • minor (int) – Minimum minor version

  • micro (int) – Minimum micro version

Returns:

True if the requirement is met or False otherwise.

Return type:

bool

Checks that the GMime library version meets the requirements of the required version.

GMime.content_encoding_from_string(str)
Parameters:

str (str) – a string representing a Content-Transfer-Encoding value

Returns:

the GMime.ContentEncoding specified by str or GMime.ContentEncoding.DEFAULT on error.

Return type:

GMime.ContentEncoding

Gets the appropriate GMime.ContentEncoding enumeration value based on the input string.

GMime.content_encoding_to_string(encoding)
Parameters:

encoding (GMime.ContentEncoding) – a GMime.ContentEncoding

Returns:

the encoding type as a string or None on error. Available values for the encoding are: GMime.ContentEncoding.DEFAULT, GMime.ContentEncoding._7BIT, GMime.ContentEncoding._8BIT, GMime.ContentEncoding.BINARY, GMime.ContentEncoding.BASE64, GMime.ContentEncoding.QUOTEDPRINTABLE and GMime.ContentEncoding.UUENCODE.

Return type:

str

Gets the string value of the content encoding.

GMime.encoding_base64_decode_step(inbuf, inlen, outbuf, state, save)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – holds the number of bits that are stored in save

  • save (int) – leftover bits that have not yet been decoded

Returns:

the number of bytes decoded (which have been dumped in outbuf).

Return type:

int

Decodes a chunk of base64 encoded data.

GMime.encoding_base64_encode_close(inbuf, inlen, outbuf, state, save)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – holds the number of bits that are stored in save

  • save (int) – leftover bits that have not yet been encoded

Returns:

the number of bytes encoded.

Return type:

int

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

GMime.encoding_base64_encode_step(inbuf, inlen, outbuf, state, save)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – holds the number of bits that are stored in save

  • save (int) – leftover bits that have not yet been encoded

Returns:

the number of bytes encoded.

Return type:

int

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

GMime.encoding_quoted_decode_step(inbuf, inlen, outbuf, state, save)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – holds the number of bits that are stored in save

  • save (int) – leftover bits that have not yet been decoded

Returns:

the number of bytes decoded.

Return type:

int

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

GMime.encoding_quoted_encode_close(inbuf, inlen, outbuf, state, save)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – holds the number of bits that are stored in save

  • save (int) – leftover bits that have not yet been encoded

Returns:

the number of bytes encoded.

Return type:

int

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

GMime.encoding_quoted_encode_step(inbuf, inlen, outbuf, state, save)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – holds the number of bits that are stored in save

  • save (int) – leftover bits that have not yet been encoded

Returns:

the number of bytes encoded.

Return type:

int

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

GMime.encoding_uudecode_step(inbuf, inlen, outbuf, state, save)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – holds the number of bits that are stored in save

  • save (int) – leftover bits that have not yet been decoded

Returns:

the number of bytes decoded.

Return type:

int

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.

GMime.encoding_uuencode_close(inbuf, inlen, outbuf, uubuf, state, save)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • uubuf (int) – temporary buffer of 60 bytes

  • state (int) – holds the number of bits that are stored in save

  • save (int) – leftover bits that have not yet been encoded

Returns:

the number of bytes encoded.

Return type:

int

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

GMime.encoding_uuencode_step(inbuf, inlen, outbuf, uubuf, state, save)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output stream

  • uubuf (int) – temporary buffer of 60 bytes

  • state (int) – holds the number of bits that are stored in save

  • save (int) – leftover bits that have not yet been encoded

Returns:

the number of bytes encoded.

Return type:

int

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

GMime.format_options_get_default()
Returns:

the default format options.

Return type:

GMime.FormatOptions

Gets the default format options.

GMime.iconv_locale_to_utf8(str)
Parameters:

str (str) – string in locale charset

Returns:

a new string buffer containing str converted to UTF-8.

Return type:

str

Allocates a new string buffer containing str in UTF-8.

GMime.iconv_locale_to_utf8_length(str, n)
Parameters:

  • str (str) – string in locale charset

  • n (int) – number of bytes to convert

Returns:

a new string buffer containing the first n bytes of str converted to UTF-8.

Return type:

str

Allocates a new string buffer containing the first n bytes of str converted to UTF-8.

GMime.iconv_utf8_to_locale(str)
Parameters:

str (str) – string in UTF-8 charset

Returns:

a new string buffer containing str converted to the user’s locale charset.

Return type:

str

Allocates a new string buffer containing str converted to the user’s locale charset.

GMime.iconv_utf8_to_locale_length(str, n)
Parameters:

  • str (str) – string in UTF-8 charset

  • n (int) – number of bytes to convert

Returns:

a new string buffer containing the first n bytes of str converted to the user’s locale charset.

Return type:

str

Allocates a new string buffer containing the first n bytes of str converted to the user’s locale charset.

GMime.init()

Initializes GMime.

GMime.locale_charset()
Returns:

the user’s locale charset (or iso-8859-1 by default).

Return type:

str

Gets the user’s locale charset (or iso-8859-1 by default).

GMime.locale_language()
Returns:

the user’s locale language code (or None by default).

Return type:

str or None

Gets the user’s locale language code (or None by default).

GMime.parser_options_get_default()
Returns:

the default parser options.

Return type:

GMime.ParserOptions

Gets the default parser options.

GMime.references_parse(options, text)
Parameters:
Returns:

a new GMime.References containing the parsed message ids.

Return type:

GMime.References

Decodes a list of msg-ids as in the References and/or In-Reply-To headers defined in rfc822.

GMime.shutdown()

Frees internally allocated tables created in GMime.init().

GMime.utils_best_encoding(text)
Parameters:

text (bytes) – text to encode

Returns:

a GMime.ContentEncoding that is determined to be the best encoding type for the specified block of text. (“best” in this particular case means smallest output size)

Return type:

GMime.ContentEncoding

Determines the best content encoding for the first len bytes of text.

GMime.utils_decode_8bit(options, text)
Parameters:
Returns:

a UTF-8 string representation of text.

Return type:

str

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.

GMime.utils_decode_message_id(message_id)
Parameters:

message_id (str) – string containing a message-id

Returns:

the addr-spec portion of the msg-id.

Return type:

str

Decodes a msg-id as defined by rfc822.

GMime.utils_generate_message_id(fqdn)
Parameters:

fqdn (str) – Fully qualified domain name

Returns:

a unique string in an addr-spec format suitable for use as a Message-Id.

Return type:

str

Generates a unique Message-Id.

GMime.utils_header_decode_date(str)
Parameters:

str (str) – input date string

Returns:

the GLib.DateTime representation of the date string specified by str or None on error.

Return type:

GLib.DateTime or None

Parses the rfc822 date string.

GMime.utils_header_decode_phrase(options, phrase)
Parameters:
Returns:

a newly allocated UTF-8 string representing the the decoded header.

Return type:

str

Decodes an rfc2047 encoded ‘phrase’ header.

GMime.utils_header_decode_text(options, text)
Parameters:
Returns:

a newly allocated UTF-8 string representing the the decoded header.

Return type:

str

Decodes an rfc2047 encoded ‘text’ header.

GMime.utils_header_encode_phrase(options, phrase, charset)
Parameters:
Returns:

the encoded ‘phrase’. Useful for encoding internet addresses.

Return type:

str

Encodes a ‘phrase’ header according to the rules in rfc2047.

GMime.utils_header_encode_text(options, text, charset)
Parameters:
Returns:

the encoded header. Useful for encoding headers like “Subject”.

Return type:

str

Encodes a ‘text’ header according to the rules in rfc2047.

GMime.utils_header_format_date(date)
Parameters:

date (GLib.DateTime) – a GLib.DateTime

Returns:

a valid string representation of the date.

Return type:

str

Allocates a string buffer containing the rfc822 formatted date string represented by date.

GMime.utils_header_unfold(value)
Parameters:

value (str) – raw header value

Returns:

an allocated string containing the unfolded header value.

Return type:

str

Unfolds a raw header value according to the rules in rfc822.

GMime.utils_quote_string(str)
Parameters:

str (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 ‘specials’ as defined by rfc2822.

Return type:

str

Quotes string as needed according to the rules in rfc2822.

GMime.utils_structured_header_fold(options, format, header)
Parameters:
Returns:

an allocated string containing the folded header.

Return type:

str

Folds a structured header according to the rules in rfc822.

GMime.utils_text_is_8bit(text)
Parameters:

text (bytes) – text to check for 8bit chars

Returns:

True if the text contains 8bit characters or False otherwise.

Return type:

bool

Determines if text contains 8bit characters within the first len bytes.

GMime.utils_unquote_string(str)
Parameters:

str (str) – input string

Unquotes and unescapes a string.

GMime.utils_unstructured_header_fold(options, format, header)
Parameters:
Returns:

an allocated string containing the folded header.

Return type:

str

Folds an unstructured header according to the rules in rfc822.

GMime.ydecode_step(inbuf, inlen, outbuf, state, pcrc, crc)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – ydecode state

  • pcrc (int) – part crc state

  • crc (int) – crc state

Returns:

the number of bytes decoded.

Return type:

int

Performs a ‘decode step’ on a chunk of yEncoded data of length inlen pointed to by inbuf and writes to outbuf. Assumes the =ybegin and =ypart lines have already been stripped off.

To get the crc32 value of the part, use #GMIME_YENCODE_CRC_FINAL (pcrc). If there are more parts, you should reuse crc without re-initializing. Once all parts have been decoded, you may get the combined crc32 value of all the parts using #GMIME_YENCODE_CRC_FINAL (crc).

GMime.yencode_close(inbuf, inlen, outbuf, state, pcrc, crc)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – yencode state

  • pcrc (int) – part crc state

  • crc (int) – crc state

Returns:

the number of bytes encoded.

Return type:

int

Call this function when finished encoding data with GMime.yencode_step() to flush off the remaining state.

#GMIME_YENCODE_CRC_FINAL (pcrc) will give you the crc32 of the encoded “part”. If there are more “parts” to encode, you should re-use crc when encoding the next “parts” and then use #GMIME_YENCODE_CRC_FINAL (crc) to get the combined crc32 value of all the parts.

GMime.yencode_step(inbuf, inlen, outbuf, state, pcrc, crc)
Parameters:

  • inbuf (int) – input buffer

  • inlen (int) – input buffer length

  • outbuf (int) – output buffer

  • state (int) – yencode state

  • pcrc (int) – part crc state

  • crc (int) – crc state

Returns:

the number of bytes encoded.

Return type:

int

Performs an yEncode ‘encode step’ on a chunk of raw data of length inlen pointed to by inbuf and writes to outbuf.

state should be initialized to GMime.YENCODE_STATE_INIT before beginning making the first call to this function. Subsequent calls should reuse state.

Along the same lines, pcrc and crc should be initialized to GMime.YENCODE_CRC_INIT before using.