camel-mime-utils: Camel Reference Manual

## camel-mime-utils camel-mime-utils |

## Functions

time_t | camel_mktime_utc ()
void | camel_localtime_with_offset ()
CamelHeaderAddress * | camel_header_address_new ()
CamelHeaderAddress * | camel_header_address_new_name ()
CamelHeaderAddress * | camel_header_address_new_group ()
CamelHeaderAddress * | camel_header_address_ref ()
void | camel_header_address_unref ()
void | camel_header_address_set_name ()
void | camel_header_address_set_addr ()
void | camel_header_address_set_members ()
void | camel_header_address_add_member ()
void | camel_header_address_list_append_list ()
void | camel_header_address_list_append ()
void | camel_header_address_list_clear ()
CamelHeaderAddress * | camel_header_address_decode ()
CamelHeaderAddress * | camel_header_mailbox_decode ()
gchar * | camel_header_address_list_encode ()
gchar * | camel_header_address_list_format ()
struct _camel_header_param * | camel_header_param_list_decode ()
gchar * | camel_header_param ()
struct _camel_header_param * | camel_header_set_param ()
void | camel_header_param_list_format_append ()
gchar * | camel_header_param_list_format ()
void | camel_header_param_list_free ()
CamelContentType * | camel_content_type_new ()
CamelContentType * | camel_content_type_decode ()
void | camel_content_type_unref ()
CamelContentType * | camel_content_type_ref ()
const gchar * | camel_content_type_param ()
void | camel_content_type_set_param ()
gboolean | camel_content_type_is ()
gchar * | camel_content_type_format ()
gchar * | camel_content_type_simple ()
void | camel_content_type_dump ()
CamelContentDisposition * | camel_content_disposition_new ()
CamelContentDisposition * | camel_content_disposition_decode ()
CamelContentDisposition * | camel_content_disposition_ref ()
void | camel_content_disposition_unref ()
gchar * | camel_content_disposition_format ()
gboolean | camel_content_disposition_is_attachment ()
gboolean | camel_content_disposition_is_attachment_ex ()
gchar * | camel_content_transfer_encoding_decode ()
gchar * | camel_header_address_fold ()
gchar * | camel_header_fold ()
gchar * | camel_header_unfold ()
gchar * | camel_headers_dup_mailing_list ()
gchar * | camel_header_token_decode ()
gint | camel_header_decode_int ()
gchar * | camel_header_decode_string ()
gchar * | camel_header_encode_string ()
gchar * | camel_header_format_ctext ()
gchar * | camel_header_encode_phrase ()
time_t | camel_header_decode_date ()
gchar * | camel_header_format_date ()
gchar * | camel_header_msgid_decode ()
gchar * | camel_header_contentid_decode ()
gchar * | camel_header_msgid_generate ()
GSList * | camel_header_references_decode ()
gchar * | camel_header_location_decode ()
GSList * | camel_header_newsgroups_decode ()
const gchar * | camel_transfer_encoding_to_string ()
CamelTransferEncoding | camel_transfer_encoding_from_string ()
void | camel_header_mime_decode ()
gsize | camel_uudecode_step ()
gsize | camel_uuencode_step ()
gsize | camel_uuencode_close ()
gsize | camel_quoted_decode_step ()
gsize | camel_quoted_encode_step ()
gsize | camel_quoted_encode_close ()
#define | camel_mime_is_ctrl()
#define | camel_mime_is_lwsp()
#define | camel_mime_is_tspecial()
#define | camel_mime_is_type()
#define | camel_mime_is_ttoken()
#define | camel_mime_is_atom()
#define | camel_mime_is_dtext()
#define | camel_mime_is_fieldname()
#define | camel_mime_is_qpsafe()
#define | camel_mime_is_especial()
#define | camel_mime_is_psafe()
#define | camel_mime_is_attrchar()

## Types and Values

#define | CAMEL_FOLD_SIZE
#define | CAMEL_FOLD_MAX_SIZE
enum | CamelUUDecodeState
#define | CAMEL_UUDECODE_STATE_MASK
| CamelHeaderParam
enum | CamelHeaderAddressType

## Description

## Functions

### camel_mktime_utc ()

    time_t
    camel_mktime_utc (struct tm *tm);

Like mktime(3), but assumes UTC instead of local timezone.

#### Parameters

tm | the tm to convert to a calendar time representation |

#### Returns

the calendar time representation of `tm`

Since: 3.4

### camel_localtime_with_offset ()

    void
    camel_localtime_with_offset (time_t tt,
                                 struct tm *tm,
                                 gint *offset);

Converts the calendar time representation `tt` to a broken-down time representation, stored in `tm` , and provides the offset in seconds from UTC time, stored in `offset` .

#### Parameters

tt | the time_t to convert |
tm | the tm to store the result in |
offset | the gint to store the offset in |

### camel_header_address_new ()

    CamelHeaderAddress *
    camel_header_address_new (void);

### camel_header_address_new_name ()

    CamelHeaderAddress *
    camel_header_address_new_name (const gchar *name,
                                   const gchar *addr);

### camel_header_address_new_group ()

    CamelHeaderAddress *
    camel_header_address_new_group (const gchar *name);

### camel_header_address_ref ()

    CamelHeaderAddress *
    camel_header_address_ref (CamelHeaderAddress *addrlist);

### camel_header_address_unref ()

    void
    camel_header_address_unref (CamelHeaderAddress *addrlist);

### camel_header_address_set_name ()

    void
    camel_header_address_set_name (CamelHeaderAddress *addrlist,
                                   const gchar *name);

### camel_header_address_set_addr ()

    void
    camel_header_address_set_addr (CamelHeaderAddress *addrlist,
                                   const gchar *addr);

### camel_header_address_set_members ()

    void
    camel_header_address_set_members (CamelHeaderAddress *addrlist,
                                      CamelHeaderAddress *group);

TODO: Document me.

#### Parameters

addrlist | a CamelHeaderAddress object |
group | a NULL-terminated list of CamelHeaderAddress. | [array zero-terminated=1]

### camel_header_address_add_member ()

    void
    camel_header_address_add_member (CamelHeaderAddress *addrlist,
                                     CamelHeaderAddress *member);

### camel_header_address_list_append_list ()

    void
    camel_header_address_list_append_list (CamelHeaderAddress **addrlistp,
                                           CamelHeaderAddress **addrs);

TODO: Document me.

#### Parameters

addrlistp | a NULL-terminated list of CamelHeaderAddress objects. | [array zero-terminated=1]
addrs | a NULL-terminated list of CamelHeaderAddress to add. | [array zero-terminated=1]

### camel_header_address_list_append ()

    void
    camel_header_address_list_append (CamelHeaderAddress **addrlistp,
                                      CamelHeaderAddress *addr);

TODO: Document me.

#### Parameters

addrlistp | a NULL-terminated list of CamelHeaderAddress objects. | [array zero-terminated=1]
addr | the CamelHeaderAddress to add |

### camel_header_address_list_clear ()

    void
    camel_header_address_list_clear (CamelHeaderAddress **addrlistp);

TODO: Document me.

#### Parameters

addrlistp | a NULL-terminated list of CamelHeaderAddress objects. | [array zero-terminated=1]

### camel_header_address_decode ()

    CamelHeaderAddress *
    camel_header_address_decode (const gchar *in,
                                 const gchar *charset);

### camel_header_mailbox_decode ()

    CamelHeaderAddress *
    camel_header_mailbox_decode (const gchar *in,
                                 const gchar *charset);

### camel_header_address_list_encode ()

    gchar *
    camel_header_address_list_encode (CamelHeaderAddress *addrlist);

TODO: Document me.

#### Parameters

addrlist | a NULL-terminated list of CamelHeaderAddress objects. | [array zero-terminated=1]

### camel_header_address_list_format ()

    gchar *
    camel_header_address_list_format (CamelHeaderAddress *addrlist);

TODO: Document me.

#### Parameters

addrlist | a NULL-terminated list of CamelHeaderAddress objects. | [array zero-terminated=1]

### camel_header_param_list_decode ()

    struct _camel_header_param *
    camel_header_param_list_decode (const gchar *in);

#### Parameters

in | a header param value to decode. | [nullable]

#### Returns

Decode list of parameters. Free with `camel_header_param_list_free()` when done with it.

[nullable][transfer full]

### camel_header_param ()

    gchar *
    camel_header_param (struct _camel_header_param *params,
                        const gchar *name);

Searches `params` for a param named `name` and gets the value.

#### Parameters

params | parameters |
name | name of param to find |

#### Returns

the value of the `name` param

### camel_header_set_param ()

    struct _camel_header_param *
    camel_header_set_param (struct _camel_header_param **paramsp,
                            const gchar *name,
                            const gchar *value);

Set a parameter in the list.

#### Parameters

paramsp | poinetr to a list of params |
name | name of param to set |
value | value to set |

#### Returns

the set param.

[transfer none]

### camel_header_param_list_format_append ()

    void
    camel_header_param_list_format_append (GString *out,
                                           struct _camel_header_param *params);

### camel_header_param_list_format ()

    gchar *
    camel_header_param_list_format (struct _camel_header_param *params);

### camel_header_param_list_free ()

    void
    camel_header_param_list_free (struct _camel_header_param *params);

Free the list of params.

#### Parameters

params | a list of params |

### camel_content_type_new ()

    CamelContentType *
    camel_content_type_new (const gchar *type,
                            const gchar *subtype);

Create a new CamelContentType.

#### Parameters

type | the major type of the new content-type |
subtype | the subtype |

#### Returns

the new CamelContentType

### camel_content_type_decode ()

    CamelContentType *
    camel_content_type_decode (const gchar *in);

### camel_content_type_unref ()

    void
    camel_content_type_unref (CamelContentType *content_type);

Unrefs, and potentially frees, the content type.

#### Parameters

content_type | a CamelContentType |

### camel_content_type_ref ()

    CamelContentType *
    camel_content_type_ref (CamelContentType *content_type);

Refs the content type.

#### Parameters

content_type | a CamelContentType |

### camel_content_type_param ()

    const gchar *
    camel_content_type_param (CamelContentType *content_type,
                              const gchar *name);

Searches the params on s CamelContentType for a param named `name` and gets the value.

#### Parameters

content_type | a CamelContentType |
name | name of param to find |

#### Returns

the value of the `name` param

### camel_content_type_set_param ()

    void
    camel_content_type_set_param (CamelContentType *content_type,
                                  const gchar *name,
                                  const gchar *value);

Set a parameter on `content_type` .

#### Parameters

content_type | a CamelContentType |
name | name of param to set |
value | value of param to set |

### camel_content_type_is ()

    gboolean
    camel_content_type_is (const CamelContentType *content_type,
                           const gchar *type,
                           const gchar *subtype);

The subtype of "*" will match any subtype. If `ct` is `NULL`, then it will match the type "text/plain".

#### Parameters

content_type | A content type specifier, or `NULL`. |
type | A type to check against. |
subtype | A subtype to check against, or "*" to match any subtype. |

#### Returns

`TRUE` if the content type `ct` is of type `type` /`subtype` or `FALSE` otherwise

### camel_content_type_format ()

    gchar *
    camel_content_type_format (CamelContentType *content_type);

### camel_content_type_simple ()

    gchar *
    camel_content_type_simple (CamelContentType *content_type);

### camel_content_type_dump ()

    void
    camel_content_type_dump (CamelContentType *content_type);

### camel_content_disposition_new ()

    CamelContentDisposition *
    camel_content_disposition_new (void);

### camel_content_disposition_decode ()

    CamelContentDisposition *
    camel_content_disposition_decode (const gchar *in);

### camel_content_disposition_ref ()

    CamelContentDisposition *
    camel_content_disposition_ref (CamelContentDisposition *disposition);

### camel_content_disposition_unref ()

    void
    camel_content_disposition_unref (CamelContentDisposition *disposition);

### camel_content_disposition_format ()

    gchar *
    camel_content_disposition_format (CamelContentDisposition *disposition);

### camel_content_disposition_is_attachment ()

    gboolean
    camel_content_disposition_is_attachment
                                   (const CamelContentDisposition *disposition,
                                    const CamelContentType *content_type);

### camel_content_disposition_is_attachment_ex ()

    gboolean
    camel_content_disposition_is_attachment_ex
                                   (const CamelContentDisposition *disposition,
                                    const CamelContentType *content_type,
                                    const CamelContentType *parent_content_type);

### camel_content_transfer_encoding_decode ()

    gchar *
    camel_content_transfer_encoding_decode
                                   (const gchar *in);

### camel_header_address_fold ()

    gchar *
    camel_header_address_fold (const gchar *in,
                               gsize headerlen);

### camel_header_fold ()

    gchar *
    camel_header_fold (const gchar *in,
                       gsize headerlen);

### camel_header_unfold ()

    gchar *
    camel_header_unfold (const gchar *in);

### camel_headers_dup_mailing_list ()

    gchar *
    camel_headers_dup_mailing_list (const CamelNameValueArray *headers);

Searches for a mailing list information among known headers and returns a newly allocated string with its value.

#### Parameters

headers | a CamelNameValueArray with headers |

#### Returns

The mailing list header, or `NULL`, if none is found.

[nullable][transfer full]

### camel_header_token_decode ()

    gchar *
    camel_header_token_decode (const gchar *in);

Gets the first token in the string according to the rules of rfc0822.

#### Parameters

in | input string |

#### Returns

a new string containing the first token in `in`

### camel_header_decode_int ()

    gint
    camel_header_decode_int (const gchar **in);

Extracts an integer token from `in` and updates the pointer to point to after the end of the integer token (sort of like strtol).

#### Parameters

in | pointer to input string |

#### Returns

the gint value

### camel_header_decode_string ()

    gchar *
    camel_header_decode_string (const gchar *in,
                                const gchar *default_charset);

Decodes rfc2047 encoded-word tokens

#### Parameters

in | input header value string |
default_charset | default charset to use if improperly encoded |

#### Returns

a string containing the UTF-8 version of the decoded header value

### camel_header_encode_string ()

    gchar *
    camel_header_encode_string (const guchar *in);

Encodes a 'text' header according to the rules of rfc2047.

#### Parameters

in | input string |

#### Returns

the rfc2047 encoded header

### camel_header_format_ctext ()

    gchar *
    camel_header_format_ctext (const gchar *in,
                               const gchar *default_charset);

Decodes a header which contains rfc2047 encoded-word tokens that may or may not be within a comment.

#### Parameters

in | input header value string |
default_charset | default charset to use if improperly encoded |

#### Returns

a string containing the UTF-8 version of the decoded header value

### camel_header_encode_phrase ()

    gchar *
    camel_header_encode_phrase (const guchar *in);

Encodes a 'phrase' header according to the rules in rfc2047.

#### Parameters

in | header to encode |

#### Returns

the encoded 'phrase'

### camel_header_decode_date ()

    time_t
    camel_header_decode_date (const gchar *str,
                              gint *tz_offset);

Decodes the rfc822 date string and saves the GMT offset into `tz_offset` if non-NULL.

#### Parameters

str | input date string |
tz_offset | timezone offset |

#### Returns

the time_t representation of the date string specified by `str` or (time_t) 0 on error. If `tz_offset` is non-NULL, the value of the timezone offset will be stored.

### camel_header_format_date ()

    gchar *
    camel_header_format_date (time_t date,
                              gint tz_offset);

Allocates a string buffer containing the rfc822 formatted date string represented by `time` and `tz_offset` .

#### Parameters

date | time_t date representation |
tz_offset | Timezone offset |

#### Returns

a valid string representation of the date.

### camel_header_msgid_decode ()

    gchar *
    camel_header_msgid_decode (const gchar *in);

Extract a message-id token from `in` .

#### Parameters

in | input string |

#### Returns

the msg-id

### camel_header_contentid_decode ()

    gchar *
    camel_header_contentid_decode (const gchar *in);

Extract a content-id from `in` .

#### Parameters

in | input string |

#### Returns

the extracted content-id

### camel_header_msgid_generate ()

    gchar *
    camel_header_msgid_generate (const gchar *domain);

Either the `domain` is used, or the user's local hostname, in case it's NULL or empty.

#### Parameters

domain | domain to use (like "example.com") for the ID suffix; can be NULL |

#### Returns

Unique message ID.

### camel_header_references_decode ()

    GSList *
    camel_header_references_decode (const gchar *in);

Generate a list of references, from most recent up.

#### Parameters

in | References header value |

#### Returns

a list of references decoedd from `in` .

[element-type utf8][transfer full]

### camel_header_location_decode ()

    gchar *
    camel_header_location_decode (const gchar *in);

### camel_header_newsgroups_decode ()

    GSList *
    camel_header_newsgroups_decode (const gchar *in);

#### Returns

.

[element-type utf8][transfer full]

### camel_transfer_encoding_to_string ()

    const gchar *
    camel_transfer_encoding_to_string (CamelTransferEncoding encoding);

### camel_transfer_encoding_from_string ()

    CamelTransferEncoding
    camel_transfer_encoding_from_string (const gchar *string);

### camel_header_mime_decode ()

    void
    camel_header_mime_decode (const gchar *in,
                              gint *maj,
                              gint *min);

### camel_uudecode_step ()

    gsize
    camel_uudecode_step (guchar *in,
                         gsize inlen,
                         guchar *out,
                         gint *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

in | input stream. | [array length=inlen]
inlen | max length of data to decode |
out | output stream. | [inout][array]
state | holds the number of bits that are stored in `save` . | [inout]
save | leftover bits that have not yet been decoded. | [inout][array length=state]

#### Returns

the number of bytes decoded

### camel_uuencode_step ()

    gsize
    camel_uuencode_step (guchar *in,
                         gsize len,
                         guchar *out,
                         guchar *uubuf,
                         gint *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

in | input stream. | [array length=len]
len | input stream length |
out | output stream. | [inout][array]
uubuf | temporary buffer of 60 bytes. | [inout][array fixed-size=60]
state | holds the number of bits that are stored in `save` . | [inout]
save | leftover bits that have not yet been encoded. | [inout][array length=state]

#### Returns

the number of bytes encoded

### camel_uuencode_close ()

    gsize
    camel_uuencode_close (guchar *in,
                          gsize len,
                          guchar *out,
                          guchar *uubuf,
                          gint *state,
                          guint32 *save);

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

#### Parameters

in | input stream. | [array length=len]
len | input stream length |
out | output stream. | [inout][array]
uubuf | temporary buffer of 60 bytes. | [inout][array fixed-size=60]
state | holds the number of bits that are stored in `save` . | [inout]
save | leftover bits that have not yet been encoded. | [inout][array length=state]

#### Returns

the number of bytes encoded

### camel_quoted_decode_step ()

    gsize
    camel_quoted_decode_step (guchar *in,
                              gsize len,
                              guchar *out,
                              gint *savestate,
                              gint *saveme);

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

#### Parameters

in | input stream. | [array length=len]
len | max length of data to decode |
out | output stream. | [inout][array]
savestate | holds the number of bits that are stored in `saveme` . | [inout]
saveme | leftover bits that have not yet been decoded. | [inout][array length=savestate]

#### Returns

the number of bytes decoded

### camel_quoted_encode_step ()

    gsize
    camel_quoted_encode_step (guchar *in,
                              gsize len,
                              guchar *out,
                              gint *state,
                              gint *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

in | input stream. | [array length=len]
len | length of the input |
out | output string. | [inout][array]
state | holds the number of bits that are stored in `save` . | [inout]
save | leftover bits that have not yet been encoded. | [inout][array length=state]

#### Returns

the number of bytes encoded

### camel_quoted_encode_close ()

    gsize
    camel_quoted_encode_close (guchar *in,
                               gsize len,
                               guchar *out,
                               gint *state,
                               gint *save);

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

#### Parameters

in | input stream. | [array length=len]
len | length of the input |
out | output string. | [inout][array]
state | holds the number of bits that are stored in `save` . | [inout]
save | leftover bits that have not yet been encoded. | [inout][array length=state]

#### Returns

the number of bytes encoded

### camel_mime_is_ctrl()

    #define camel_mime_is_ctrl(x) ((camel_mime_special_table[(guchar)(x)] & CAMEL_MIME_IS_CTRL) != 0)

### camel_mime_is_lwsp()

    #define camel_mime_is_lwsp(x) ((camel_mime_special_table[(guchar)(x)] & CAMEL_MIME_IS_LWSP) != 0)

### camel_mime_is_tspecial()

    #define camel_mime_is_tspecial(x) ((camel_mime_special_table[(guchar)(x)] & CAMEL_MIME_IS_TSPECIAL) != 0)

### camel_mime_is_type()

    #define camel_mime_is_type(x, t) ((camel_mime_special_table[(guchar)(x)] & (t)) != 0)

### camel_mime_is_ttoken()

    #define camel_mime_is_ttoken(x) ((camel_mime_special_table[(guchar)(x)] & (CAMEL_MIME_IS_TSPECIAL|CAMEL_MIME_IS_LWSP|CAMEL_MIME_IS_CTRL)) == 0)

### camel_mime_is_atom()

    #define camel_mime_is_atom(x) ((camel_mime_special_table[(guchar)(x)] & (CAMEL_MIME_IS_SPECIAL|CAMEL_MIME_IS_SPACE|CAMEL_MIME_IS_CTRL)) == 0)

### camel_mime_is_dtext()

    #define camel_mime_is_dtext(x) ((camel_mime_special_table[(guchar)(x)] & CAMEL_MIME_IS_DSPECIAL) == 0)

### camel_mime_is_fieldname()

    #define camel_mime_is_fieldname(x) ((camel_mime_special_table[(guchar)(x)] & (CAMEL_MIME_IS_CTRL|CAMEL_MIME_IS_SPACE)) == 0)

### camel_mime_is_qpsafe()

    #define camel_mime_is_qpsafe(x) ((camel_mime_special_table[(guchar)(x)] & CAMEL_MIME_IS_QPSAFE) != 0)

### camel_mime_is_especial()

    #define camel_mime_is_especial(x) ((camel_mime_special_table[(guchar)(x)] & CAMEL_MIME_IS_ESPECIAL) != 0)

### camel_mime_is_psafe()

    #define camel_mime_is_psafe(x) ((camel_mime_special_table[(guchar)(x)] & CAMEL_MIME_IS_PSAFE) != 0)

### camel_mime_is_attrchar()

    #define camel_mime_is_attrchar(x) ((camel_mime_special_table[(guchar)(x)] & CAMEL_MIME_IS_ATTRCHAR) != 0)

## Types and Values

### CAMEL_FOLD_SIZE

    #define CAMEL_FOLD_SIZE (77)

### CAMEL_FOLD_MAX_SIZE

    #define CAMEL_FOLD_MAX_SIZE (998)

### enum CamelUUDecodeState

#### Members

CAMEL_UUDECODE_STATE_INIT |  |
CAMEL_UUDECODE_STATE_BEGIN |  |
CAMEL_UUDECODE_STATE_END |  |

### CAMEL_UUDECODE_STATE_MASK

    #define CAMEL_UUDECODE_STATE_MASK   (CAMEL_UUDECODE_STATE_BEGIN | CAMEL_UUDECODE_STATE_END)

### CamelHeaderParam

    typedef struct {
    	struct _camel_header_param *next;
    	gchar *name;
    	gchar *value;
    } CamelHeaderParam;

### enum CamelHeaderAddressType

#### Members

CAMEL_HEADER_ADDRESS_NONE |  |
CAMEL_HEADER_ADDRESS_NAME |  |
CAMEL_HEADER_ADDRESS_GROUP |  |