## Main Utility Toolbox

Main Utility Toolbox

## 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 ()
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_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_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 ()
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 ()
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 ()
ENamedParameters * | e_named_parameters_new ()
ENamedParameters * | e_named_parameters_new_strv ()
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 ()
gboolean | e_named_parameters_test ()
#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 ()

## Types and Values

| ENamedParameters
| EAsyncClosure
struct | tm

## 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_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_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_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()`.

#### Parameters

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

#### Returns

a new GWeakRef

Since 3.10

### e_weak_ref_free ()

    void
    e_weak_ref_free (GWeakRef *weak_ref);

Frees a GWeakRef created by `e_weak_ref_new()`.

#### 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 |
error | return location for a GError, or `NULL` |

#### Returns

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

Since 3.6

### 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.

#### Returns

a new EAsyncClosure

Since 3.6

### 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.

#### 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.

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

#### 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_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_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 |

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_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_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

## Types and Values

### ENamedParameters

    typedef struct _ENamedParameters ENamedParameters;

Since 3.8

### 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

### struct tm

    struct tm;