## Main Utility Toolbox

Main Utility Toolbox

## Synopsis

    const gchar *       e_get_user_cache_dir                (void);
    const gchar *       e_get_user_config_dir               (void);
    const gchar *       e_get_user_data_dir                 (void);
    gboolean            e_util_strv_equal                   (gconstpointer v1,
                                                             gconstpointer v2);
    gchar *             e_util_strdup_strip                 (const gchar *string);
    gchar *             e_util_strstrcase                   (const gchar *haystack,
                                                             const gchar *needle);
    gchar *             e_util_unicode_get_utf8             (const gchar *text,
                                                             gunichar *out);
    const gchar *       e_util_utf8_strstrcase              (const gchar *haystack,
                                                             const gchar *needle);
    const gchar *       e_util_utf8_strstrcasedecomp        (const gchar *haystack,
                                                             const gchar *needle);
    gint                e_util_utf8_strcasecmp              (const gchar *s1,
                                                             const gchar *s2);
    gchar *             e_util_utf8_remove_accents          (const gchar *str);
    gchar *             e_util_utf8_make_valid              (const gchar *str);
    gchar *             e_util_utf8_data_make_valid         (const gchar *data,
                                                             gsize data_bytes);
    gchar *             e_util_utf8_normalize               (const gchar *str);
    const gchar *       e_util_ensure_gdbus_string          (const gchar *str,
                                                             gchar **gdbus_str);
    guint64             e_util_gthread_id                   (GThread *thread);
    void                e_filename_make_safe                (gchar *string);
    gchar *             e_filename_mkdir_encoded            (const gchar *basepath,
                                                             const gchar *fileprefix,
                                                             const gchar *filename,
                                                             gint fileindex);
    gsize               e_utf8_strftime                     (gchar *string,
                                                             gsize max,
                                                             const gchar *fmt,
                                                             const struct tm *tm);
    gsize               e_strftime                          (gchar *string,
                                                             gsize max,
                                                             const gchar *fmt,
                                                             const struct tm *tm);
    gchar **            e_util_slist_to_strv                (const GSList *strings);
    GSList *            e_util_strv_to_slist                (const gchar * const *strv);
    void                e_util_free_nullable_object_slist   (GSList *objects);
    void                e_queue_transfer                    (GQueue *src_queue,
                                                             GQueue *dst_queue);
    GWeakRef *          e_weak_ref_new                      (gpointer object);
    void                e_weak_ref_free                     (GWeakRef *weak_ref);
    gboolean            e_file_recursive_delete_sync        (GFile *file,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_file_recursive_delete             (GFile *file,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_file_recursive_delete_finish      (GFile *file,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_binding_transform_enum_value_to_nick
                                                            (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             gpointer not_used);
    gboolean            e_binding_transform_enum_nick_to_value
                                                            (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             gpointer not_used);
    gboolean            e_enum_from_string                  (GType enum_type,
                                                             const gchar *string,
                                                             gint *enum_value);
    const gchar *       e_enum_to_string                    (GType enum_type,
                                                             gint enum_value);
    EAsyncClosure *     e_async_closure_new                 (void);
    GAsyncResult *      e_async_closure_wait                (EAsyncClosure *closure);
    void                e_async_closure_free                (EAsyncClosure *closure);
    void                e_async_closure_callback            (GObject *object,
                                                             GAsyncResult *result,
                                                             gpointer closure);
    const gchar *       e_util_get_prefix                   (void);
    const gchar *       e_util_get_cp_prefix                (void);
    const gchar *       e_util_get_localedir                (void);
    gchar *             e_util_replace_prefix               (const gchar *configure_time_prefix,
                                                             const gchar *runtime_prefix,
                                                             const gchar *configure_time_path);
    ENamedParameters *  e_named_parameters_new              (void);
    ENamedParameters *  e_named_parameters_new_strv         (const gchar * const *strv);
    void                e_named_parameters_free             (ENamedParameters *parameters);
    void                e_named_parameters_clear            (ENamedParameters *parameters);
    void                e_named_parameters_assign           (ENamedParameters *parameters,
                                                             const ENamedParameters *from);
    void                e_named_parameters_set              (ENamedParameters *parameters,
                                                             const gchar *name,
                                                             const gchar *value);
    const gchar *       e_named_parameters_get              (const ENamedParameters *parameters,
                                                             const gchar *name);
    gchar **            e_named_parameters_to_strv          (const ENamedParameters *parameters);
    gboolean            e_named_parameters_test             (const ENamedParameters *parameters,
                                                             const gchar *name,
                                                             const gchar *value,
                                                             gboolean case_sensitively);
    #define             e_named_timeout_add                 (interval,
                                                             function,
                                                             data)
    #define             e_named_timeout_add_full            (priority,
                                                             interval,
                                                             function,
                                                             data,
                                                             notify)
    #define             e_named_timeout_add_seconds         (interval,
                                                             function,
                                                             data)
    #define             e_named_timeout_add_seconds_full    (priority,
                                                             interval,
                                                             function,
                                                             data,
                                                             notify)
    guint               e_timeout_add_with_name             (gint priority,
                                                             guint interval,
                                                             const gchar *name,
                                                             GSourceFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    guint               e_timeout_add_seconds_with_name     (gint priority,
                                                             guint interval,
                                                             const gchar *name,
                                                             GSourceFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    void                e_util_free_string_slist            (GSList *strings);
    void                e_util_free_object_slist            (GSList *objects);
    GSList *            e_util_copy_string_slist            (GSList *copy_to,
                                                             const GSList *strings);
    GSList *            e_util_copy_object_slist            (GSList *copy_to,
                                                             const GSList *objects);
    gint                e_data_server_util_get_dbus_call_timeout
                                                            (void);
    void                e_data_server_util_set_dbus_call_timeout
                                                            (gint timeout_msec);
                        ENamedParameters;
                        EAsyncClosure;
    struct              tm;

## Description

## Details

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

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

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

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

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

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

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

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

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

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

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

`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;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`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` : | an ENamedParameters

Since 3.8

### e_named_parameters_clear ()

    void                e_named_parameters_clear            (ENamedParameters *parameters);

Removes all stored parameters from `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` : | 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` : | 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` : | 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` : | 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` : | 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.

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

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

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

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

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

`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);

### Warning

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

`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);

### Warning

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

`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);

### Warning

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

`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);

### Warning

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

`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);

### Warning

`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);

### Warning

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

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

Since 3.0

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