e-util

e-util

Functions

Types and Values

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

Parameters

str

a UTF-8 string

 

Returns

a newly-allocated string

Since 3.0


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>

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

 

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. Returned pointer should be freed with e_util_free_string_slist().

Note: Pair function for this is e_util_slist_to_strv().

[transfer full]

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 .

Parameters

copy_to

Where to copy; can be NULL

 

strings

GSList of strings to be copied

 

Returns

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

[transfer full]

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 .

Parameters

copy_to

Where to copy; can be NULL

 

objects

GSList of GObject-s to be copied

 

Returns

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

[transfer full]

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

Parameters

strings

a GSList of strings (gchar *)

 

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.

Parameters

objects

a GSList of GObject-s

 

Since 3.4


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

Parameters

timeout_msec

default timeout for D-Bus calls in miliseconds

 

Since 3.0


e_pointer_tracker_track()

#define             e_pointer_tracker_track(ptr)

FIXME: Document me.

Since 3.2


e_pointer_tracker_track_with_info ()

void
e_pointer_tracker_track_with_info (gpointer ptr,
                                   const gchar *info);

FIXME: Document me.

Since 3.2


e_pointer_tracker_untrack ()

void
e_pointer_tracker_untrack (gpointer ptr);

FIXME: Document me.

Since 3.2


e_pointer_tracker_dump ()

void
e_pointer_tracker_dump (void);

FIXME: Document me.

Since 3.2

Types and Values

struct tm

struct tm;