gmime-charset: GMime 2.6 Reference Manual

## gmime-charset gmime-charset — Charset helper functions |

## Functions

void | g_mime_charset_map_init ()
void | g_mime_charset_map_shutdown ()
const char * | g_mime_locale_charset ()
const char * | g_mime_locale_language ()
const char * | g_mime_charset_language ()
const char * | g_mime_charset_canon_name ()
const char * | g_mime_charset_iconv_name ()
const char * | g_mime_charset_name ()
const char * | g_mime_charset_locale_name ()
const char * | g_mime_charset_iso_to_windows ()
void | g_mime_charset_init ()
void | g_mime_charset_step ()
const char * | g_mime_charset_best_name ()
const char * | g_mime_charset_best ()
gboolean | g_mime_charset_can_encode ()
void | g_mime_set_user_charsets ()
const char ** | g_mime_user_charsets ()

## Types and Values

struct | GMimeCharset

## Description

Charset utility functions.

## Functions

### g_mime_charset_map_init ()

    void
    g_mime_charset_map_init (void);

Initializes character set maps.

Note: `g_mime_init()` calls this routine for you.

### g_mime_charset_map_shutdown ()

    void
    g_mime_charset_map_shutdown (void);

Frees internal lookup tables created in `g_mime_charset_map_init()`.

### g_mime_locale_charset ()

    const char *
    g_mime_locale_charset (void);

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

#### Returns

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

### g_mime_locale_language ()

    const char *
    g_mime_locale_language (void);

Gets the user's locale language code (or `NULL` by default).

#### Returns

the user's locale language code (or `NULL` by default).

### g_mime_charset_language ()

    const char *
    g_mime_charset_language (const char *charset);

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

#### Parameters

charset | charset name |

#### Returns

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

### g_mime_charset_canon_name ()

    const char *
    g_mime_charset_canon_name (const char *charset);

Attempts to find a canonical charset name for `charset` .

Note: Will normally return the same value as `g_mime_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).

#### Parameters

charset | charset name |

#### Returns

a canonical charset name for `charset` .

### g_mime_charset_iconv_name ()

    const char *
    g_mime_charset_iconv_name (const char *charset);

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

#### Parameters

charset | charset name |

#### Returns

an iconv-friendly charset name for `charset` .

### g_mime_charset_name ()

    const char *
    g_mime_charset_name (const char *charset);

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

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

Note: This function is deprecated. Use `g_mime_charset_iconv_name()` instead.

#### Parameters

charset | charset name |

#### Returns

an iconv-friendly charset name for `charset` .

### g_mime_charset_locale_name ()

    const char *
    g_mime_charset_locale_name (void);

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

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

Note: This function is deprecated. Use `g_mime_locale_charset()` instead.

#### Returns

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

### g_mime_charset_iso_to_windows ()

    const char *
    g_mime_charset_iso_to_windows (const char *isocharset);

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

#### Parameters

isocharset | ISO-8859-# charset |

#### Returns

equivalent Windows charset.

### g_mime_charset_init ()

    void
    g_mime_charset_init (GMimeCharset *charset);

Initializes a charset mask structure.

#### Parameters

charset | charset mask |

### g_mime_charset_step ()

    void
    g_mime_charset_step (GMimeCharset *charset,
                         const char *inbuf,
                         size_t inlen);

Steps through the input buffer 1 unicode character (glyph) at a time (ie, not necessarily 1 byte at a time). Bitwise 'and' our `charset->mask` with the mask for each glyph. This has the effect of limiting what charsets our `charset->mask` can match.

#### Parameters

charset | charset structure |
inbuf | input text buffer (must be in UTF-8) |
inlen | input buffer length |

### g_mime_charset_best_name ()

    const char *
    g_mime_charset_best_name (GMimeCharset *charset);

Gets the best charset name based on the charset mask `charset` .

#### Parameters

charset | charset mask |

#### Returns

a pointer to a string containing the best charset name that can represent the charset mask `charset` .

### g_mime_charset_best ()

    const char *
    g_mime_charset_best (const char *inbuf,
                         size_t inlen);

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

#### Parameters

inbuf | a UTF-8 text buffer |
inlen | input buffer length |

#### Returns

the charset name best suited for the input text or `NULL` if it is US-ASCII safe.

### g_mime_charset_can_encode ()

    gboolean
    g_mime_charset_can_encode (GMimeCharset *mask,
                               const char *charset,
                               const char *text,
                               size_t len);

Check to see if the UTF-8 `text` will fit safely within `charset` .

#### Parameters

mask | a GMimeCharset mask |
charset | a charset |
text | utf-8 text to check |
len | length of `text` |

#### Returns

`TRUE` if it is safe to encode `text` into `charset` or `FALSE` otherwise.

### g_mime_set_user_charsets ()

    void
    g_mime_set_user_charsets (const char **charsets);

Set a list of charsets for GMime to use as a hint for encoding and decoding headers. The charset list should be in order of preference (e.g. most preferred first, least preferred last).

#### Parameters

charsets | an array of user-preferred charsets |

### g_mime_user_charsets ()

    const char **
    g_mime_user_charsets (void);

Get the list of user-preferred charsets set with `g_mime_set_user_charsets()`.

#### Returns

an array of user-set charsets or `NULL` if none set.

[array zero-terminated=1][transfer none]

## Types and Values

### struct GMimeCharset

    struct GMimeCharset {
    	unsigned int mask;
    	unsigned int level;
    };

State used by `g_mime_charset_best()` and `g_mime_charset_best_name()`.

#### Members

unsigned int `mask`; | charset mask |
unsigned int `level`; | charset level |