e-data-server-util: Evolution-Data-Server Reference Manual

## e-data-server-util e-data-server-util |

## Functions

const gchar * | e_get_user_cache_dir ()
const gchar * | e_get_user_config_dir ()
const gchar * | e_get_user_data_dir ()
gboolean | e_util_strv_equal ()
gchar * | e_util_strdup_strip ()
gint | e_util_strcmp0 ()
gchar * | e_util_strstrcase ()
gchar * | e_util_unicode_get_utf8 ()
const gchar * | e_util_utf8_strstrcase ()
const gchar * | e_util_utf8_strstrcasedecomp ()
gint | e_util_utf8_strcasecmp ()
gchar * | e_util_utf8_remove_accents ()
gchar * | e_util_utf8_decompose ()
gchar * | e_util_utf8_make_valid ()
gchar * | e_util_utf8_data_make_valid ()
gchar * | e_util_utf8_normalize ()
const gchar * | e_util_ensure_gdbus_string ()
guint64 | e_util_gthread_id ()
void | e_filename_make_safe ()
gchar * | e_filename_mkdir_encoded ()
gsize | e_utf8_strftime ()
gsize | e_strftime ()
gchar ** | e_util_slist_to_strv ()
GSList * | e_util_strv_to_slist ()
void | e_util_free_nullable_object_slist ()
void | e_util_safe_free_string ()
void | e_queue_transfer ()
GWeakRef * | e_weak_ref_new ()
void | e_weak_ref_free ()
gboolean | e_file_recursive_delete_sync ()
void | e_file_recursive_delete ()
gboolean | e_file_recursive_delete_finish ()
GBinding * | e_binding_bind_property ()
GBinding * | e_binding_bind_property_full ()
GBinding * | e_binding_bind_property_with_closures ()
gboolean | e_binding_transform_enum_value_to_nick ()
gboolean | e_binding_transform_enum_nick_to_value ()
gboolean | e_enum_from_string ()
const gchar * | e_enum_to_string ()
EAsyncClosure * | e_async_closure_new ()
EAsyncClosure * | e_async_closure_new_with_context ()
GAsyncResult * | e_async_closure_wait ()
void | e_async_closure_free ()
void | e_async_closure_callback ()
const gchar * | e_util_get_prefix ()
const gchar * | e_util_get_cp_prefix ()
const gchar * | e_util_get_localedir ()
gchar * | e_util_replace_prefix ()
void | e_util_win32_initialize ()
ENamedParameters * | e_named_parameters_new ()
ENamedParameters * | e_named_parameters_new_strv ()
ENamedParameters * | e_named_parameters_new_string ()
ENamedParameters * | e_named_parameters_new_clone ()
void | e_named_parameters_free ()
void | e_named_parameters_clear ()
void | e_named_parameters_assign ()
void | e_named_parameters_set ()
const gchar * | e_named_parameters_get ()
gchar ** | e_named_parameters_to_strv ()
gchar * | e_named_parameters_to_string ()
gboolean | e_named_parameters_test ()
gboolean | e_named_parameters_exists ()
guint | e_named_parameters_count ()
gchar * | e_named_parameters_get_name ()
#define | e_named_timeout_add()
#define | e_named_timeout_add_full()
#define | e_named_timeout_add_seconds()
#define | e_named_timeout_add_seconds_full()
guint | e_timeout_add_with_name ()
guint | e_timeout_add_seconds_with_name ()
void | e_util_free_string_slist ()
void | e_util_free_object_slist ()
GSList * | e_util_copy_string_slist ()
GSList * | e_util_copy_object_slist ()
gint | e_data_server_util_get_dbus_call_timeout ()
void | e_data_server_util_set_dbus_call_timeout ()
gboolean | e_source_registry_debug_enabled ()
void | e_source_registry_debug_print ()
void | e_util_debug_print ()
void | e_util_debug_printv ()
void | (*ETypeFunc) ()
void | e_type_traverse ()
gchar * | e_util_get_source_full_name ()
void | e_util_unref_in_thread ()
gchar * | e_util_generate_uid ()
gboolean | e_util_identity_can_send ()
gboolean | e_util_can_use_collection_as_credential_source ()
gint | e_util_source_compare_for_sort ()
GPtrArray * | e_util_get_directory_variants ()

## Types and Values

| EAsyncClosure
| ENamedParameters
struct | tm

## Object Hierarchy

        GBoxed
        ╰── ENamedParameters

## Description

## Functions

### e_get_user_cache_dir ()

    const gchar *
    e_get_user_cache_dir (void);

Returns a base directory in which to store user-specific, non-essential cached data for Evolution or Evolution-Data-Server.

The returned string is owned by libedataserver and must not be modified or freed.

#### Returns

base directory for user-specific, non-essential data

Since: 2.32

### e_get_user_config_dir ()

    const gchar *
    e_get_user_config_dir (void);

Returns a base directory in which to store user-specific configuration information for Evolution or Evolution-Data-Server.

The returned string is owned by libedataserver and must not be modified or freed.

#### Returns

base directory for user-specific configuration information

Since: 2.32

### e_get_user_data_dir ()

    const gchar *
    e_get_user_data_dir (void);

Returns a base directory in which to store user-specific data for Evolution or Evolution-Data-Server.

The returned string is owned by libedataserver and must not be modified or freed.

#### Returns

base directory for user-specific data

Since: 2.32

### e_util_strv_equal ()

    gboolean
    e_util_strv_equal (gconstpointer v1,
                       gconstpointer v2);

Compares `v1` and `v2` for equality, handling `NULL` gracefully.

The arguments types are generic for compatibility with GEqualFunc.

#### Parameters

v1 | a `NULL`-terminated string array, or `NULL`. | [allow-none]
v2 | another `NULL`-terminated string array, or `NULL`. | [allow-none]

#### Returns

whether `v1` and `v2` are identical

Since: 3.12

### e_util_strdup_strip ()

    gchar *
    e_util_strdup_strip (const gchar *string);

Duplicates `string` and strips off any leading or trailing whitespace. The resulting string is returned unless it is empty or `NULL`, in which case the function returns `NULL`.

Free the returned string with `g_free()`.

#### Parameters

string | a string value, or `NULL`. | [allow-none]

#### Returns

a newly-allocated, stripped copy of `string` , or `NULL`

Since: 3.6

### e_util_strcmp0 ()

    gint
    e_util_strcmp0 (const gchar *str1,
                    const gchar *str2);

Compares `str1` and `str2` like `g_strcmp0()`, except it handles `NULL` and empty strings as equal.

#### Parameters

str1 | a C string on `NULL` |
str2 | another C string or `NULL` |

#### Returns

an integer less than 0 when `str1` is before `str2` ; 0 when the strings are equal and an integer greated than 0 when `str1` is after `str2` .

Since: 3.32

### e_util_strstrcase ()

    gchar *
    e_util_strstrcase (const gchar *haystack,
                       const gchar *needle);

Find the first instance of `needle` in `haystack` , ignoring case for bytes that are ASCII characters.

#### Parameters

haystack | The string to search in. |
needle | The string to search for. |

#### Returns

A pointer to the start of `needle` in `haystack` , or NULL if `needle` is not found.

### e_util_unicode_get_utf8 ()

    gchar *
    e_util_unicode_get_utf8 (const gchar *text,
                             gunichar *out);

Get a UTF-8 character from the beginning of `text` .

#### Parameters

text | The string to take the UTF-8 character from. |
out | The location to store the UTF-8 character in. |

#### Returns

A pointer to the next character in `text` after `out` .

### e_util_utf8_strstrcase ()

    const gchar *
    e_util_utf8_strstrcase (const gchar *haystack,
                            const gchar *needle);

Find the first instance of `needle` in `haystack` , ignoring case. (No proper case folding or decomposing is done.) Both `needle` and `haystack` are UTF-8 strings.

#### Parameters

haystack | The string to search in. |
needle | The string to search for. |

#### Returns

A pointer to the first instance of `needle` in `haystack` , or `NULL` if no match is found, or if either of the strings are not legal UTF-8 strings.

### e_util_utf8_strstrcasedecomp ()

    const gchar *
    e_util_utf8_strstrcasedecomp (const gchar *haystack,
                                  const gchar *needle);

Find the first instance of `needle` in `haystack` , where both `needle` and `haystack` are UTF-8 strings. Both strings are stripped and decomposed for comparison, and case is ignored.

#### Parameters

haystack | The string to search in. |
needle | The string to search for. |

#### Returns

A pointer to the first instance of `needle` in `haystack` , or `NULL` if either of the strings are not legal UTF-8 strings.

### e_util_utf8_strcasecmp ()

    gint
    e_util_utf8_strcasecmp (const gchar *s1,
                            const gchar *s2);

Compares two UTF-8 strings using approximate case-insensitive ordering.

#### Parameters

s1 | a UTF-8 string |
s2 | another UTF-8 string |

#### Returns

< 0 if `s1` compares before `s2` , 0 if they compare equal, > 0 if `s1` compares after `s2`

### e_util_utf8_remove_accents ()

    gchar *
    e_util_utf8_remove_accents (const gchar *str);

Returns a newly-allocated copy of `str` with accents removed.

#### Parameters

str | a UTF-8 string, or `NULL` |

#### Returns

a newly-allocated string

Since: 2.28

### e_util_utf8_decompose ()

    gchar *
    e_util_utf8_decompose (const gchar *text);

Converts the `text` into a decomposed variant and strips it, which allows also cheap case insensitive comparision afterwards. This produces an output as being used in `e_util_utf8_strstrcasedecomp()`.

#### Parameters

text | a UTF-8 string |

#### Returns

A newly allocated string, a decomposed variant of the `text` . Free with `g_free()`, when no longer needed.

[transfer full]

Since: 3.26

### e_util_utf8_make_valid ()

    gchar *
    e_util_utf8_make_valid (const gchar *str);

Returns a newly-allocated copy of `str` , with invalid characters replaced by Unicode replacement characters (U+FFFD). For `NULL` `str` returns newly allocated empty string ("").

#### Parameters

str | a UTF-8 string |

#### Returns

a newly-allocated string

Since: 3.0

### e_util_utf8_data_make_valid ()

    gchar *
    e_util_utf8_data_make_valid (const gchar *data,
                                 gsize data_bytes);

Returns a newly-allocated NULL-terminated string with invalid characters replaced by Unicode replacement characters (U+FFFD). For `NULL` `data` returns newly allocated empty string ("").

#### Parameters

data | UTF-8 binary data |
data_bytes | length of the binary data |

#### Returns

a newly-allocated string

Since: 3.6

### e_util_utf8_normalize ()

    gchar *
    e_util_utf8_normalize (const gchar *str);

Normalizes `str` by making it all lower case and removing any accents from it.

#### Parameters

str | a UTF-8 string |

#### Returns

The normalized version of `str` , or `NULL` if `str` was not valid UTF-8

Since: 3.8

### e_util_ensure_gdbus_string ()

    const gchar *
    e_util_ensure_gdbus_string (const gchar *str,
                                gchar **gdbus_str);

If `str` is a valid UTF-8 string, the function returns `str` and does not set `gdbus_str` .

If `str` is an invalid UTF-8 string, the function calls `e_util_utf8_make_valid()` and points `gdbus_str` to the newly-allocated, valid UTF-8 string, and also returns it. The caller should free the string pointed to by `gdbus_str` with `g_free()`.

If `str` is `NULL`, the function returns an empty string and does not set `gdbus_str` .

Admittedly, the function semantics are a little awkward. The example below illustrates the easiest way to cope with the `gdbus_str` argument:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    const gchar *trusted_utf8;
    gchar *allocated = NULL;

    trusted_utf8 = e_util_ensure_gdbus_string (untrusted_utf8, &allocated);

    Do stuff with trusted_utf8, then clear it.

    trusted_utf8 = NULL;

    g_free (allocated);
    allocated = NULL;

#### Parameters

str | a possibly invalid UTF-8 string, or `NULL` |
gdbus_str | return location for the corrected string |

#### Returns

a valid UTF-8 string

Since: 3.0

### e_util_gthread_id ()

    guint64
    e_util_gthread_id (GThread *thread);

Returns a 64-bit integer hopefully uniquely identifying the thread. To be used in debugging output and logging only. The returned value is just a cast of a pointer to the 64-bit integer.

There is no guarantee that calling `e_util_gthread_id()` on one thread first and later after that thread has dies on another won't return the same integer.

On Linux and Win32, known to really return a unique id for each thread existing at a certain time. No guarantee that ids won't be reused after a thread has terminated, though.

#### Parameters

thread | A GThread pointer |

#### Returns

A 64-bit integer.

Since: 2.32

### e_filename_make_safe ()

    void
    e_filename_make_safe (gchar *string);

### e_filename_mkdir_encoded ()

    gchar *
    e_filename_mkdir_encoded (const gchar *basepath,
                              const gchar *fileprefix,
                              const gchar *filename,
                              gint fileindex);

Creates a local path constructed from `basepath` / `fileprefix` + "-" + `filename` , and makes sure the path `basepath` exists. If creation of the path fails, then NULL is returned.

#### Parameters

basepath | base path of a file name; this is left unchanged |
fileprefix | prefix for the filename; this is encoded |
filename | file name to use; this is encoded; can be `NULL` |
fileindex | used when `filename` is NULL, then the filename is generated as "file" + fileindex |

#### Returns

Full local path like `g_build_filename()` except that `fileprefix` and `filename` are encoded to create a proper file elements for a file system. Free returned pointer with `g_free()`.

Since: 3.4

### e_utf8_strftime ()

    gsize
    e_utf8_strftime (gchar *string,
                     gsize max,
                     const gchar *fmt,
                     const struct tm *tm);

The UTF-8 equivalent of `e_strftime()`.

#### Parameters

string | The string array to store the result in. |
max | The size of array `s` . |
fmt | The formatting to use on `tm` . |
tm | The time value to format. |

#### Returns

The number of characters placed in `s` .

### e_strftime ()

    gsize
    e_strftime (gchar *string,
                gsize max,
                const gchar *fmt,
                const struct tm *tm);

This function is a wrapper around the strftime (3) function, which converts the %l and %k (12h and 24h) format variables if necessary.

#### Parameters

string | The string array to store the result in. |
max | The size of array `s` . |
fmt | The formatting to use on `tm` . |
tm | The time value to format. |

#### Returns

The number of characters placed in `s` .

### e_util_slist_to_strv ()

    gchar **
    e_util_slist_to_strv (const GSList *strings);

Convert list of strings into NULL-terminates array of strings.

#### Parameters

strings | a GSList of strings (const gchar *). | [element-type utf8]

#### Returns

Newly allocated `NULL`-terminated array of strings. Returned pointer should be freed with `g_strfreev()`.

Note: Pair function for this is `e_util_strv_to_slist()`.

[transfer full]

Since: 3.4

### e_util_strv_to_slist ()

    GSList *
    e_util_strv_to_slist (const gchar * const *strv);

Convert NULL-terminated array of strings to a list of strings.

#### Parameters

strv | a NULL-terminated array of strings (const gchar *) |

#### Returns

Newly allocated GSList of newly allocated strings. The returned pointer should be freed with `e_util_free_string_slist()`.

Note: Pair function for this is `e_util_slist_to_strv()`.

[transfer full][element-type utf8]

Since: 3.4

### e_util_free_nullable_object_slist ()

    void
    e_util_free_nullable_object_slist (GSList *objects);

Calls `g_object_unref()` on each member of `objects` if non-`NULL` and then frees also `objects` itself.

#### Parameters

objects | a GSList of nullable GObjects. | [element-type GObject]

Since: 3.6

### e_util_safe_free_string ()

    void
    e_util_safe_free_string (gchar *str);

Calls `g_free()` on `string` , but before it rewrites its content with zeros. This is suitable to free strings with passwords.

#### Parameters

str | a string to free |

Since: 3.16

### e_queue_transfer ()

    void
    e_queue_transfer (GQueue *src_queue,
                      GQueue *dst_queue);

Transfers the contents of `src_queue` to the tail of `dst_queue` . When the operation is complete, `src_queue` will be empty.

#### Parameters

src_queue | a source GQueue |
dst_queue | a destination GQueue |

Since: 3.8

### e_weak_ref_new ()

    GWeakRef *
    e_weak_ref_new (gpointer object);

Allocates a new GWeakRef and calls `g_weak_ref_set()` with `object` .

Free the returned GWeakRef with `e_weak_ref_free()`.

[skip]

#### Parameters

object | a GObject or `NULL`. | [allow-none]

#### Returns

a new GWeakRef.

[transfer full]

Since: 3.10

### e_weak_ref_free ()

    void
    e_weak_ref_free (GWeakRef *weak_ref);

Frees a GWeakRef created by `e_weak_ref_new()`.

[skip]

#### Parameters

weak_ref | a GWeakRef |

Since: 3.10

### e_file_recursive_delete_sync ()

    gboolean
    e_file_recursive_delete_sync (GFile *file,
                                  GCancellable *cancellable,
                                  GError **error);

Deletes `file` . If `file` is a directory, its contents are deleted recursively before `file` itself is deleted. The recursive delete operation will stop on the first error.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

#### Parameters

file | a GFile to delete |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the file was deleted, `FALSE` otherwise

Since: 3.6

### e_file_recursive_delete ()

    void
    e_file_recursive_delete (GFile *file,
                             gint io_priority,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Asynchronously deletes `file` . If `file` is a directory, its contents are deleted recursively before `file` itself is deleted. The recursive delete operation will stop on the first error.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the cancellable object before the operation finishes.

When the operation is finished, `callback` will be called. You can then call `e_file_recursive_delete_finish()` to get the result of the operation.

#### Parameters

file | a GFile to delete |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, or `NULL` |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | data to pass to the callback function |

Since: 3.6

### e_file_recursive_delete_finish ()

    gboolean
    e_file_recursive_delete_finish (GFile *file,
                                    GAsyncResult *result,
                                    GError **error);

Finishes the operation started with `e_file_recursive_delete()`.

If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

#### Parameters

file | a GFile to delete |
result | a GAsyncResult. | [transfer full]
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the file was deleted, `FALSE` otherwise

Since: 3.6

### e_binding_bind_property ()

    GBinding *
    e_binding_bind_property (gpointer source,
                             const gchar *source_property,
                             gpointer target,
                             const gchar *target_property,
                             GBindingFlags flags);

Thread safe variant of `g_object_bind_property()`. See its documentation for more information on arguments and return value.

#### Parameters

source | the source GObject. | [type GObject.Object]
source_property | the property on `source` to bind |
target | the target GObject. | [type GObject.Object]
target_property | the property on `target` to bind |
flags | flags to pass to GBinding |

#### Returns

.

[transfer none]

Since: 3.16

### e_binding_bind_property_full ()

    GBinding *
    e_binding_bind_property_full (gpointer source,
                                  const gchar *source_property,
                                  gpointer target,
                                  const gchar *target_property,
                                  GBindingFlags flags,
                                  GBindingTransformFunc transform_to,
                                  GBindingTransformFunc transform_from,
                                  gpointer user_data,
                                  GDestroyNotify notify);

Thread safe variant of `g_object_bind_property_full()`. See its documentation for more information on arguments and return value.

#### Parameters

source | the source GObject. | [type GObject.Object]
source_property | the property on `source` to bind |
target | the target GObject. | [type GObject.Object]
target_property | the property on `target` to bind |
flags | flags to pass to GBinding |
transform_to | the transformation function from the `source` to the `target` , or `NULL` to use the default. | [scope notified][allow-none]
transform_from | the transformation function from the `target` to the `source` , or `NULL` to use the default. | [scope notified][allow-none]
user_data | custom data to be passed to the transformation functions, or `NULL` |
notify | function to be called when disposing the binding, to free the resources used by the transformation functions |

#### Returns

the GBinding instance representing the binding between the two GObject instances. The binding is released whenever the GBinding reference count reaches zero.

[transfer none]

Since: 3.16

### e_binding_bind_property_with_closures ()

    GBinding *
    e_binding_bind_property_with_closures (gpointer source,
                                           const gchar *source_property,
                                           gpointer target,
                                           const gchar *target_property,
                                           GBindingFlags flags,
                                           GClosure *transform_to,
                                           GClosure *transform_from);

Thread safe variant of `g_object_bind_property_with_closures()`. See its documentation for more information on arguments and return value.

[rename-to e_binding_bind_property_full]

#### Parameters

source | the source GObject. | [type GObject.Object]
source_property | the property on `source` to bind |
target | the target GObject. | [type GObject.Object]
target_property | the property on `target` to bind |
flags | flags to pass to GBinding |
transform_to | a GClosure wrapping the transformation function from the `source` to the `target` , or `NULL` to use the default |
transform_from | a GClosure wrapping the transformation function from the `target` to the `source` , or `NULL` to use the default |

#### Returns

the GBinding instance representing the binding between the two GObject instances. The binding is released whenever the GBinding reference count reaches zero.

[transfer none]

Since: 3.16

### e_binding_transform_enum_value_to_nick ()

    gboolean
    e_binding_transform_enum_value_to_nick
                                   (GBinding *binding,
                                    const GValue *source_value,
                                    GValue *target_value,
                                    gpointer not_used);

Transforms an enumeration value to its corresponding nickname.

#### Parameters

binding | a GBinding |
source_value | a GValue whose type is derived from G_TYPE_ENUM |
target_value | a GValue of type G_TYPE_STRING |
not_used | not used |

#### Returns

`TRUE` if the enum value has a corresponding nickname

Since: 3.4

### e_binding_transform_enum_nick_to_value ()

    gboolean
    e_binding_transform_enum_nick_to_value
                                   (GBinding *binding,
                                    const GValue *source_value,
                                    GValue *target_value,
                                    gpointer not_used);

Transforms an enumeration nickname to its corresponding value.

#### Parameters

binding | a GBinding |
source_value | a GValue of type G_TYPE_STRING |
target_value | a GValue whose type is derived from G_TYPE_ENUM |
not_used | not used |

#### Returns

`TRUE` if the enum nickname has a corresponding value

Since: 3.4

### e_enum_from_string ()

    gboolean
    e_enum_from_string (GType enum_type,
                        const gchar *string,
                        gint *enum_value);

Fetches the appropriate enumeration value for `string` in the given enum type `type` and stores the result in `enum_value`

#### Parameters

enum_type | The enum type |
string | The string containing the enum value or nick |
enum_value | A return location to store the result |

#### Returns

`TRUE` if the string was a valid name or nick for the given `type` , `FALSE` if the conversion failed.

Since: 3.8

### e_enum_to_string ()

    const gchar *
    e_enum_to_string (GType enum_type,
                      gint enum_value);

Converts an enum value to a string using strings from the GType system.

#### Parameters

enum_type | An enum type |
enum_value | The enum value to convert |

#### Returns

the string representing `eval`

Since: 3.8

### e_async_closure_new ()

    EAsyncClosure *
    e_async_closure_new (void);

Creates a new EAsyncClosure for use with asynchronous functions.

[skip]

#### Returns

a new EAsyncClosure

Since: 3.6

### e_async_closure_new_with_context ()

    EAsyncClosure *
    e_async_closure_new_with_context (GMainContext *context);

Creates a new EAsyncClosure for use with asynchronous functions using the `context` as the main context.

[skip]

#### Parameters

context | a GMainContext to use, or `NULL` to use the default context. | [nullable]

#### Returns

a new EAsyncClosure

Since: 3.40

### e_async_closure_wait ()

    GAsyncResult *
    e_async_closure_wait (EAsyncClosure *closure);

Call this function immediately after starting an asynchronous operation. The function waits for the asynchronous operation to complete and returns its GAsyncResult to be passed to the operation's "finish" function.

This function can be called repeatedly on the same EAsyncClosure to easily string together multiple asynchronous operations.

[skip]

#### Parameters

closure | an EAsyncClosure |

#### Returns

a GAsyncResult which is owned by the closure.

[transfer none]

Since: 3.6

### e_async_closure_free ()

    void
    e_async_closure_free (EAsyncClosure *closure);

Frees the `closure` and the resources it holds.

[skip]

#### Parameters

closure | an EAsyncClosure |

Since: 3.6

### e_async_closure_callback ()

    void
    e_async_closure_callback (GObject *object,
                              GAsyncResult *result,
                              gpointer closure);

Pass this function as the GAsyncReadyCallback argument of an asynchronous function, and the EAsyncClosure as the data argument.

This causes `e_async_closure_wait()` to terminate and return `result` .

[skip]

#### Parameters

object | a GObject or `NULL`, it is not used by the function at all |
result | a GAsyncResult |
closure | an EAsyncClosure |

Since: 3.6

### e_util_get_prefix ()

    const gchar *
    e_util_get_prefix (void);

### e_util_get_cp_prefix ()

    const gchar *
    e_util_get_cp_prefix (void);

### e_util_get_localedir ()

    const gchar *
    e_util_get_localedir (void);

### e_util_replace_prefix ()

    gchar *
    e_util_replace_prefix (const gchar *configure_time_prefix,
                           const gchar *runtime_prefix,
                           const gchar *configure_time_path);

### e_util_win32_initialize ()

    void
    e_util_win32_initialize (void);

Initializes win32 environment. This might be called in `main()`.

### e_named_parameters_new ()

    ENamedParameters *
    e_named_parameters_new (void);

Creates a new instance of an ENamedParameters. This should be freed with `e_named_parameters_free()`, when no longer needed. Names are compared case insensitively.

The structure is not thread safe, if the caller requires thread safety, then it should provide it on its own.

#### Returns

newly allocated ENamedParameters

Since: 3.8

### e_named_parameters_new_strv ()

    ENamedParameters *
    e_named_parameters_new_strv (const gchar * const *strv);

Creates a new instance of an ENamedParameters, with initial content being taken from `strv` . This should be freed with `e_named_parameters_free()`, when no longer needed. Names are compared case insensitively.

The structure is not thread safe, if the caller requires thread safety, then it should provide it on its own.

#### Parameters

strv | NULL-terminated string array to be used as a content of a newly created ENamedParameters |

#### Returns

newly allocated ENamedParameters

Since: 3.8

### e_named_parameters_new_string ()

    ENamedParameters *
    e_named_parameters_new_string (const gchar *str);

Creates a new instance of an ENamedParameters, with initial content being taken from `str` . This should be freed with `e_named_parameters_free()`, when no longer needed. Names are compared case insensitively.

The `str` should be created with `e_named_parameters_to_string()`, to be properly encoded.

The structure is not thread safe, if the caller requires thread safety, then it should provide it on its own.

#### Parameters

str | a string to be used as a content of a newly created ENamedParameters |

#### Returns

newly allocated ENamedParameters.

[transfer full]

Since: 3.18

### e_named_parameters_new_clone ()

    ENamedParameters *
    e_named_parameters_new_clone (const ENamedParameters *parameters);

Creates a new instance of an ENamedParameters, with initial content being taken from `parameters` . This should be freed with `e_named_parameters_free()`, when no longer needed. Names are compared case insensitively.

The structure is not thread safe, if the caller requires thread safety, then it should provide it on its own.

#### Parameters

parameters | an ENamedParameters to be used as a content of a newly created ENamedParameters |

#### Returns

newly allocated ENamedParameters

Since: 3.16

### e_named_parameters_free ()

    void
    e_named_parameters_free (ENamedParameters *parameters);

Frees an instance of ENamedParameters, previously allocated with `e_named_parameters_new()`. Function does nothing, if `parameters` is `NULL`.

#### Parameters

parameters | an ENamedParameters. | [nullable]

Since: 3.8

### e_named_parameters_clear ()

    void
    e_named_parameters_clear (ENamedParameters *parameters);

Removes all stored parameters from `parameters` .

#### Parameters

parameters | an ENamedParameters |

Since: 3.8

### e_named_parameters_assign ()

    void
    e_named_parameters_assign (ENamedParameters *parameters,
                               const ENamedParameters *from);

Makes content of the `parameters` the same as `from` . Functions clears content of `parameters` if `from` is `NULL`.

#### Parameters

parameters | an ENamedParameters to assign values to |
from | an ENamedParameters to get values from, or `NULL`. | [allow-none]

Since: 3.8

### e_named_parameters_set ()

    void
    e_named_parameters_set (ENamedParameters *parameters,
                            const gchar *name,
                            const gchar *value);

Sets parameter named `name` to value `value` . If `value` is NULL, then the parameter is removed. `value` can be an empty string.

Note: There is a restriction on parameter names, it cannot be empty or contain a colon character (':'), otherwise it can be pretty much anything.

#### Parameters

parameters | an ENamedParameters |
name | name of a parameter to set |
value | value to set, or `NULL` to unset. | [allow-none]

Since: 3.8

### e_named_parameters_get ()

    const gchar *
    e_named_parameters_get (const ENamedParameters *parameters,
                            const gchar *name);

Returns current value of a parameter with name `name` . If not such exists, then returns `NULL`.

#### Parameters

parameters | an ENamedParameters |
name | name of a parameter to get |

#### Returns

value of a parameter named `name` , or `NULL`.

Since: 3.8

### e_named_parameters_to_strv ()

    gchar **
    e_named_parameters_to_strv (const ENamedParameters *parameters);

#### Parameters

parameters | an ENamedParameters |

#### Returns

Contents of `parameters` as a null-terminated strv.

[transfer full]

Since: 3.8

### e_named_parameters_to_string ()

    gchar *
    e_named_parameters_to_string (const ENamedParameters *parameters);

#### Parameters

parameters | an ENamedParameters |

#### Returns

Contents of `parameters` as a string.

[transfer full]

Since: 3.18

### e_named_parameters_test ()

    gboolean
    e_named_parameters_test (const ENamedParameters *parameters,
                             const gchar *name,
                             const gchar *value,
                             gboolean case_sensitively);

Compares current value of parameter named `name` with given `value` and returns whether they are equal, either case sensitively or insensitively, based on `case_sensitively` argument. Function returns `FALSE`, if no such parameter exists.

#### Parameters

parameters | an ENamedParameters |
name | name of a parameter to test |
value | value to test |
case_sensitively | whether to compare case sensitively |

#### Returns

Whether parameter of given name has stored value of given value.

Since: 3.8

### e_named_parameters_exists ()

    gboolean
    e_named_parameters_exists (const ENamedParameters *parameters,
                               const gchar *name);

#### Parameters

parameters | an ENamedParameters |
name | name of the parameter whose existence to check |

#### Returns

Whether `parameters` holds a parameter named `name`

Since: 3.18

### e_named_parameters_count ()

    guint
    e_named_parameters_count (const ENamedParameters *parameters);

#### Parameters

parameters | an ENamedParameters |

#### Returns

The number of stored named parameters in `parameters`

Since: 3.18

### e_named_parameters_get_name ()

    gchar *
    e_named_parameters_get_name (const ENamedParameters *parameters,
                                 gint index);

#### Parameters

parameters | an ENamedParameters |
index | an index of the parameter whose name to retrieve |

#### Returns

The name of the parameters at index `index` , or `NULL`, of the `index` is out of bounds or other error. The returned string should be freed with `g_free()` when done with it.

[transfer full]

Since: 3.18

### e_named_timeout_add()

    #define             e_named_timeout_add(interval, function, data)

Similar to `g_timeout_add()`, but also names the GSource for use in debugging and profiling. The name is formed from `function` and the `PACKAGE` definintion from a <config.h> file.

#### Parameters

interval | the time between calls to the function, in milliseconds (1/1000ths of a second) |
function | function to call |
data | data to pass to `function` |

#### Returns

the ID (greater than 0) of the event source

Since: 3.12

### e_named_timeout_add_full()

    #define             e_named_timeout_add_full(priority, interval, function, data, notify)

Similar to `g_timeout_add_full()`, but also names the GSource for use in debugging and profiling. The name is formed from `function` and the `PACKAGE` definition from a <config.h> file.

#### Parameters

priority | the priority of the timeout source, typically in the range between G_PRIORITY_DEFAULT and G_PRIORITY_HIGH |
interval | the time between calls to the function, in milliseconds (1/1000ths of a second) |
function | function to call |
data | data to pass to `function` |
notify | function to call when the timeout is removed, or `NULL` |

#### Returns

the ID (greater than 0) of the event source

Since: 3.12

### e_named_timeout_add_seconds()

    #define             e_named_timeout_add_seconds(interval, function, data)

Similar to `g_timeout_add_seconds()`, but also names the GSource for use in debugging and profiling. The name is formed from `function` and the `PACKAGE` definition from a <config.h> file.

#### Parameters

interval | the time between calls to the function, in seconds |
function | function to call |
data | data to pass to `function` |

#### Returns

the ID (greater than 0) of the event source

Since: 3.12

### e_named_timeout_add_seconds_full()

    #define             e_named_timeout_add_seconds_full(priority, interval, function, data, notify)

Similar to `g_timeout_add_seconds_full()`, but also names the GSource for use in debugging and profiling. The name is formed from `function` and the `PACKAGE` definition from a <config.h> file.

#### Parameters

priority | the priority of the timeout source, typically in the range between G_PRIORITY_DEFAULT and G_PRIORITY_HIGH |
interval | the time between calls to the function, in seconds |
function | function to call |
data | data to pass to `function` |
notify | function to call when the timeout is removed, or `NULL` |

#### Returns

the ID (greater than 0) of the event source

Since: 3.12

### e_timeout_add_with_name ()

    guint
    e_timeout_add_with_name (gint priority,
                             guint interval,
                             const gchar *name,
                             GSourceFunc function,
                             gpointer data,
                             GDestroyNotify notify);

Similar to `g_timeout_add_full()`, but also names the GSource as `name` .

You might find `e_named_timeout_add()` or `e_named_timeout_add_full()` more convenient. Those macros name the GSource implicitly.

#### Parameters

priority | the priority of the timeout source, typically in the range between G_PRIORITY_DEFAULT and G_PRIORITY_HIGH |
interval | the time between calls to the function, in milliseconds (1/1000ths of a second) |
name | debug name for the source. | [allow-none]
function | function to call |
data | data to pass to `function` |
notify | function to call when the timeout is removed, or `NULL`. | [allow-none]

#### Returns

the ID (greather than 0) of the event source

Since: 3.12

### e_timeout_add_seconds_with_name ()

    guint
    e_timeout_add_seconds_with_name (gint priority,
                                     guint interval,
                                     const gchar *name,
                                     GSourceFunc function,
                                     gpointer data,
                                     GDestroyNotify notify);

Similar to `g_timeout_add_seconds_full()`, but also names the GSource as `name` .

You might find `e_named_timeout_add_seconds()` or `e_named_timeout_add_seconds_full()` more convenient. Those macros name the GSource implicitly.

#### Parameters

priority | the priority of the timeout source, typically in the range between G_PRIORITY_DEFAULT and G_PRIORITY_HIGH |
interval | the time between calls to the function, in seconds |
name | debug name for the source. | [allow-none]
function | function to call |
data | data to pass to `function` |
notify | function to call when the timeout is removed, or `NULL`. | [allow-none]

#### Returns

the ID (greater than 0) of the event source

Since: 3.12

### e_util_free_string_slist ()

    void
    e_util_free_string_slist (GSList *strings);

`e_util_free_string_slist` has been deprecated since version 3.8 and should not be used in newly-written code.

Use `g_slist_free_full()` instead.

Frees memory previously allocated by `e_util_strv_to_slist()`.

#### Parameters

strings | a GSList of strings (gchar *). | [element-type utf8]

Since: 3.4

### e_util_free_object_slist ()

    void
    e_util_free_object_slist (GSList *objects);

`e_util_free_object_slist` has been deprecated since version 3.8 and should not be used in newly-written code.

Use `g_slist_free_full()` instead.

Calls `g_object_unref()` on each member of `objects` and then frees also `objects` itself.

#### Parameters

objects | a GSList of GObjects. | [element-type GObject]

Since: 3.4

### e_util_copy_string_slist ()

    GSList *
    e_util_copy_string_slist (GSList *copy_to,
                              const GSList *strings);

`e_util_copy_string_slist` has been deprecated since version 3.8 and should not be used in newly-written code.

Use `g_slist_copy_deep()` instead, and optionally `g_slist_concat()` to concatenate the copied list to another GSList.

Copies GSList of strings at the end of `copy_to` .

#### Parameters

copy_to | Where to copy; can be `NULL`. | [element-type utf8][allow-none]
strings | GSList of strings to be copied. | [element-type utf8]

#### Returns

New head of `copy_to` . Returned pointer can be freed with `e_util_free_string_slist()`.

[transfer full][element-type utf8]

Since: 3.4

### e_util_copy_object_slist ()

    GSList *
    e_util_copy_object_slist (GSList *copy_to,
                              const GSList *objects);

`e_util_copy_object_slist` has been deprecated since version 3.8 and should not be used in newly-written code.

Use `g_slist_copy_deep()` instead, and optionally `g_slist_concat()` to concatenate the copied list to another GSList.

Copies GSList of GObjects at the end of `copy_to` .

#### Parameters

copy_to | Where to copy; can be `NULL`. | [element-type GObject][allow-none]
objects | GSList of GObjects to be copied. | [element-type GObject]

#### Returns

New head of `copy_to` . Returned pointer can be freed with `e_util_free_object_slist()`.

[transfer full][element-type GObject]

Since: 3.4

### e_data_server_util_get_dbus_call_timeout ()

    gint
    e_data_server_util_get_dbus_call_timeout
                                   (void);

`e_data_server_util_get_dbus_call_timeout` has been deprecated since version 3.8 and should not be used in newly-written code.

This value is not used anywhere.

Returns the value set by `e_data_server_util_set_dbus_call_timeout()`.

#### Returns

the D-Bus call timeout in milliseconds

Since: 3.0

### e_data_server_util_set_dbus_call_timeout ()

    void
    e_data_server_util_set_dbus_call_timeout
                                   (gint timeout_msec);

`e_data_server_util_set_dbus_call_timeout` has been deprecated since version 3.8 and should not be used in newly-written code.

This value is not used anywhere.

Sets default timeout, in milliseconds, for calls of `g_dbus_proxy_call()` family functions.

-1 means the default value as set by D-Bus itself. G_MAXINT means no timeout at all.

Default value is set also by configure option --with-dbus-call-timeout=ms and -1 is used when not set.

#### Parameters

timeout_msec | default timeout for D-Bus calls in miliseconds |

Since: 3.0

### e_source_registry_debug_enabled ()

    gboolean
    e_source_registry_debug_enabled (void);

#### Returns

Whether debugging is enabled, that is, whether `e_source_registry_debug_print()` will produce any output.

Since: 3.16

### e_source_registry_debug_print ()

    void
    e_source_registry_debug_print (const gchar *format,
                                   ...);

Prints the text only if a debugging is enabled with an environment variable ESR_DEBUG=1.

#### Parameters

format | a format string to print |
... | other arguments for the format |

Since: 3.16

### e_util_debug_print ()

    void
    e_util_debug_print (const gchar *domain,
                        const gchar *format,
                        ...);

Prints a text according to `format` and its arguments to stdout prefixed with `domain` in brackets [] and the current date and time. This function doesn't check whether the logging is enabled, it's up to the caller to determine it, the function only prints the information in a consistent format: [domain] YYYY-MM-DD hh:mm:ss.ms - format

See: `e_util_debug_printv()`

#### Parameters

domain | a debug domain |
format | a printf-like format |
... | arguments for the `format` |

Since: 3.30

### e_util_debug_printv ()

    void
    e_util_debug_printv (const gchar *domain,
                         const gchar *format,
                         va_list args);

Prints a text according to `format` and its `args` to stdout prefixed with `domain` in brackets [] and the current date and time. This function doesn't check whether the logging is enabled, it's up to the caller to determine it, the function only prints the information in a consistent form: [`domain` ] YYYY-MM-DD hh:mm:ss.ms - `format`

See: `e_util_debug_print()`

#### Parameters

domain | a debug domain |
format | a printf-like format |
args | arguments for the `format` |

Since: 3.30

### ETypeFunc ()

    void
    (*ETypeFunc) (GType type,
                  gpointer user_data);

Specifies the type of functions passed to `e_type_traverse()`.

#### Parameters

type | a GType |
user_data | user data passed to `e_type_traverse()` |

Since: 3.4

### e_type_traverse ()

    void
    e_type_traverse (GType parent_type,
                     ETypeFunc func,
                     gpointer user_data);

Calls `func` for all instantiable subtypes of `parent_type` .

This is often useful for extending functionality by way of EModule. A module may register a subtype of `parent_type` in its `e_module_load()` function. Then later on the application will call `e_type_traverse()` to instantiate all registered subtypes of `parent_type` .

#### Parameters

parent_type | the root GType to traverse from |
func | the function to call for each visited GType. | [scope call]
user_data | user data to pass to the function |

Since: 3.4

### e_util_get_source_full_name ()

    gchar *
    e_util_get_source_full_name (struct _ESourceRegistry *registry,
                                 struct _ESource *source);

Constructs a full name of the `source` with all of its parents of the form: "<account-name> : <parent>/<source>" where the "<parent>/" part can be repeated zero or more times, depending on the deep level of the `source` .

#### Parameters

registry | an ESourceRegistry |
source | an ESource |

#### Returns

Full name of the `source` as a newly allocated string, which should be freed with `g_free()` when done with it.

Since 3.18.

[transfer full]

### e_util_unref_in_thread ()

    void
    e_util_unref_in_thread (gpointer object);

Unrefs the given `object` in a dedicated thread. This is useful when unreffing object deep in call stack when the caller might still use the object and this being the last reference to it.

#### Parameters

object | a GObject |

Since: 3.26

### e_util_generate_uid ()

    gchar *
    e_util_generate_uid (void);

Generates a unique identificator, which can be used as part of the Message-ID header, or iCalendar component UID, or vCard UID. The resulting string doesn't contain any host name, it's a hexa-decimal string with no particular meaning.

Free the returned string with `g_free()`, when no longer needed.

#### Returns

generated unique identificator as a newly allocated string.

[transfer full]

Since: 3.26

### e_util_identity_can_send ()

    gboolean
    e_util_identity_can_send (struct _ESourceRegistry *registry,
                              struct _ESource *identity_source);

Checks whether the `identity_source` can be used for sending, which means whether it has configures send mail source.

#### Parameters

registry | an ESourceRegistry |
identity_source | an ESource with mail identity extension |

#### Returns

Whether `identity_source` can be used to send messages

Since: 3.26

### e_util_can_use_collection_as_credential_source ()

    gboolean
    e_util_can_use_collection_as_credential_source
                                   (struct _ESource *collection_source,
                                    struct _ESource *child_source);

Checks whether the `collection_source` can be used as a credential source for the `child_source` . The relationship is not tested in the function. When the `collection_source` is `NULL`, then it simply returns `FALSE`.

#### Parameters

collection_source | a collection ESource, or `NULL`. | [nullable]
child_source | a children of `collection_source` |

#### Returns

whether `collection_source` can be used as a credential source for `child_source` , that is, whether they share credentials.

Since: 3.28

### e_util_source_compare_for_sort ()

    gint
    e_util_source_compare_for_sort (struct _ESource *source_a,
                                    struct _ESource *source_b);

Compares two ESource-s in a way suitable for user interface. It can be used as a GCompareFunc.

This is also used by `e_source_registry_build_display_tree()`.

#### Parameters

source_a | the first ESource |
source_b | the second ESource |

#### Returns

an integer less than, equal to, or greater than zero, if `source_a` is <, == or > than `source_b` .

Since: 3.40

### e_util_get_directory_variants ()

    GPtrArray *
    e_util_get_directory_variants (const gchar *main_path,
                                   const gchar *replace_prefix,
                                   gboolean with_modules_dir);

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 `g_get_user_data_dir()` + "evolution/modules/", aka ~/.local/share/evolution/modules/, into the resulting array.

#### Parameters

main_path | the main path to work with |
replace_prefix | path prefix to replace |
with_modules_dir | whether to add also the modules directory |

#### Returns

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

[element-type utf8][transfer container]

Since: 3.40

## Types and Values

### EAsyncClosure

    typedef struct _EAsyncClosure EAsyncClosure;

EAsyncClosure provides a simple way to run an asynchronous function synchronously without blocking a running GMainLoop or using threads.

1) Create an EAsyncClosure with `e_async_closure_new()`.

2) Call the asynchronous function passing `e_async_closure_callback()` as the GAsyncReadyCallback argument and the EAsyncClosure as the data argument.

3) Call `e_async_closure_wait()` and collect the GAsyncResult.

4) Call the corresponding asynchronous "finish" function, passing the GAsyncResult returned by `e_async_closure_wait()`.

5) If needed, repeat steps 2-4 for additional asynchronous functions using the same EAsyncClosure.

6) Finally, free the EAsyncClosure with `e_async_closure_free()`.

Since: 3.6

### ENamedParameters

    typedef struct _ENamedParameters ENamedParameters;

Since: 3.8

### struct tm

    struct tm;