![]() |
![]() |
![]() |
Evolution-Data-Server Manual: Utilities (libedataserver) | ![]() |
---|---|---|---|---|
Top | Description |
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
); 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
); #define e_pointer_tracker_track (ptr) void e_pointer_tracker_track_with_info (gpointer ptr
,const gchar *info
); void e_pointer_tracker_untrack (gpointer ptr
); void e_pointer_tracker_dump (void
);
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
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
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
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()
.
|
a string value, or NULL . [allow-none]
|
Returns : |
a newly-allocated, stripped copy of string , or NULL
|
Since 3.6
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.
|
The string to search in. |
|
The string to search for. |
Returns : |
A pointer to the start of needle in haystack , or NULL if
needle is not found. |
gchar * e_util_unicode_get_utf8 (const gchar *text
,gunichar *out
);
Get a UTF-8 character from the beginning of text
.
|
The string to take the UTF-8 character from. |
|
The location to store the UTF-8 character in. |
Returns : |
A pointer to the next character in text after out . |
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.
|
The string to search in. |
|
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. |
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.
|
The string to search in. |
|
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. |
gint e_util_utf8_strcasecmp (const gchar *s1
,const gchar *s2
);
Compares two UTF-8 strings using approximate case-insensitive ordering.
|
a UTF-8 string |
|
another UTF-8 string |
Returns : |
< 0 if s1 compares before s2 , 0 if they compare equal,
> 0 if s1 compares after s2
|
gchar * e_util_utf8_remove_accents (const gchar *str
);
Returns a newly-allocated copy of str
with accents removed.
|
a UTF-8 string, or NULL
|
Returns : |
a newly-allocated string |
Since 2.28
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).
|
a UTF-8 string |
Returns : |
a newly-allocated string |
Since 3.0
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>
|
a possibly invalid UTF-8 string, or NULL
|
|
return location for the corrected string |
Returns : |
a valid UTF-8 string |
Since 3.0
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.
|
A GThread pointer |
Returns : |
A 64-bit integer. |
Since 2.32
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.
|
base path of a file name; this is left unchanged |
|
prefix for the filename; this is encoded |
|
file name to use; this is encoded; can be NULL
|
|
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
gsize e_utf8_strftime (gchar *string
,gsize max
,const gchar *fmt
,const struct tm *tm
);
The UTF-8 equivalent of e_strftime()
.
|
The string array to store the result in. |
|
The size of array s . |
|
The formatting to use on tm . |
|
The time value to format. |
Returns : |
The number of characters placed in s . |
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.
|
The string array to store the result in. |
|
The size of array s . |
|
The formatting to use on tm . |
|
The time value to format. |
Returns : |
The number of characters placed in s . |
gchar ** e_util_slist_to_strv (const GSList *strings
);
Convert list of strings into NULL-terminates array of 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
GSList * e_util_strv_to_slist (const gchar * const *strv
);
Convert NULL-terminated array of strings to a list of strings.
|
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
GSList * e_util_copy_string_slist (GSList *copy_to
,const GSList *strings
);
Copies GSList of strings at the end of copy_to
.
|
Where to copy; can be NULL . [element-type utf8][allow-none]
|
|
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
GSList * e_util_copy_object_slist (GSList *copy_to
,const GSList *objects
);
Copies GSList of GObject<!-- -->s at the end of copy_to
.
|
Where to copy; can be NULL . [element-type GObject][allow-none]
|
|
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
void e_util_free_string_slist (GSList *strings
);
Frees memory previously allocated by e_util_strv_to_slist()
.
|
a GSList of strings (gchar *). [element-type utf8] |
Since 3.4
void e_util_free_object_slist (GSList *objects
);
Calls g_object_unref()
on each member of objects
and then frees
also objects
itself.
Since 3.4
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.
Since 3.6
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.
|
a GFile to delete |
|
optional GCancellable object, or NULL
|
|
return location for a GError, or NULL
|
Returns : |
TRUE if the file was deleted, FALSE otherwise |
Since 3.6
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.
|
a GFile to delete |
|
the I/O priority of the request |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
data to pass to the callback function |
Since 3.6
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.
|
a GFile to delete |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
TRUE if the file was deleted, FALSE otherwise |
Since 3.6
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.
|
a GBinding |
|
a GValue whose type is derived from G_TYPE_ENUM |
|
a GValue of type G_TYPE_STRING |
|
not used |
Returns : |
TRUE if the enum value has a corresponding nickname |
Since 3.4
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.
|
a GBinding |
|
a GValue of type G_TYPE_STRING |
|
a GValue whose type is derived from G_TYPE_ENUM |
|
not used |
Returns : |
TRUE if the enum nickname has a corresponding value |
Since 3.4
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
EAsyncClosure * e_async_closure_new (void
);
Creates a new EAsyncClosure for use with asynchronous functions.
Returns : |
a new EAsyncClosure |
Since 3.6
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.
|
an EAsyncClosure |
Returns : |
a GAsyncResult which is owned by the closure. [transfer none] |
Since 3.6
void e_async_closure_free (EAsyncClosure *closure
);
Frees the closure
and the resources it holds.
|
an EAsyncClosure |
Since 3.6
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
.
|
a GObject |
|
a GAsyncResult |
|
an EAsyncClosure |
Since 3.6
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
);
Returns the value set by e_data_server_util_set_dbus_call_timeout()
.
Returns : |
the D-Bus call timeout in milliseconds |
Since 3.0
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.
|
default timeout for D-Bus calls in miliseconds |
Since 3.0
void e_pointer_tracker_track_with_info (gpointer ptr
,const gchar *info
);
FIXME: Document me.
Since 3.2
void e_pointer_tracker_untrack (gpointer ptr
);
FIXME: Document me.
Since 3.2