Functions

  binding_bind_property (source, source_property, target, target_property, flags)
  binding_bind_property_full (source, source_property, target, target_property, flags, transform_to, transform_from)
  charset_best (in_)
  charset_iso_to_windows (isocharset)
  cipher_can_load_photos ()
  cipher_canonical_to_stream (part, flags, ostream, cancellable)
  cipher_certinfo_get_property (cert_info, name)
  cipher_certinfo_set_property (cert_info, name, value, value_free, value_clone)
  content_disposition_decode (in_)
  content_transfer_encoding_decode (in_)
  content_type_decode (in_)
  debug (mode)
  debug_demangle_backtrace (bt)
  debug_end ()
  debug_get_backtrace ()
  debug_get_raw_backtrace ()
  debug_init ()
  debug_ref_unref_dump_backtraces ()
  debug_ref_unref_push_backtrace (backtrace, object_ref_count)
  debug_ref_unref_push_backtrace_for_object (_object)
  debug_start (mode)
  enriched_to_html (in_, flags)
  error_quark ()
  file_util_decode_fixed_int32 (in_, dest)
  file_util_decode_fixed_string (in_, str, len)
  file_util_decode_gsize (in_, dest)
  file_util_decode_off_t (in_, dest)
  file_util_decode_string (in_, str)
  file_util_decode_time_t (in_, dest)
  file_util_decode_uint32 (in_, dest)
  file_util_encode_fixed_int32 (out, value)
  file_util_encode_fixed_string (out, str, len)
  file_util_encode_gsize (out, value)
  file_util_encode_off_t (out, value)
  file_util_encode_string (out, str)
  file_util_encode_time_t (out, value)
  file_util_encode_uint32 (out, value)
  file_util_safe_filename (name)
  file_util_savename (filename)
  folder_info_build (folders, namespace_, separator, short_names)
  freeaddrinfo (host)
  getaddrinfo (name, service, hints, cancellable)
  header_address_decode (in_, charset)
  header_address_fold (in_, headerlen)
  header_address_list_append (addrlistp, addr)
  header_address_list_append_list (addrlistp, addrs)
  header_address_list_clear (addrlistp)
  header_address_list_encode (addrlist)
  header_address_list_format (addrlist)
  header_contentid_decode (in_)
  header_decode_date (str, tz_offset)
  header_decode_int (in_)
  header_decode_string (in_, default_charset)
  header_encode_phrase (in_)
  header_encode_string (in_)
  header_fold (in_, headerlen)
  header_format_ctext (in_, default_charset)
  header_format_date (date, tz_offset)
  header_location_decode (in_)
  header_mailbox_decode (in_, charset)
  header_mime_decode (in_, maj, min)
  header_msgid_decode (in_)
  header_msgid_generate (domain)
  header_newsgroups_decode (in_)
  header_param (params, name)
  header_param_list_decode (in_)
  header_param_list_format (params)
  header_param_list_format_append (out, params)
  header_param_list_free (params)
  header_references_decode (in_)
  header_set_param (paramsp, name, value)
  header_token_decode (in_)
  header_unfold (in_)
  headers_dup_mailing_list (headers)
  host_idna_to_ascii (host)
  iconv_charset_language (charset)
  iconv_charset_name (charset)
  iconv_locale_charset ()
  iconv_locale_language ()
  init (certdb_dir, nss_init)
  localtime_with_offset (tt, tm, offset)
  lock_dot (path)
  lock_fcntl (fd, type)
  lock_flock (fd, type)
  lock_folder (path, fd, type)
  lock_helper_lock (path)
  lock_helper_unlock (lockid)
  mktime_utc (tm)
  movemail (source, dest)
  pointer_tracker_dump ()
  pointer_tracker_track_with_info (ptr, info)
  pointer_tracker_untrack (ptr)
  provider_get (protocol)
  provider_init ()
  provider_list (load)
  provider_load (path)
  provider_module_init ()
  pstring_add (string, own)
  pstring_contains (string)
  pstring_dump_stat ()
  pstring_free (string)
  pstring_peek (string)
  pstring_strdup (string)
  quoted_decode_step (in_, out, saveme)
  quoted_encode_close (in_, out, save)
  quoted_encode_step (in_, out, save)
  read (fd, buf, n, cancellable)
  search_camel_header_soundex (header, match)
  search_get_all_headers_decoded (message)
  search_get_default_charset_from_headers (headers)
  search_get_default_charset_from_message (message)
  search_get_header_decoded (header_name, header_value, default_charset)
  search_get_headers_decoded (headers, default_charset)
  search_header_is_address (header_name)
  search_header_match (value, match, how, type, default_charset)
  search_words_free (words)
  search_words_simple (words)
  search_words_split (in_)
  shutdown ()
  store_info_name (summary, info)
  store_info_path (summary, info)
  store_info_set_string (summary, info, type, value)
  strcase_equal (a, b)
  strcase_hash (v)
  strdown (str)
  strstrcase (haystack, needle)
  system_flag (name)
  system_flag_get (flags, name)
  text_to_html (in_, flags, color)
  time_value_apply (src_time, unit, value)
  transfer_encoding_from_string (string)
  transfer_encoding_to_string (encoding)
  ucs2_utf8 (ptr)
  uid_cache_free_uids (uids)
  unlock_dot (path)
  unlock_fcntl (fd)
  unlock_flock (fd)
  unlock_folder (path, fd)
  url_addrspec_end (in_, pos, inend, match)
  url_addrspec_start (in_, pos, inend, match)
  url_decode (part)
  url_decode_path (path)
  url_encode (part, escape_extra)
  url_file_end (in_, pos, inend, match)
  url_file_start (in_, pos, inend, match)
  url_web_end (in_, pos, inend, match)
  url_web_start (in_, pos, inend, match)
  ustrstrcase (haystack, needle)
  utf7_utf8 (ptr)
  utf8_getc (ptr)
  utf8_getc_limit (ptr, end)
  utf8_make_valid (text)
  utf8_make_valid_len (text, text_len)
  utf8_putc (ptr, c)
  utf8_ucs2 (ptr)
  utf8_utf7 (ptr)
  util_bdata_get_number (bdata_ptr, default_value)
  util_bdata_get_string (bdata_ptr, default_value)
  util_bdata_put_number (bdata_str, value)
  util_bdata_put_string (bdata_str, value)
  uudecode_step (in_, out, save)
  uuencode_close (in_, out, uubuf, save)
  uuencode_step (in_, out, uubuf, save)
  write (fd, buf, n, cancellable)
  ydecode_step (in_)
  yencode_close (in_)
  yencode_step (in_)

Details

Camel.binding_bind_property(source, source_property, target, target_property, flags)
Parameters:
Return type:

GObject.Binding

Thread safe variant of GObject.Object.bind_property(). See its documentation for more information on arguments and return value.

New in version 3.16.

Camel.binding_bind_property_full(source, source_property, target, target_property, flags, transform_to, transform_from)
Parameters:
Returns:

the GObject.Binding instance representing the binding between the two GObject.Object instances. The binding is released whenever the GObject.Binding reference count reaches zero.
Return type:

GObject.Binding

Thread safe variant of GObject.Object.bind_property_full(). See its documentation for more information on arguments and return value.

New in version 3.16.

Camel.charset_best(in_)
Parameters:in ([int]) – input text
Returns:the minimum charset or None for US_ASCII.
Return type:str or None

Finds the minimum charset for this string None means US-ASCII.

Camel.charset_iso_to_windows(isocharset)
Parameters:isocharset (str) – a canonicalised ISO charset
Returns:the equivalent Windows charset.
Return type:str
Camel.cipher_can_load_photos()
Returns:Whether ciphers can load photos, as being setup by the user.
Return type:bool

New in version 3.22.

Camel.cipher_canonical_to_stream(part, flags, ostream, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

-1 on error;
Return type:

int

Writes a Camel.part to a stream in a canonicalised format, suitable for signing/encrypting.

The transfer encoding paramaters for the Camel.part may be changed by this function.

Camel.cipher_certinfo_get_property(cert_info, name)
Parameters:
Returns:

Value of a named property of the cert_info, or None when no such property exists. The returned value is owned by the cert_info and is valid until the cert_info is freed.
Return type:

object or None

Gets a named property name value for the given cert_info.

New in version 3.22.

Camel.cipher_certinfo_set_property(cert_info, name, value, value_free, value_clone)
Parameters:

Sets a named property name value value for the given cert_info. If the value is None, then the property is removed. With a non-None value also value_free and value_clone functions cannot be None.

New in version 3.22.

Camel.content_disposition_decode(in_)
Parameters:in (str) –
Return type:Camel.ContentDisposition
Camel.content_transfer_encoding_decode(in_)
Parameters:in (str) –
Return type:str
Camel.content_type_decode(in_)
Parameters:in (str) –
Return type:Camel.ContentType
Camel.debug(mode)
Parameters:mode (str) – string name of the mode to check for
Returns:Whether the debug mode is activated
Return type:bool

Check to see if a debug mode is activated. mode takes one of two forms, a fully qualified ‘module:target’, or a wildcard ‘module’ name. It returns a boolean to indicate if the module or module and target is currently activated for debug output.

Camel.debug_demangle_backtrace(bt)
Parameters:bt (GLib.String or None) – a GLib.String with a raw backtrace, or None
Returns:a GLib.String with a raw backtrace, or None
Return type:bt: GLib.String or None

Demangles bt, possibly got from Camel.debug_get_raw_backtrace(), by replacing addresses with actual function calls and eventually line numbers, if available. It modifies lines of bt, but skips those it cannot parse.

Note: Getting backtraces only works if the library was configured with –enable-backtraces.

See also Camel.debug_get_raw_backtrace()

New in version 3.30.

Camel.debug_end()

Call this when you’re done with your debug output. If and only if you called Camel.debug_start, and if it returns True.

Camel.debug_get_backtrace()
Returns:Current backtrace, or None, if cannot determine it.

Note: Getting backtraces only works if the library was configured with –enable-backtraces.

See also Camel.debug_get_raw_backtrace()
Return type:GLib.String

Gets current backtrace leading to this function call and demangles it.

New in version 3.12.

Camel.debug_get_raw_backtrace()
Returns:Current raw backtrace, or None, if cannot determine it.

Note: Getting backtraces only works if the library was configured with –enable-backtraces.

See also Camel.debug_get_backtrace()
Return type:GLib.String

Gets current raw backtrace leading to this function call. This is quicker than Camel.debug_get_backtrace(), because it doesn’t demangle the backtrace. To demangle it (replace addresses with actual function calls and eventually line numbers, if available) call Camel.debug_demangle_backtrace().

New in version 3.30.

Camel.debug_init()

Init camel debug.

CAMEL_DEBUG is set to a comma separated list of modules to debug. The modules can contain module-specific specifiers after a ‘:’, or just act as a wildcard for the module or even specifier. e.g. ‘imap’ for imap debug, or ‘imap:folder’ for imap folder debug. Additionaly, ‘:folder’ can be used for a wildcard for any folder operations.

Camel.debug_ref_unref_dump_backtraces()

Prints current backtraces stored with Camel.debug_ref_unref_push_backtrace() or with Camel.debug_ref_unref_push_backtrace_for_object().

It’s usually not needed to use this function, as the left backtraces, if any, are printed at the end of the application.

New in version 3.20.

Camel.debug_ref_unref_push_backtrace(backtrace, object_ref_count)
Parameters:

Adds this backtrace into the set of backtraces related to some object reference counting issues debugging. This is usually called inside GObject.Object.ref() and GObject.Object.unref(). If the backtrace corresponds to a GObject.Object.unref() call, and a corresponding GObject.Object.ref() backtrace is found in the current list, then the previous backtrace is removed and this one is skipped.

Any left backtraces in the list are printed at the application end.

A convenient function Camel.debug_ref_unref_push_backtrace_for_object() is provided too.

New in version 3.20.

Camel.debug_ref_unref_push_backtrace_for_object(_object)
Parameters:_object (object or None) – a GObject.Object, for which add the backtrace

Gets current backtrace of this call and adds it to the list of backtraces with Camel.debug_ref_unref_push_backtrace().

Usual usage would be, once GNOME bug 758358 is applied to the GLib sources, or a patched GLib is used, to call this function in an object init() function, like this:

static void my_object_init (MyObject *obj) { Camel.debug_ref_unref_push_backtrace_for_object (obj); g_track_object_ref_unref (obj, (GLib.Func) Camel.debug_ref_unref_push_backtrace_for_object, None); }

Note that the g_track_object_ref_unref() can track only one pointer, thus make sure you track the right one (add some logic if multiple objects are created at once).

New in version 3.20.

Camel.debug_start(mode)
Parameters:mode (str) – string name of the mode to start the debug for
Returns:True if mode is set, and in which case, you must call Camel.debug_end() when finished any screen output.
Return type:bool

Start debug output for a given mode, used to make sure debug output is output atomically and not interspersed with unrelated stuff.

Camel.enriched_to_html(in_, flags)
Parameters:
  • in (str) – input textual string
  • flags (int) – flags specifying filter behaviour
Returns:

a newly allocated string containing the enriched or richtext version of in.
Return type:

str

Convert in from text/plain into text/enriched or text/richtext based on flags.

Camel.error_quark()
Return type:int
Camel.file_util_decode_fixed_int32(in_, dest)
Parameters:
  • in (object or None) – file to read from
  • dest (int) – pointer to a variable to store the value in
Returns:

0 on success, -1 on error.
Return type:

int

Retrieve a gint32.

Camel.file_util_decode_fixed_string(in_, str, len)
Parameters:
  • in (object or None) – file to read from
  • str (str) – pointer to a variable to store the value in
  • len (int) – total-len to decode.
Returns:

0 on success, -1 on error.
Return type:

int

Decode a normal string from the input file.

Camel.file_util_decode_gsize(in_, dest)
Parameters:
  • in (object or None) – file to read from
  • dest (int) – pointer to a variable to put the value in
Returns:

0 on success, -1 on failure.
Return type:

int

Decode an gsize type.

Camel.file_util_decode_off_t(in_, dest)
Parameters:
  • in (object or None) – file to read from
  • dest (int) – pointer to a variable to put the value in
Returns:

0 on success, -1 on failure.
Return type:

int

Decode an off_t type.

Camel.file_util_decode_string(in_, str)
Parameters:
  • in (object or None) – file to read from
  • str (str) – pointer to a variable to store the value in
Returns:

0 on success, -1 on error.
Return type:

int

Decode a normal string from the input file.

Camel.file_util_decode_time_t(in_, dest)
Parameters:
  • in (object or None) – file to read from
  • dest (int) – pointer to a variable to store the value in
Returns:

0 on success, -1 on error.
Return type:

int

Decode a time_t value.

Camel.file_util_decode_uint32(in_, dest)
Parameters:
  • in (object or None) – file to read from
  • dest (int) – pointer to a variable to store the value in
Returns:

0 on success, -1 on error. @*dest will contain the decoded value.
Return type:

int

Retrieve an encoded uint32 from a file.

Camel.file_util_encode_fixed_int32(out, value)
Parameters:
  • out (object or None) – file to output to
  • value (int) – value to output
Returns:

0 on success, -1 on error.
Return type:

int

Encode a gint32, performing no compression, but converting to network order.

Camel.file_util_encode_fixed_string(out, str, len)
Parameters:
  • out (object or None) – file to output to
  • str (str) – value to output
  • len (int) – total-len of str to store
Returns:

0 on success, -1 on error.
Return type:

int

Encode a normal string and save it in the output file. Unlike camel_file_util_encode_string, it pads the str with “None” bytes, if len is > strlen(str)

Camel.file_util_encode_gsize(out, value)
Parameters:
  • out (object or None) – file to output to
  • value (int) – value to output
Returns:

0 on success, -1 on error.
Return type:

int

Encode an gsize type.

Camel.file_util_encode_off_t(out, value)
Parameters:
  • out (object or None) – file to output to
  • value (int) – value to output
Returns:

0 on success, -1 on error.
Return type:

int

Encode an off_t type.

Camel.file_util_encode_string(out, str)
Parameters:
  • out (object or None) – file to output to
  • str (str) – value to output
Returns:

0 on success, -1 on error.
Return type:

int

Encode a normal string and save it in the output file.

Camel.file_util_encode_time_t(out, value)
Parameters:
  • out (object or None) – file to output to
  • value (int) – value to output
Returns:

0 on success, -1 on error.
Return type:

int

Encode a time_t value to the file.

Camel.file_util_encode_uint32(out, value)
Parameters:
  • out (object or None) – file to output to
  • value (int) – value to output
Returns:

0 on success, -1 on error.
Return type:

int

Utility function to save an uint32 to a file.

Camel.file_util_safe_filename(name)
Parameters:name (str) – string to ‘flattened’ into a safe filename
Returns:a safe filename string.
Return type:str

‘Flattens’ name into a safe filename string by hex encoding any chars that may cause problems on the filesystem.

Camel.file_util_savename(filename)
Parameters:filename (str) – a pathname
Returns:The new pathname. It must be free’d with GLib.free().
Return type:str

Builds a pathname where the basename is of the form “.#” + the basename of filename, for instance used in a two-stage commit file write.

Camel.folder_info_build(folders, namespace_, separator, short_names)
Parameters:
  • folders ([Camel.FolderInfo]) – an array of Camel.FolderInfo
  • namespace (str) – an ignorable prefix on the folder names
  • separator (int) – the hieararchy separator character
  • short_names (bool) – True if the (short) name of a folder is the Camel.part after the last separator in the full name. False if it is the full name.
Returns:

the top level of the tree of linked folder info.
Return type:

Camel.FolderInfo

This takes an array of folders and attaches them together according to the hierarchy described by their full_names and separator. If namespace_ is non-None, then it will be ignored as a full_name prefix, for purposes of comparison. If necessary, Camel.FolderInfo.build() will create additional Camel.FolderInfo with None urls to fill in gaps in the tree. The value of short_names is used in constructing the names of these intermediate folders.

Camel.freeaddrinfo(host)
Parameters:host (object or None) – a host address information structure to free, or None

Frees a structure returned with Camel.getaddrinfo(). It does nothing when the host is None.

New in version 2.22.

Camel.getaddrinfo(name, service, hints, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

a newly allocated #addrinfo. Free it with Camel.freeaddrinfo() when done with it.
Return type:

object or None

Resolves a host name and returns an information about its address.

New in version 2.22.

Camel.header_address_decode(in_, charset)
Parameters:
  • in (str) –
  • charset (str) –
Return type:

Camel.HeaderAddress
Camel.header_address_fold(in_, headerlen)
Parameters:
  • in (str) –
  • headerlen (int) –
Return type:

str
Camel.header_address_list_append(addrlistp, addr)
Parameters:

TODO: Document me.

Camel.header_address_list_append_list(addrlistp, addrs)
Parameters:

TODO: Document me.

Camel.header_address_list_clear(addrlistp)
Parameters:addrlistp ([Camel.HeaderAddress]) – a None-terminated list of Camel.HeaderAddress objects

TODO: Document me.

Camel.header_address_list_encode(addrlist)
Parameters:addrlist ([Camel.HeaderAddress]) – a None-terminated list of Camel.HeaderAddress objects
Return type:str

TODO: Document me.

Camel.header_address_list_format(addrlist)
Parameters:addrlist ([Camel.HeaderAddress]) – a None-terminated list of Camel.HeaderAddress objects
Return type:str

TODO: Document me.

Camel.header_contentid_decode(in_)
Parameters:in (str) – input string
Returns:the extracted content-id
Return type:str

Extract a content-id from in.

Camel.header_decode_date(str, tz_offset)
Parameters:
  • str (str) – input date string
  • tz_offset (int) – 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-None, the value of the timezone offset will be stored.
Return type:

int

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

Camel.header_decode_int(in_)
Parameters:in (str) – pointer to input string
Returns:the int value
Return type:int

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

Camel.header_decode_string(in_, default_charset)
Parameters:
  • in (str) – input header value string
  • default_charset (str) – default charset to use if improperly encoded
Returns:

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

str

Decodes rfc2047 encoded-word tokens

Camel.header_encode_phrase(in_)
Parameters:in (int) – header to encode
Returns:the encoded ‘phrase’
Return type:str

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

Camel.header_encode_string(in_)
Parameters:in (int) – input string
Returns:the rfc2047 encoded header
Return type:str

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

Camel.header_fold(in_, headerlen)
Parameters:
  • in (str) –
  • headerlen (int) –
Return type:

str
Camel.header_format_ctext(in_, default_charset)
Parameters:
  • in (str) – input header value string
  • default_charset (str) – default charset to use if improperly encoded
Returns:

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

str

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

Camel.header_format_date(date, tz_offset)
Parameters:
  • date (int) – time_t date representation
  • tz_offset (int) – Timezone offset
Returns:

a valid string representation of the date.
Return type:

str

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

Camel.header_location_decode(in_)
Parameters:in (str) –
Return type:str
Camel.header_mailbox_decode(in_, charset)
Parameters:
  • in (str) –
  • charset (str) –
Return type:

Camel.HeaderAddress
Camel.header_mime_decode(in_, maj, min)
Parameters:
Camel.header_msgid_decode(in_)
Parameters:in (str) – input string
Returns:the msg-id
Return type:str

Extract a message-id token from in.

Camel.header_msgid_generate(domain)
Parameters:domain (str) – domain to use (like “example.com”) for the ID suffix; can be None
Returns:Unique message ID.
Return type:str

Either the domain is used, or the user’s local hostname, in case it’s None or empty.

Camel.header_newsgroups_decode(in_)
Parameters:in (str) –
Return type:[str]
Camel.header_param(params, name)
Parameters:
  • params (object or None) – parameters
  • name (str) – name of param to find
Returns:

the value of the name param
Return type:

str

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

Camel.header_param_list_decode(in_)
Parameters:in (str or None) – a header param value to decode
Returns:Decode list of parameters. Free with Camel.HeaderParam.list_free() when done with it.
Return type:object or None
Camel.header_param_list_format(params)
Parameters:params (object or None) –
Return type:str
Camel.header_param_list_format_append(out, params)
Parameters:
Camel.header_param_list_free(params)
Parameters:params (object or None) – a list of params

Free the list of params.

Camel.header_references_decode(in_)
Parameters:in (str) – References header value
Returns:a list of references decoedd from in
Return type:[str]

Generate a list of references, from most recent up.

Camel.header_set_param(paramsp, name, value)
Parameters:
  • paramsp (object or None) – poinetr to a list of params
  • name (str) – name of param to set
  • value (str) – value to set
Returns:

the set param
Return type:

object or None

Set a parameter in the list.

Camel.header_token_decode(in_)
Parameters:in (str) – input string
Returns:a new string containing the first token in in
Return type:str

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

Camel.header_unfold(in_)
Parameters:in (str) –
Return type:str
Camel.headers_dup_mailing_list(headers)
Parameters:headers (Camel.NameValueArray) – a Camel.NameValueArray with headers
Returns:The mailing list header, or None, if none is found
Return type:str or None

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

Camel.host_idna_to_ascii(host)
Parameters:host (str) – Host name, with or without non-ascii letters in utf8
Returns:Newly allocated string with only ASCII letters describing the host. Free it with GLib.free() when done with it.
Return type:str

Converts IDN (Internationalized Domain Name) into ASCII representation. If there’s a failure or the host has only ASCII letters, then a copy of host is returned.

New in version 3.16.

Camel.iconv_charset_language(charset)
Parameters:charset (str) –
Return type:str
Camel.iconv_charset_name(charset)
Parameters:charset (str) –
Return type:str
Camel.iconv_locale_charset()
Return type:str
Camel.iconv_locale_language()
Return type:str
Camel.init(certdb_dir, nss_init)
Parameters:
  • certdb_dir (str) –
  • nss_init (bool) –
Return type:

int
Camel.localtime_with_offset(tt, tm, offset)
Parameters:
  • tt (int) – the #time_t to convert
  • tm (object or None) – the #tm to store the result in
  • offset (int) – the int to store the offset in

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.

Camel.lock_dot(path)
Parameters:path (str) – a path to lock
Raises:GLib.Error
Returns:-1 on error, sets ex appropriately.
Return type:int

Create an exclusive lock using .lock semantics. All locks are equivalent to write locks (exclusive).

The function does nothing and returns success (zero), when dot locking had not been compiled.

Camel.lock_fcntl(fd, type)
Parameters:
Raises:

GLib.Error
Returns:

-1 on error.
Return type:

int

Create a lock using fcntl(2).

type is Camel.LockType.WRITE or Camel.LockType.READ, to create exclusive or shared read locks

The function does nothing and returns success (zero), when fcntl locking had not been compiled.

Camel.lock_flock(fd, type)
Parameters:
Raises:

GLib.Error
Returns:

-1 on error.
Return type:

int

Create a lock using flock(2).

type is Camel.LockType.WRITE or Camel.LockType.READ, to create exclusive or shared read locks

The function does nothing and returns success (zero), when flock locking had not been compiled.

Camel.lock_folder(path, fd, type)
Parameters:
Raises:

GLib.Error
Returns:

-1 on error, ex will describe the locking system that failed.
Return type:

int

Attempt to lock a folder, multiple attempts will be made using all locking strategies available.

Camel.lock_helper_lock(path)
Parameters:path (str) –
Raises:GLib.Error
Return type:int
Camel.lock_helper_unlock(lockid)
Parameters:lockid (int) –
Return type:int
Camel.mktime_utc(tm)
Parameters:tm (object or None) – the #tm to convert to a calendar time representation
Returns:the calendar time representation of tm
Return type:int

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

New in version 3.4.

Camel.movemail(source, dest)
Parameters:
  • source (str) – source file
  • dest (str) – destination file
Raises:

GLib.Error
Returns:

Returns -1 on error or 0 on success.
Return type:

int

This copies an mbox file from a shared directory with multiple readers and writers into a private (presumably Camel-controlled) directory. Dot locking is used on the source file (but not the destination).

Camel.pointer_tracker_dump()

Prints information about currently stored pointers in the pointer tracker. This is called automatically on application exit if camel_pointer_tracker_track() or Camel.pointer_tracker_track_with_info() was called.

Note: If the library is configured with –enable-backtraces, then also backtraces where the pointer was added is printed in the summary.

New in version 3.6.

Camel.pointer_tracker_track_with_info(ptr, info)
Parameters:
  • ptr (object or None) – pointer to add to the pointer tracker
  • info (str) – info to print in tracker summary

Adds pointer to the pointer tracker, with associated information, which is printed in summary of pointer tracker printed by Camel.pointer_tracker_dump(). For convenience can be used camel_pointer_tracker_track(), which adds place of the caller as info. Added pointer should be removed with pair function Camel.pointer_tracker_untrack().

New in version 3.6.

Camel.pointer_tracker_untrack(ptr)
Parameters:ptr (object or None) – pointer to remove from the tracker

Removes pointer from the pointer tracker. It’s an error to try to remove pointer which was not added to the tracker by camel_pointer_tracker_track() or Camel.pointer_tracker_track_with_info(), or a pointer which was already removed.

New in version 3.6.

Camel.provider_get(protocol)
Parameters:protocol (str) – a Camel.Provider protocol name
Raises:GLib.Error
Returns:a Camel.Provider for protocol, or None
Return type:Camel.Provider

Returns the registered Camel.Provider for protocol, loading it from disk if necessary. If no Camel.Provider can be found for protocol, or the provider module fails to load, the function sets error and returns None.

The returned Camel.Provider is owned by Camel and should not be modified or freed.

Camel.provider_init()

Initialize the Camel provider system by reading in the .urls files in the provider directory and creating a hash table mapping URLs to module names.

A .urls file has the same initial prefix as the shared library it correspond to, and consists of a series of lines containing the URL protocols that that library handles.

TODO: This should be pathed? TODO: This should be plugin-d?

Camel.provider_list(load)
Parameters:load (bool) – whether or not to load in providers that are not already loaded
Returns:a GLib.List of Camel.Provider structs
Return type:[Camel.Provider]

This returns a list of available providers. If load is True, it will first load in all available providers that haven’t yet been loaded.

Free the returned list with g_list_free(). The Camel.Provider structs in the list are owned by Camel and should not be modified or freed.

Camel.provider_load(path)
Parameters:path (str) – the path to a shared library
Raises:GLib.Error
Returns:True on success, False on failure
Return type:bool

Loads the provider at path, and calls its initialization function, passing session as an argument. The provider should then register itself with session.

Camel.provider_module_init()
Camel.pstring_add(string, own)
Parameters:
  • string (str) – string to add to the string pool
  • own (bool) – whether the string pool will own the memory pointed to by string, if string is not yet in the pool
Returns:

a canonicalized copy of string
Return type:

str

Add string to the pool.

The None and empty strings are special cased to constant values.

Unreference the returned string with Camel.pstring_free().

Camel.pstring_contains(string)
Parameters:string (str) – string to look up in the string pool
Returns:Whether the string exists in the string pool
Return type:bool

Returns whether the string exists in the string pool.

The None and empty strings are special cased to constant values.

New in version 3.22.

Camel.pstring_dump_stat()

Dumps to stdout memory statistic about the string pool.

New in version 3.6.

Camel.pstring_free(string)
Parameters:string (str) – string to free

Unreferences a pooled string. If the string’s reference count drops to zero it will be deallocated. None and the empty string are special cased.

Camel.pstring_peek(string)
Parameters:string (str) – string to fetch from the string pool
Returns:a canonicalized copy of string
Return type:str

Returns the canonicalized copy of string without increasing its reference count in the string pool. If necessary, string is first added to the string pool.

The None and empty strings are special cased to constant values.

New in version 2.24.

Camel.pstring_strdup(string)
Parameters:string (str) – string to copy
Returns:a canonicalized copy of string
Return type:str

Create a new pooled string entry for strings. A pooled string is a table where common strings are canonicalized. They are also reference counted and freed when no longer referenced.

The None and empty strings are special cased to constant values.

Unreference the returned string with Camel.pstring_free().

Camel.quoted_decode_step(in_, out, saveme)
Parameters:
  • in (bytes) – input stream
  • out (bytes) – output stream
  • saveme ([int]) – leftover bits that have not yet been decoded
Returns:

the number of bytes decoded

out:output stream
saveme:leftover bits that have not yet been decoded

Return type:

(int, out: bytes, saveme: [int])

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

Camel.quoted_encode_close(in_, out, save)
Parameters:
  • in (bytes) – input stream
  • out (bytes) – output string
  • save ([int]) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded

out:output string
save:leftover bits that have not yet been encoded

Return type:

(int, out: bytes, save: [int])

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.

Camel.quoted_encode_step(in_, out, save)
Parameters:
  • in (bytes) – input stream
  • out (bytes) – output string
  • save ([int]) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded

out:output string
save:leftover bits that have not yet been encoded

Return type:

(int, out: bytes, save: [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).

Camel.read(fd, buf, n, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

number of bytes read or -1 on fail. On failure, errno will be set appropriately.
Return type:

int

Cancellable libc read() replacement.

Code that intends to be portable to Win32 should call this function only on file descriptors returned from open(), not on sockets.

Camel.search_camel_header_soundex(header, match)
Parameters:
  • header (str) –
  • match (str) –
Return type:

bool
Camel.search_get_all_headers_decoded(message)
Parameters:message (Camel.MimeMessage) – a #CamelMessage
Returns:All headers of the message, decoded where needed. Free the returned pointer with GLib.free() when done with it.
Return type:str

New in version 3.22.

Camel.search_get_default_charset_from_headers(headers)
Parameters:headers (Camel.NameValueArray) – a Camel.NameValueArray
Returns:Default charset from the Content-Type header of the headers; if none cannot be determined, UTF-8 is returned.
Return type:str

New in version 3.28.

Camel.search_get_default_charset_from_message(message)
Parameters:message (Camel.MimeMessage) – a Camel.MimeMessage
Returns:Default charset of the message; if none cannot be determined, UTF-8 is returned.
Return type:str

New in version 3.22.

Camel.search_get_header_decoded(header_name, header_value, default_charset)
Parameters:
  • header_name (str) – the header name
  • header_value (str) – the header value
  • default_charset (str or None) – the default charset to use for the decode, or None
Returns:

decoded header value, suitable for text comparison. Free the returned pointer with GLib.free() when done with it.
Return type:

str

Decodes header_value, if needed, either from an address header or the Subject header. Other header_name headers are returned as is.

New in version 3.22.

Camel.search_get_headers_decoded(headers, default_charset)
Parameters:
Returns:

The headers, decoded where needed. Free the returned pointer with GLib.free() when done with it.
Return type:

str

New in version 3.28.

Camel.search_header_is_address(header_name)
Parameters:header_name (str) – A header name, like “Subject”
Returns:Whether the header_name is a header with a mail address
Return type:bool

New in version 3.22.

Camel.search_header_match(value, match, how, type, default_charset)
Parameters:
  • value (str) –
  • match (str) –
  • how (Camel._search_match_t) –
  • type (Camel._search_t) –
  • default_charset (str) –
Return type:

bool
Camel.search_words_free(words)
Parameters:words (object or None) –
Camel.search_words_simple(words)
Parameters:words (object or None) –
Return type:object or None
Camel.search_words_split(in_)
Parameters:in (int) –
Return type:object or None
Camel.shutdown()

New in version 2.24.

Camel.store_info_name(summary, info)
Parameters:
Returns:

the last segment of the path string from info
Return type:

str

Returns the last segment of the path string from info.

Camel.store_info_path(summary, info)
Parameters:
Returns:

the path string from info
Return type:

str

Returns the path string from info.

Camel.store_info_set_string(summary, info, type, value)
Parameters:

Set a specific string on the info.

Camel.strcase_equal(a, b)
Parameters:
Return type:

int
Camel.strcase_hash(v)
Parameters:v (object or None) –
Return type:int
Camel.strdown(str)
Parameters:str (str) –
Return type:str
Camel.strstrcase(haystack, needle)
Parameters:
  • haystack (str) –
  • needle (str) –
Return type:

str
Camel.system_flag(name)
Parameters:name (str) – name of a system flag
Returns:the integer value of the system flag string
Return type:Camel.MessageFlags
Camel.system_flag_get(flags, name)
Parameters:
Returns:

True if the named flag is set or False otherwise
Return type:

bool

Find the state of the flag name in flags.

Camel.text_to_html(in_, flags, color)
Parameters:
  • in (str) – input text
  • flags (Camel.MimeFilterToHTMLFlags) – bitwise flags defining the html conversion behaviour
  • color (int) – color to use when syntax highlighting
Returns:

a newly allocated string containing the HTMLified version of in
Return type:

str

Convert in from plain text into HTML.

Camel.time_value_apply(src_time, unit, value)
Parameters:
Returns:

src_time modified by the given parameters as date, with the time Camel.part being beginning of the day.
Return type:

int

Applies the given time value in unit unit to the src_time. Use negative value to subtract it. The time Camel.part is rounded to the beginning of the day.

New in version 3.24.

Camel.transfer_encoding_from_string(string)
Parameters:string (str) –
Return type:Camel.TransferEncoding
Camel.transfer_encoding_to_string(encoding)
Parameters:encoding (Camel.TransferEncoding) –
Return type:str
Camel.ucs2_utf8(ptr)
Parameters:ptr (str) – a ucs2 string to convert
Returns:The converted string. Free it with GLib.free(), when no longer needed.
Return type:str

Convert a ucs2 string into a UTF-8 one. The ucs2 string is treated as network byte ordered, and terminated with a 16-bit None.

Camel.uid_cache_free_uids(uids)
Parameters:uids ([str]) – an array returned from Camel.UIDCache.get_new_uids()

Frees the array of UIDs.

Camel.unlock_dot(path)
Parameters:path (str) – a path to unlock

Attempt to unlock a .lock lock.

The function does nothing, when dot locking had not been compiled.

Camel.unlock_fcntl(fd)
Parameters:fd (int) – a file descriptor

Unlock an fcntl lock.

The function does nothing, when fcntl locking had not been compiled.

Camel.unlock_flock(fd)
Parameters:fd (int) – a file descriptor

Unlock an flock lock.

The function does nothing, when flock locking had not been compiled.

Camel.unlock_folder(path, fd)
Parameters:
  • path (str) – Filename of folder.
  • fd (int) – Open descrptor on which locks were placed.

Free a lock on a folder.

Camel.url_addrspec_end(in_, pos, inend, match)
Parameters:
Return type:

bool
Camel.url_addrspec_start(in_, pos, inend, match)
Parameters:
Return type:

bool
Camel.url_decode(part)
Parameters:part (str) – a URL Camel.part

%-decodes the passed-in URL *in place*. The decoded version is never longer than the encoded version, so there does not need to be any additional space at the end of the string.

Camel.url_decode_path(path)
Parameters:path (str) –
Return type:str
Camel.url_encode(part, escape_extra)
Parameters:
  • part (str) – a URL Camel.part
  • escape_extra (str) – additional characters beyond ” "%#<>{}|\^[]`” to escape (or None)
Returns:

the encoded string
Return type:

str

This &percnt;-encodes the given URL Camel.part and returns the escaped version in allocated memory, which the caller must free when it is done.

Camel.url_file_end(in_, pos, inend, match)
Parameters:
Return type:

bool
Camel.url_file_start(in_, pos, inend, match)
Parameters:
Return type:

bool
Camel.url_web_end(in_, pos, inend, match)
Parameters:
Return type:

bool
Camel.url_web_start(in_, pos, inend, match)
Parameters:
Return type:

bool
Camel.ustrstrcase(haystack, needle)
Parameters:
  • haystack (str) –
  • needle (str) –
Return type:

str
Camel.utf7_utf8(ptr)
Parameters:ptr (str) – a UTF-7 string to convert
Returns:The converted string. Free it with GLib.free(), when no longer needed.
Return type:str

Convert a modified UTF-7 string to UTF-8. If the UTF-7 string contains 8 bit characters, they are treated as iso-8859-1.

The IMAP rules [rfc2060] are used in the UTF-7 encoding.

Camel.utf8_getc(ptr)
Parameters:ptr (int) – a pointer to read the character from
Returns:The next Unicode character. The ptr will be advanced to the next character always.
ptr:a pointer to read the character from
Return type:(int, ptr: int)

Get a Unicode character from a UTF-8 stream. ptr will be advanced to the next character position. Invalid utf8 characters will be silently skipped. The ptr should point to a NUL terminated array.

Camel.utf8_getc_limit(ptr, end)
Parameters:
  • ptr (int) – a pointer to read the character from
  • end (int) – upper limit for the read, must not be None
Returns:

The next UTF-8 str, or 0xffff.

ptr:a pointer to read the character from

Return type:

(int, ptr: int)

Get the next UTF-8 str at ptr, and return it, advancing ptr to the next character. If end is reached before a full UTF-8 character can be read, then the invalid Unicode str 0xffff is returned as a sentinel (Unicode 3.1, section 2.7), and ptr is not advanced.

Camel.utf8_make_valid(text)
Parameters:text (str) – a text to make valid
Returns:Valid UTF-8 string, with replaced incorrect letters. Free it with GLib.free(), when no longer needed.
Return type:str

Ensures the returned text will be valid UTF-8 string, with incorrect letters changed to question marks.

New in version 2.26.

Camel.utf8_make_valid_len(text, text_len)
Parameters:
  • text (str) – a text to make valid
  • text_len (int) – length of the text, or -1 if NUL-terminated
Returns:

Valid UTF-8 string, with replaced incorrect letters. Free it with GLib.free(), when no longer needed.
Return type:

str

Ensures the returned text will be valid UTF-8 string, with incorrect letters changed to question marks.

New in version 3.34.

Camel.utf8_putc(ptr, c)
Parameters:
  • ptr (int) – pointer to write the character to
  • c (int) – a Unicode character to write
Returns:

pointer to write the character to
Return type:

ptr: int

Output a 32 bit unicode character as UTF-8 octets. At most 4 octets will be written to ptr. The ptr will be advanced to the next character position.

Camel.utf8_ucs2(ptr)
Parameters:ptr (str) – a UTF-8 string to convert
Returns:The converted string. Free it with GLib.free(), when no longer needed.
Return type:str

Convert a UTF-8 string into a ucs2 one. The ucs string will be in network byte order, and terminated with a 16-bit None.

Camel.utf8_utf7(ptr)
Parameters:ptr (str) – a UTF-8 string to convert
Returns:The converted string. Free it with GLib.free(), when no longer needed.
Return type:str

Convert a UTF-8 string to a modified UTF-7 format.

The IMAP rules [rfc2060] are used in the UTF-7 encoding.

Camel.util_bdata_get_number(bdata_ptr, default_value)
Parameters:
  • bdata_ptr (str) – a backend specific data (bdata) pointer
  • default_value (int) – a value to return, when no data can be read
Returns:

The read number, or the default_value, if the bdata_ptr doesn’t point to a number.
Return type:

int

Reads a numeric data from the bdata_ptr and moves the bdata_ptr after that number. If the number cannot be read, then the default_value is returned instead and the bdata_ptr is left unchanged. The number might be previously stored with the Camel.util_bdata_put_number().

New in version 3.24.

Camel.util_bdata_get_string(bdata_ptr, default_value)
Parameters:
  • bdata_ptr (str) – a backend specific data (bdata) pointer
  • default_value (str) – a value to return, when no data can be read
Returns:

Newly allocated string, which was read, or dupped the default_value, if the bdata_ptr doesn’t point to a string. Free returned pointer with GLib.free() when done with it.
Return type:

str

Reads a string data from the bdata_ptr and moves the bdata_ptr after that string. If the string cannot be read, then the default_value is returned instead and the bdata_ptr is left unchanged. The string might be previously stored with the Camel.util_bdata_put_string().

New in version 3.24.

Camel.util_bdata_put_number(bdata_str, value)
Parameters:

Puts the number value at the end of the bdata_str. In case the bdata_str is not empty a space is added before the numeric value. The stored value can be read back with the Camel.util_bdata_get_number().

New in version 3.24.

Camel.util_bdata_put_string(bdata_str, value)
Parameters:

Puts the string value at the end of the bdata_str. In case the bdata_str is not empty a space is added before the string value. The stored value can be read back with the Camel.util_bdata_get_string().

The strings are encoded as “length-value”, quotes for clarity only.

New in version 3.24.

Camel.uudecode_step(in_, out, save)
Parameters:
  • in (bytes) – input stream
  • out (bytes) – output stream
  • save ([int]) – leftover bits that have not yet been decoded
Returns:

the number of bytes decoded

out:output stream
save:leftover bits that have not yet been decoded

Return type:

(int, out: bytes, save: [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.

Camel.uuencode_close(in_, out, uubuf, save)
Parameters:
  • in (bytes) – input stream
  • out (bytes) – output stream
  • uubuf (bytes) – temporary buffer of 60 bytes
  • save ([int]) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded

out:output stream
uubuf:temporary buffer of 60 bytes
save:leftover bits that have not yet been encoded

Return type:

(int, out: bytes, uubuf: bytes, save: [int])

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

Camel.uuencode_step(in_, out, uubuf, save)
Parameters:
  • in (bytes) – input stream
  • out (bytes) – output stream
  • uubuf (bytes) – temporary buffer of 60 bytes
  • save ([int]) – leftover bits that have not yet been encoded
Returns:

the number of bytes encoded

out:output stream
uubuf:temporary buffer of 60 bytes
save:leftover bits that have not yet been encoded

Return type:

(int, out: bytes, uubuf: bytes, save: [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).

Camel.write(fd, buf, n, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

number of bytes written or -1 on fail. On failure, errno will be set appropriately.
Return type:

int

Cancellable libc write() replacement.

Code that intends to be portable to Win32 should call this function only on file descriptors returned from open(), not on sockets.

Camel.ydecode_step(in_)
Parameters:in (bytes) – input buffer
Returns:the number of bytes decoded
out:output buffer
state:ydecode state
pcrc:Camel.part crc state
crc:crc state
Return type:(int, out: bytes, state: int, pcrc: int, crc: int)

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

To get the crc32 value of the Camel.part, use #CAMEL_MIME_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 #CAMEL_MIME_YENCODE_CRC_FINAL (crc).

Camel.yencode_close(in_)
Parameters:in (bytes) – input buffer
Returns:the number of bytes encoded.
out:output buffer
state:yencode state
pcrc:Camel.part crc state
crc:crc state
Return type:(int, out: bytes, state: int, pcrc: int, crc: int)

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

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

Camel.yencode_step(in_)
Parameters:in (bytes) – input buffer
Returns:the number of bytes encoded
out:output buffer
state:yencode state
pcrc:Camel.part crc state
crc:crc state
Return type:(int, out: bytes, state: int, pcrc: int, crc: int)

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

state should be initialized to Camel.MIME_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 Camel.MIME_YENCODE_CRC_INIT before using.