Functions ¶

Returns:

-1 on error;

Return type:

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:

cert_info (Camel.CipherCertInfo) – a Camel.CipherCertInfo
name (str) – a property name

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:

cert_info (Camel.CipherCertInfo) – a Camel.CipherCertInfo
name (str) – a property name
value (object or None) – a property value, or None
value_free (GLib.DestroyNotify or None) – a free function for the value
value_clone (Camel.CipherCloneFunc or None) – a clone function for the value

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.

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.

Return type:

GLib.String or None

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 or None

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:

backtrace (GLib.String) – a backtrace to push, taken from Camel.debug_get_backtrace()
object_ref_count (int) – the current object reference count when the push is done

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 (Camel.MimeFilterEnrichedFlags) – flags specifying filter behaviour

Returns:

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

Return type:

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:

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:

Decode a normal string from the input file.

Camel.file_util_decode_gint64(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:

Decode a gint64 type.

New in version 3.50.

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:

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:

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:

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:

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:

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:

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:

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_gint64(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:

Encode a gint64 type.

New in version 3.50.

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:

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:

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:

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:

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:

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_error_quark()¶

Return type:: int

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:

name (str) – an address name to resolve
service (str) – a service name to use
hints (object or None) – an #addrinfo hints, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

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:

Camel.header_address_list_append(addrlistp, addr)¶

Parameters:

addrlistp ([Camel.HeaderAddress]) – a None-terminated list of Camel.HeaderAddress objects
addr (Camel.HeaderAddress) – the Camel.HeaderAddress to add

TODO: Document me.

Camel.header_address_list_append_list(addrlistp, addrs)¶

Parameters:

addrlistp ([Camel.HeaderAddress]) – a None-terminated list of Camel.HeaderAddress objects
addrs ([Camel.HeaderAddress]) – a None-terminated list of Camel.HeaderAddress to add

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:

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:

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:

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:

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:

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:

in (str) –
maj (int) –
min (int) –

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 or None) – 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:

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:

out (GLib.String) –
params (object or None) –

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 or None) – Host name, with or without non-ascii letters in utf8
Returns:: Newly allocated string with only ASCII letters describing the host or None, when the host is None. Free the returned string with GLib.free() when no longer needed.
Return type:: str or None

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.hostname_utils_requires_ascii(hostname)¶

Parameters:: hostname (str) – a host name
Returns:: True, when the hostname should be converted to an ASCII equivalent, False, when it can be shown as is.
Return type:: bool

Check whether the hostname requires conversion to ASCII. That can be when a character in it can look like an ASCII character, even it being a Unicode letter. This can be used to display host names in a way of invulnerable to IDN homograph attacks.

New in version 3.44.

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:

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:

fd (int) – a file descriptor
type (Camel.LockType) – a Camel.LockType

Raises:

Returns:

-1 on error.

Return type:

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:

fd (int) – a file descriptor
type (Camel.LockType) – a Camel.LockType

Raises:

Returns:

-1 on error.

Return type:

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:

path (str) – Path to the file to lock (used for .locking only).
fd (int) – Open file descriptor of the right type to lock.
type (Camel.LockType) – Type of lock, Camel.LockType.READ or Camel.LockType.WRITE.

Raises:

Returns:

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

Return type:

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:

Returns:

Returns -1 on error or 0 on success.

Return type:

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 on error
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 or None) – 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 or None

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 or None) – 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 or None) – 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 or None) – string to fetch from the string pool
Returns:: a canonicalized copy of string
Return type:: str or None

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 or None) – string to copy
Returns:: a canonicalized copy of string
Return type:: str or None

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:

fd (int) – file descriptor
buf (str) – buffer to fill
n (int) – number of bytes to read into buf
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

Returns:

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

Return type:

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:

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:

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:

headers (Camel.NameValueArray) – a Camel.NameValueArray
default_charset (str or None) – default charset to use; or None, to detect from Content-Type of headers

Returns:

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

Return type:

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:

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.service_error_quark()¶

Return type:: int

Camel.shutdown()¶: New in version 2.24.

Camel.store_error_quark()¶

Return type:: int

Camel.store_info_name(summary, info)¶

Parameters:

summary (Camel.StoreSummary) – a Camel.StoreSummary
info (Camel.StoreInfo) – a Camel.StoreInfo

Returns:

the last segment of the path string from info

Return type:

Returns the last segment of the path string from info.

Deprecated since version 3.46: Use Camel.StoreInfo.get_name() instead.

Camel.store_info_path(summary, info)¶

Parameters:

summary (Camel.StoreSummary) – a Camel.StoreSummary
info (Camel.StoreInfo) – a Camel.StoreInfo

Returns:

the path string from info

Return type:

Returns the path string from info.

Deprecated since version 3.46: Use Camel.StoreInfo.get_path() instead.

Camel.store_info_set_string(summary, info, type, value)¶

Parameters:

summary (Camel.StoreSummary) – a Camel.StoreSummary object
info (Camel.StoreInfo) – a Camel.StoreInfo
type (int) – specific string being set
value (str) – string value to set

Set a specific string on the info.

Deprecated since version 3.46: Use Camel.StoreInfo.set_value() instead.

Camel.strcase_equal(a, b)¶

Parameters:

a (object or None) –
b (object or None) –

Return type:

Camel.strcase_hash(v)¶

Parameters:: v (object or None) –
Return type:: int

Camel.strdown(str)¶

Parameters:: str (str) –
Return type:: str

Camel.string_is_all_ascii(str)¶

Parameters:: str (str or None) – a string to check, or None
Returns:: True, when the str is None, an empty string or when it contains only ASCII letters.
Return type:: bool

New in version 3.44.

Camel.strstrcase(haystack, needle)¶

Parameters:

haystack (str) –
needle (str) –

Return type:

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:

flags (Camel.MessageFlags) – bitwise system flags
name (str) – name of the flag to check for

Returns:

True if the named flag is set or False otherwise

Return type:

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:

Convert in from plain text into HTML.

Camel.time_value_apply(src_time, unit, value)¶

Parameters:

src_time (int) – a time_t to apply the value to, or -1 to use the current time
unit (Camel.TimeUnit) – a Camel.TimeUnit
value (int) – a value to apply

Returns:

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

Return type:

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:

in (str) –
pos (str) –
inend (str) –
match (Camel.UrlMatch) –

Return type:

Camel.url_addrspec_start(in_, pos, inend, match)¶

Parameters:

in (str) –
pos (str) –
inend (str) –
match (Camel.UrlMatch) –

Return type:

Camel.url_decode(part)¶

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

&percnt;-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 or None) – additional characters beyond “ \”%#<>{}|\^[]`” to escape (or None)

Returns:

the encoded string

Return type:

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:

in (str) –
pos (str) –
inend (str) –
match (Camel.UrlMatch) –

Return type:

Camel.url_file_start(in_, pos, inend, match)¶

Parameters:

in (str) –
pos (str) –
inend (str) –
match (Camel.UrlMatch) –

Return type:

Camel.url_web_end(in_, pos, inend, match)¶

Parameters:

in (str) –
pos (str) –
inend (str) –
match (Camel.UrlMatch) –

Return type:

Camel.url_web_start(in_, pos, inend, match)¶

Parameters:

in (str) –
pos (str) –
inend (str) –
match (Camel.UrlMatch) –

Return type:

Camel.ustrstrcase(haystack, needle)¶

Parameters:

haystack (str) –
needle (str) –

Return type:

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:

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:

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:

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:

bdata_str (GLib.String) – a GLib.String to store a backend specific data (bdata)
value (int) – a value to store

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:

bdata_str (GLib.String) – a GLib.String to store a backend specific data (bdata)
value (str) – a value to store

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.util_decode_user_header_setting(setting_value)¶

Parameters:

setting_value (str) – the value to decode

Returns:

out_display_name:: location for the decoded display name, or None when not needed
out_header_name:: the location for the decoded header name

Return type:

(out_display_name: str or None, out_header_name: str)

Decode the values previously encoded by Camel.util_encode_user_header_setting(). The out_header_name points to the setting_value, thus it’s valid as long as the setting_value is valid and unchanged.

The out_header_name can result in None when the setting_value contains invalid data.

The out_display_name can result in None when the setting_value does not contain the display name. In such case the header name can be used as the display name.

New in version 3.42.

Camel.util_encode_user_header_setting(display_name, header_name)¶

Parameters:

display_name (str or None) – display name for the header name, or None
header_name (str) – the header name

Returns:

a newly allocated string with encoded display_name and header_name

Return type:

Encode the optional display_name and the header_name to a value suitable for Gio.Settings schema org.gnome.evolution-data-server and key camel-message-info-user-headers.

Free the returned string with GLib.free(), when no longer needed.

New in version 3.42.

Camel.util_fill_message_info_user_headers(info, headers)¶

Parameters:

info (Camel.MessageInfo) – a Camel.MessageInfo
headers (Camel.NameValueArray) – a Camel.NameValueArray with the headers to read from

Returns:

Whether the info's user headers changed

Return type:

Fill info ‘s user-headers with the user-defined headers from the headers array.

New in version 3.42.

Camel.util_get_directory_variants(main_path, replace_prefix, with_modules_dir)¶

Parameters:

main_path (str) – the main path to work with
replace_prefix (str) – path prefix to replace
with_modules_dir (bool) – whether to add also the modules directory

Returns:

a GLib.PtrArray with paths to use, including the main_path. Free it with g_ptr_array_unref(), when no longer needed.

Return type:

[str]

The main_path is a directory, which will be always used. It should have as its prefix the replace_prefix, otherwise the function returns only the main_path in the paths array.

When there’s exported an environment variable EDS_EXTRA_PREFIXES, it is used as a list of alternative prefixes where to look for the main_path (rest after the replace_prefix).

When the with_modules_dir is True, there’s also added GLib.get_user_data_dir() + “evolution/modules/”, aka ~/.local/share/evolution/modules/, into the resulting array.

New in version 3.40.

Camel.utils_sanitize_ascii_domain_in_address(email_address, do_format)¶

Parameters:

email_address (str or None) – an email address as string
do_format (bool) – what format will be returned

Returns:

the email_address with only ASCII letters, if such conversion is needed or None, when no conversion was required.

See: Camel.hostname_utils_requires_ascii(), Camel.InternetAddress.sanitize_ascii_domain(), Camel.utils_sanitize_ascii_domain_in_url_str()

Return type:

str or None

Checks whether the domain in the email_address requires conversion to ASCII and if it does it also converts it. When the do_format is True, the output string is formatted for display, otherwise it’s encoded for use in the message headers. A None is returned when no conversion was needed.

New in version 3.44.

Camel.utils_sanitize_ascii_domain_in_url(url)¶

Parameters:

url (Camel.URL) – a Camel.URL

Returns:

True, when the conversion was required.

See: Camel.hostname_utils_requires_ascii(), Camel.utils_sanitize_ascii_domain_in_url_str()

Return type:

Checks whether the host name of the url requires conversion to ASCII and converts it, if needed.

New in version 3.44.

Camel.utils_sanitize_ascii_domain_in_url_str(url_str)¶

Parameters:

url_str (str or None) – a URL as string

Returns:

converted url_str to ASCII host name, or None, when no conversion was needed.

See: Camel.hostname_utils_requires_ascii(), Camel.utils_sanitize_ascii_domain_in_url()

Return type:

str or None

Checks whether the host name of the url_str requires conversion to ASCII and converts it if needed. Returns None, when no conversion was required.

New in version 3.44.

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:

fd (int) – file descriptor
buf (str) – buffer to write
n (int) – number of bytes of buf to write
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

Returns:

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

Return type: