e-util

## e-util e-util |

## Synopsis

    struct              tm;
    const gchar *       e_get_user_cache_dir                (void);
    const gchar *       e_get_user_config_dir               (void);
    const gchar *       e_get_user_data_dir                 (void);
    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);
    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);
    GSList *            e_util_copy_string_slist            (GSList *copy_to,
                                                             const GSList *strings);
    GSList *            e_util_copy_object_slist            (GSList *copy_to,
                                                             const GSList *objects);
    void                e_util_free_string_slist            (GSList *strings);
    void                e_util_free_object_slist            (GSList *objects);
    void                e_util_free_nullable_object_slist   (GSList *objects);
    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);
                        EAsyncClosure;
    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);
    gint                e_data_server_util_get_dbus_call_timeout
                                                            (void);
    void                e_data_server_util_set_dbus_call_timeout
                                                            (gint timeout_msec);

## Description

## Details

### struct tm

    struct tm;

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

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

`data` : | UTF-8 binary data
`data_bytes` : | length of the binary data
Returns : | a newly-allocated string

Since 3.6

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

<informalexample> <programlisting> 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; </programlisting> </informalexample>

`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 &percnt;l and &percnt;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_copy_string_slist ()

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

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

Copies GSList of GObject<!-- -->s at the end of `copy_to`.

`copy_to` : | Where to copy; can be `NULL`. [element-type GObject][allow-none]
`objects` : | GSList of GObject<!-- -->s 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_util_free_string_slist ()

    void                e_util_free_string_slist            (GSList *strings);

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

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

`objects` : | a GSList of GObject<!-- -->s. [element-type GObject]

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 GObject<!-- -->s. [element-type GObject]

Since 3.6

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

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

### 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_data_server_util_get_dbus_call_timeout ()

    gint                e_data_server_util_get_dbus_call_timeout
                                                            (void);

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

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