From 97645fe7bc69994a5430a9fbf1b521af75cb11a6 Mon Sep 17 00:00:00 2001 From: Gustavo Sverzut Barbieri Date: Sat, 12 Sep 2009 18:23:05 +0000 Subject: [PATCH] API BREAK: Fix Ethumb API to be more EFL-like * Callbacks were named to help Vala bindings. * All callbacks get 'void *data' as first argument, always. * All async methods get free_data parameters and call them also on disconnect() * queue_remove() renamed to generate_cancel() to be more clear. * queue_clear() renamed tp generate_cancel_call() to be more clear. SVN revision: 42445 --- legacy/ethumb/src/bin/ethumb.c | 2 +- legacy/ethumb/src/bin/ethumbd.c | 8 +- legacy/ethumb/src/bin/ethumbd_child.c | 13 +- legacy/ethumb/src/bin/ethumbd_client.c | 4 +- legacy/ethumb/src/lib/Ethumb.c | 6 +- legacy/ethumb/src/lib/Ethumb.h | 4 +- legacy/ethumb/src/lib/client/Ethumb_Client.c | 348 ++++++++++++++++--- legacy/ethumb/src/lib/client/Ethumb_Client.h | 19 +- legacy/ethumb/src/lib/ethumb_private.h | 4 +- legacy/ethumb/src/tests/ethumb_dbus.c | 18 +- 10 files changed, 333 insertions(+), 93 deletions(-) diff --git a/legacy/ethumb/src/bin/ethumb.c b/legacy/ethumb/src/bin/ethumb.c index 5fb285e335..0e31942ae0 100644 --- a/legacy/ethumb/src/bin/ethumb.c +++ b/legacy/ethumb/src/bin/ethumb.c @@ -133,7 +133,7 @@ _thumb_report(const char *mode, Ethumb *e) } static void -_finished_thumb(Ethumb *e, Eina_Bool success, void *data __UNUSED__) +_finished_thumb( void *data __UNUSED__, Ethumb *e, Eina_Bool success) { const char *mode = success ? "GENERATED" : "FAILED"; _thumb_report(mode, e); diff --git a/legacy/ethumb/src/bin/ethumbd.c b/legacy/ethumb/src/bin/ethumbd.c index 731337a068..0cce3ece73 100644 --- a/legacy/ethumb/src/bin/ethumbd.c +++ b/legacy/ethumb/src/bin/ethumbd.c @@ -42,10 +42,10 @@ #define MAX_ID 2000000 -#define DBG(...) EINA_ERROR_PDBG(__VA_ARGS__) -#define INF(...) EINA_ERROR_PINFO(__VA_ARGS__) -#define WRN(...) EINA_ERROR_PWARN(__VA_ARGS__) -#define ERR(...) EINA_ERROR_PERR(__VA_ARGS__) +#define DBG(...) EINA_LOG_DBG(__VA_ARGS__) +#define INF(...) EINA_LOG_INFO(__VA_ARGS__) +#define WRN(...) EINA_LOG_WARN(__VA_ARGS__) +#define ERR(...) EINA_LOG_ERR(__VA_ARGS__) static const char _ethumb_dbus_bus_name[] = "org.enlightenment.Ethumb"; static const char _ethumb_dbus_interface[] = "org.enlightenment.Ethumb"; diff --git a/legacy/ethumb/src/bin/ethumbd_child.c b/legacy/ethumb/src/bin/ethumbd_child.c index 5a6ac805a0..48516056b5 100644 --- a/legacy/ethumb/src/bin/ethumbd_child.c +++ b/legacy/ethumb/src/bin/ethumbd_child.c @@ -33,10 +33,10 @@ #include "ethumbd_private.h" -#define DBG(...) EINA_ERROR_PDBG(__VA_ARGS__) -#define INF(...) EINA_ERROR_PINFO(__VA_ARGS__) -#define WRN(...) EINA_ERROR_PWARN(__VA_ARGS__) -#define ERR(...) EINA_ERROR_PERR(__VA_ARGS__) +#define DBG(...) EINA_LOG_DBG(__VA_ARGS__) +#define INF(...) EINA_LOG_INFO(__VA_ARGS__) +#define WRN(...) EINA_LOG_WARN(__VA_ARGS__) +#define ERR(...) EINA_LOG_ERR(__VA_ARGS__) #define NETHUMBS 100 @@ -228,7 +228,7 @@ _ec_op_del(struct _Ethumbd_Child *ec) } static void -_ec_op_generated_cb(Ethumb *e, Eina_Bool success, void *data) +_ec_op_generated_cb(void *data, Ethumb *e, Eina_Bool success) { struct _Ethumbd_Child *ec = data; const char *thumb_path, *thumb_key; @@ -267,8 +267,7 @@ _ec_op_generate(struct _Ethumbd_Child *ec) ethumb_file_set(ec->ethumbt[index], path, key); ethumb_thumb_path_set(ec->ethumbt[index], thumb_path, thumb_key); - ethumb_generate(ec->ethumbt[index], _ec_op_generated_cb, - ec, NULL); + ethumb_generate(ec->ethumbt[index], _ec_op_generated_cb, ec, NULL); free(path); free(key); diff --git a/legacy/ethumb/src/bin/ethumbd_client.c b/legacy/ethumb/src/bin/ethumbd_client.c index 69dac049b9..685cb9b0ac 100644 --- a/legacy/ethumb/src/bin/ethumbd_client.c +++ b/legacy/ethumb/src/bin/ethumbd_client.c @@ -149,7 +149,7 @@ _thumb_report(const char *mode, const char *src_path, const char *src_key, const } static void -_finished_thumb(long id __UNUSED__, const char *src_path, const char *src_key, const char *thumb_path, const char *thumb_key, Eina_Bool success, void *data __UNUSED__) +_finished_thumb(void *data __UNUSED__, Ethumb_Client *client __UNUSED__, int id __UNUSED__, const char *src_path, const char *src_key, const char *thumb_path, const char *thumb_key, Eina_Bool success) { const char *mode = success ? "GENERATED" : "FAILED"; _thumb_report(mode, src_path, src_key, thumb_path, thumb_key); @@ -157,7 +157,7 @@ _finished_thumb(long id __UNUSED__, const char *src_path, const char *src_key, c } static void -_connected(Ethumb_Client *c, Eina_Bool success, void *data) +_connected(void *data, Ethumb_Client *c, Eina_Bool success) { struct options *opts = data; const char *thumb_path, *thumb_key; diff --git a/legacy/ethumb/src/lib/Ethumb.c b/legacy/ethumb/src/lib/Ethumb.c index 582511b5eb..00326b396a 100644 --- a/legacy/ethumb/src/lib/Ethumb.c +++ b/legacy/ethumb/src/lib/Ethumb.c @@ -1195,7 +1195,7 @@ _ethumb_finished_idler_cb(void *data) { Ethumb *e = data; - e->finished_cb(e, e->cb_result, e->cb_data); + e->finished_cb(e->cb_data, e, e->cb_result); if (e->cb_data_free) e->cb_data_free(e->cb_data); e->finished_idler = NULL; @@ -1218,7 +1218,7 @@ ethumb_finished_callback_call(Ethumb *e, int result) } EAPI Eina_Bool -ethumb_generate(Ethumb *e, ethumb_generate_callback_t finished_cb, void *data, void (*free_data)(void *)) +ethumb_generate(Ethumb *e, Ethumb_Generate_Cb finished_cb, const void *data, Eina_Free_Cb free_data) { int r; @@ -1234,7 +1234,7 @@ ethumb_generate(Ethumb *e, ethumb_generate_callback_t finished_cb, void *data, v return EINA_FALSE; } e->finished_cb = finished_cb; - e->cb_data = data; + e->cb_data = (void *)data; e->cb_data_free = free_data; if (!e->src_path) diff --git a/legacy/ethumb/src/lib/Ethumb.h b/legacy/ethumb/src/lib/Ethumb.h index 107128c5ff..8d9530440d 100644 --- a/legacy/ethumb/src/lib/Ethumb.h +++ b/legacy/ethumb/src/lib/Ethumb.h @@ -68,7 +68,7 @@ typedef enum _Ethumb_Thumb_Aspect Ethumb_Thumb_Aspect; typedef struct _Ethumb_Frame Ethumb_Frame; typedef struct _Ethumb Ethumb; -typedef void (*ethumb_generate_callback_t)(Ethumb *e, Eina_Bool success, void *data); +typedef void (*Ethumb_Generate_Cb)(void *data, Ethumb *e, Eina_Bool success); EAPI int ethumb_init(void); EAPI int ethumb_shutdown(void); @@ -126,7 +126,7 @@ EAPI void ethumb_file_get(const Ethumb *e, const char **path, const char **key) EAPI void ethumb_file_free(Ethumb *e) EINA_ARG_NONNULL(1); EAPI void ethumb_thumb_path_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1); EAPI void ethumb_thumb_path_get(Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1); -EAPI Eina_Bool ethumb_generate(Ethumb *e, ethumb_generate_callback_t finished_cb, void *data, void (*free_data)(void *)) EINA_ARG_NONNULL(1, 2); +EAPI Eina_Bool ethumb_generate(Ethumb *e, Ethumb_Generate_Cb finished_cb, const void *data, Eina_Free_Cb free_data) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool ethumb_exists(Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; #ifdef __cplusplus diff --git a/legacy/ethumb/src/lib/client/Ethumb_Client.c b/legacy/ethumb/src/lib/client/Ethumb_Client.c index 93fa8e77aa..6c83c17d80 100644 --- a/legacy/ethumb/src/lib/client/Ethumb_Client.c +++ b/legacy/ethumb/src/lib/client/Ethumb_Client.c @@ -62,16 +62,21 @@ struct _Ethumb_Client DBusPendingCall *pending_start_service_by_name; const char *unique_name; DBusPendingCall *pending_new; - ec_connect_callback_t connect_cb; - void *connect_cb_data; - void (*connect_cb_free_data)(void *); + struct { + Ethumb_Client_Connect_Cb cb; + void *data; + Eina_Free_Cb free_data; + } connect; Eina_List *pending_add; Eina_List *pending_remove; Eina_List *pending_gen; DBusPendingCall *pending_clear; DBusPendingCall *pending_setup; - void (*on_server_die_cb)(Ethumb_Client *client, void *data); - void *on_server_die_cb_data; + struct { + Ethumb_Client_Die_Cb cb; + void *data; + Eina_Free_Cb free_data; + } die; const char *object_path; Eina_Bool ethumb_dirty : 1; @@ -86,9 +91,9 @@ struct _ethumb_pending_add const char *key; const char *thumb; const char *thumb_key; - generated_callback_t generated_cb; + Ethumb_Client_Generate_Cb generated_cb; void *data; - void (*free_data)(void *); + Eina_Free_Cb free_data; DBusPendingCall *pending_call; Ethumb_Client *client; }; @@ -96,8 +101,9 @@ struct _ethumb_pending_add struct _ethumb_pending_remove { dbus_int32_t id; - void (*remove_cb)(Eina_Bool result, void *data); + Ethumb_Client_Generate_Cancel_Cb cancel_cb; void *data; + Eina_Free_Cb free_data; DBusPendingCall *pending_call; Ethumb_Client *client; }; @@ -109,9 +115,9 @@ struct _ethumb_pending_gen const char *key; const char *thumb; const char *thumb_key; - generated_callback_t generated_cb; + Ethumb_Client_Generate_Cb generated_cb; void *data; - void (*free_data)(void *); + Eina_Free_Cb free_data; }; static const char _ethumb_dbus_bus_name[] = "org.enlightenment.Ethumb"; @@ -215,15 +221,42 @@ _ethumb_client_name_owner_changed(void *data, DBusMessage *msg) else { ERR("server exit!!!\n"); - if (client->on_server_die_cb) - client->on_server_die_cb(client, - client->on_server_die_cb_data); + if (client->die.cb) + { + client->die.cb(client->die.data, client); + client->die.cb = NULL; + } + if (client->die.free_data) + { + client->die.free_data(client->die.data); + client->die.free_data = NULL; + client->die.data = NULL; + } } } else DBG("unknown change from %s to %s\n", from, to); } +static void +_ethumb_client_report_connect(Ethumb_Client *client, Eina_Bool success) +{ + if (!client->connect.cb) + { + ERR("already called?!"); + return; + } + + client->connect.cb(client->connect.data, client, success); + if (client->connect.free_data) + { + client->connect.free_data(client->connect.data); + client->connect.free_data = NULL; + } + client->connect.cb = NULL; + client->connect.data = NULL; +} + static void _ethumb_client_new_cb(void *data, DBusMessage *msg, DBusError *error) { @@ -251,15 +284,11 @@ _ethumb_client_new_cb(void *data, DBusMessage *msg, DBusError *error) _ethumb_dbus_objects_interface, "generated", _ethumb_client_generated_cb, client); - client->connect_cb(client, 1, client->connect_cb_data); - if (client->connect_cb_free_data) - client->connect_cb_free_data(client->connect_cb_data); + _ethumb_client_report_connect(client, 1); return; end_error: - client->connect_cb(client, 0, client->connect_cb_data); - if (client->connect_cb_free_data) - client->connect_cb_free_data(client->connect_cb_data); + _ethumb_client_report_connect(client, 0); } static void @@ -323,9 +352,7 @@ _ethumb_client_start_server_cb(void *data, DBusMessage *msg, DBusError *err) error: ERR("failed to start Ethumbd DBus service by its name.\n"); - client->connect_cb(client, 0, client->connect_cb_data); - if (client->connect_cb_free_data) - client->connect_cb_free_data(client->connect_cb_data); + _ethumb_client_report_connect(client, 0); } static void @@ -344,9 +371,7 @@ _ethumb_client_start_server(Ethumb_Client *client) if (!client->pending_start_service_by_name) { ERR("could not start service by name!\n"); - client->connect_cb(client, 0, client->connect_cb_data); - if (client->connect_cb_free_data) - client->connect_cb_free_data(client->connect_cb_data); + _ethumb_client_report_connect(client, 0); } } @@ -389,9 +414,7 @@ _ethumb_client_get_name_owner(void *data, DBusMessage *msg, DBusError *err) return; error: - client->connect_cb(client, 0, client->connect_cb_data); - if (client->connect_cb_free_data) - client->connect_cb_free_data(client->connect_cb_data); + _ethumb_client_report_connect(client, 0); } EAPI int @@ -434,8 +457,46 @@ ethumb_client_shutdown(void) return _initcount; } +/** + * Connects to Ethumb server and return the client instance. + * + * This is the "constructor" of Ethumb_Client, where everything + * starts. + * + * If server was down, it is tried to start it using DBus activation, + * then the connection is retried. + * + * This call is asynchronous and will not block, instead it will be in + * "not connected" state until @a connect_cb is called with either + * success or failure. On failure, then no methods should be + * called. On success you're now able to setup and then ask generation + * of thumbnails. + * + * Usually you should listen for server death/disconenction with + * ethumb_client_on_server_die_callback_set(). + * + * @param connect_cb function to call to report connection success or + * failure. Do not call any other ethumb_client method until + * this function returns. The first received parameter is the + * given argument @a data. Must @b not be @c NULL. This + * function will not be called if user explicitly calls + * ethumb_client_disconnect(). + * @param data context to give back to @a connect_cb. May be @c NULL. + * @param free_data function used to release @a data resources, if + * any. May be @c NULL. If this function exists, it will be + * called immediately after @a connect_cb is called or if user + * explicitly calls ethumb_client_disconnect() before such + * (that is, don't rely on @a data after @a connect_cb was + * called!) + * + * @return client instance or NULL if failed. If @a connect_cb is + * missing it returns @c NULL. If it fail for other + * conditions, @c NULL is also returned and @a connect_cb is + * called with @c success=EINA_FALSE. The client instance is + * not ready to be used until @a connect_cb is called. + */ EAPI Ethumb_Client * -ethumb_client_connect(ec_connect_callback_t connect_cb, void *data, void (*free_data)(void *)) +ethumb_client_connect(Ethumb_Client_Connect_Cb connect_cb, const void *data, Eina_Free_Cb free_data) { Ethumb_Client *eclient; @@ -448,9 +509,9 @@ ethumb_client_connect(ec_connect_callback_t connect_cb, void *data, void (*free_ goto err; } - eclient->connect_cb = connect_cb; - eclient->connect_cb_data = data; - eclient->connect_cb_free_data = free_data; + eclient->connect.cb = connect_cb; + eclient->connect.data = (void *)data; + eclient->connect.free_data = free_data; eclient->ethumb = ethumb_new(); if (!eclient->ethumb) @@ -486,10 +547,18 @@ connection_err: ethumb_new_err: free(eclient); err: - connect_cb(NULL, EINA_FALSE, data); + connect_cb((void *)data, NULL, EINA_FALSE); + if (free_data) + free_data((void *)data); return NULL; } +/** + * Disconnect the client, releasing all client resources. + * + * This is the destructor of Ethumb_Client, after it's disconnected + * the client handle is now gone and should not be used. + */ EAPI void ethumb_client_disconnect(Ethumb_Client *client) { @@ -531,6 +600,8 @@ ethumb_client_disconnect(Ethumb_Client *client) struct _ethumb_pending_remove *pending = data; dbus_pending_call_cancel(pending->pending_call); dbus_pending_call_unref(pending->pending_call); + if (pending->free_data) + pending->free_data(pending->data); free(pending); } @@ -563,14 +634,46 @@ end_connection: e_dbus_signal_handler_del(client->conn, client->generated_signal); e_dbus_connection_close(client->conn); + if (client->connect.free_data) + client->connect.free_data(client->connect.data); + if (client->die.free_data) + client->die.free_data(client->die.data); + free(client); } +/** + * Sets the callback to report server died. + * + * When server dies there is nothing you can do, just release + * resources with ethumb_client_disconnect() and probably try to + * connect again. + * + * Usually you should set this callback and handle this case, it does + * happen! + * + * @param client the client instance to monitor. Must @b not be @c + * NULL. + * @param server_die_cb function to call back when server dies. The + * first parameter will be the argument @a data. May be @c + * NULL. + * @param data context to give back to @a server_die_cb. May be @c + * NULL. + * @param free_data used to release @a data resources after @a + * server_die_cb is called or user calls + * ethumb_client_disconnect(). + */ EAPI void -ethumb_client_on_server_die_callback_set(Ethumb_Client *client, void (*on_server_die_cb)(Ethumb_Client *client, void *data), void *data) +ethumb_client_on_server_die_callback_set(Ethumb_Client *client, Ethumb_Client_Die_Cb server_die_cb, const void *data, Eina_Free_Cb free_data) { - client->on_server_die_cb = on_server_die_cb; - client->on_server_die_cb_data = data; + EINA_SAFETY_ON_NULL_RETURN(client); + + if (client->die.free_data) + client->die.free_data(client->die.data); + + client->die.cb = server_die_cb; + client->die.data = (void *)data; + client->die.free_data = free_data; } static void @@ -631,6 +734,15 @@ _ethumb_client_dbus_append_bytearray(DBusMessageIter *iter, const char *string) dbus_message_iter_close_container(iter, &viter); } +/** + * Send setup to server. + * + * This method is called automatically by ethumb_client_generate() if + * any property was changed. No need to call it manually. + * + * @param client client instance. Must @b not be @c NULL and client + * must be connected (after connected_cb is called). + */ EAPI void ethumb_client_ethumb_setup(Ethumb_Client *client) { @@ -647,6 +759,7 @@ ethumb_client_ethumb_setup(Ethumb_Client *client) dbus_int32_t video_ntimes, video_fps, document_page; EINA_SAFETY_ON_NULL_RETURN(client); + EINA_SAFETY_ON_FALSE_RETURN(client->connected); client->ethumb_dirty = 0; msg = dbus_message_new_method_call(_ethumb_dbus_bus_name, @@ -822,9 +935,10 @@ _ethumb_client_generated_cb(void *data, DBusMessage *msg) if (found) { client->pending_gen = eina_list_remove_list(client->pending_gen, l); - pending->generated_cb(id, pending->file, pending->key, + pending->generated_cb(pending->data, client, id, + pending->file, pending->key, pending->thumb, pending->thumb_key, - success, pending->data); + success); if (pending->free_data) pending->free_data(pending->data); eina_stringshare_del(pending->file); @@ -875,8 +989,8 @@ end: free(pending); } -static long -_ethumb_client_queue_add(Ethumb_Client *client, const char *file, const char *key, const char *thumb, const char *thumb_key, generated_callback_t generated_cb, void *data, void (*free_data)(void *)) +static int +_ethumb_client_queue_add(Ethumb_Client *client, const char *file, const char *key, const char *thumb, const char *thumb_key, Ethumb_Client_Generate_Cb generated_cb, const void *data, Eina_Free_Cb free_data) { DBusMessage *msg; DBusMessageIter iter; @@ -889,7 +1003,7 @@ _ethumb_client_queue_add(Ethumb_Client *client, const char *file, const char *ke pending->thumb = eina_stringshare_add(thumb); pending->thumb_key = eina_stringshare_add(thumb_key); pending->generated_cb = generated_cb; - pending->data = data; + pending->data = (void *)data; pending->free_data = free_data; pending->client = client; @@ -937,13 +1051,30 @@ _ethumb_client_queue_remove_cb(void *data, DBusMessage *msg, DBusError *error) dbus_message_iter_get_basic(&iter, &success); end: - if (pending->remove_cb) - pending->remove_cb(success, pending->data); + if (pending->cancel_cb) + pending->cancel_cb(pending->data, success); + if (pending->free_data) + pending->free_data(pending->data); free(pending); } +/** + * Ask server to cancel generation of thumbnail. + * + * @param client client instance. Must @b not be @c NULL and client + * must be connected (after connected_cb is called). + * @param id valid id returned by ethumb_client_generate() + * @param cancel_cb function to report cancellation results. + * @param data context argument to give back to @a cancel_cb. May be + * @c NULL. + * @param data context to give back to @a cancel_cb. May be @c + * NULL. + * @param free_data used to release @a data resources after @a + * cancel_cb is called or user calls + * ethumb_client_disconnect(). + */ EAPI void -ethumb_client_queue_remove(Ethumb_Client *client, int id, void (*queue_remove_cb)(Eina_Bool success, void *data), void *data) +ethumb_client_generate_cancel(Ethumb_Client *client, int id, Ethumb_Client_Generate_Cancel_Cb cancel_cb, const void *data, Eina_Free_Cb free_data) { DBusMessage *msg; struct _ethumb_pending_remove *pending; @@ -951,11 +1082,13 @@ ethumb_client_queue_remove(Ethumb_Client *client, int id, void (*queue_remove_cb int found; dbus_int32_t id32 = id; EINA_SAFETY_ON_NULL_RETURN(client); + EINA_SAFETY_ON_FALSE_RETURN(id >= 0); pending = calloc(1, sizeof(*pending)); pending->id = id; - pending->remove_cb = queue_remove_cb; - pending->data = data; + pending->cancel_cb = cancel_cb; + pending->data = (void *)data; + pending->free_data = free_data; pending->client = client; msg = dbus_message_new_method_call(_ethumb_dbus_bus_name, @@ -1029,8 +1162,16 @@ _ethumb_client_queue_clear_cb(void *data, DBusMessage *msg __UNUSED__, DBusError client->pending_clear = NULL; } +/** + * Ask server to cancel generation of all thumbnails. + * + * @param client client instance. Must @b not be @c NULL and client + * must be connected (after connected_cb is called). + * + * @see ethumb_client_generate_cancel() + */ EAPI void -ethumb_client_queue_clear(Ethumb_Client *client) +ethumb_client_generate_cancel_all(Ethumb_Client *client) { DBusMessage *msg; void *data; @@ -1287,6 +1428,23 @@ ethumb_client_document_page_set(Ethumb_Client *client, int page) ethumb_document_page_set(client->ethumb, page); } +/** + * Set source file to be thumbnailed. + * + * Calling this function has the side effect of resetting values set + * with ethumb_client_thumb_path_set() or auto-generated with + * ethumb_client_thumb_exists(). + * + * @param client the client instance to use. Must @b not be @c + * NULL. May be pending connected (can be called before @c + * connected_cb) + * @param path the filesystem path to use. May be @c NULL. + * @param key the extra argument/key inside @a path to read image + * from. This is only used for formats that allow multiple + * resources in one file, like EET or Edje (group name). + * + * @return #EINA_TRUE on success, #EINA_FALSE on failure. + */ EAPI Eina_Bool ethumb_client_file_set(Ethumb_Client *client, const char *path, const char *key) { @@ -1295,6 +1453,9 @@ ethumb_client_file_set(Ethumb_Client *client, const char *path, const char *key) return ethumb_file_set(client->ethumb, path, key); } +/** + * Get values set with ethumb_client_file_get() + */ EAPI void ethumb_client_file_get(Ethumb_Client *client, const char **path, const char **key) { @@ -1305,6 +1466,13 @@ ethumb_client_file_get(Ethumb_Client *client, const char **path, const char **ke ethumb_file_get(client->ethumb, path, key); } +/** + * Reset previously set file to @c NULL. + * + * @param client the client instance to use. Must @b not be @c + * NULL. May be pending connected (can be called before @c + * connected_cb) + */ EAPI void ethumb_client_file_free(Ethumb_Client *client) { @@ -1313,6 +1481,16 @@ ethumb_client_file_free(Ethumb_Client *client) ethumb_file_free(client->ethumb); } +/** + * Set a defined path and key to store the thumbnail. + * + * If not explicitly given, the thumbnail path will be auto-generated + * by ethumb_client_thumb_exists() or server using configured + * parameters like size, aspect and category. + * + * Set these to @c NULL to forget previously given values. After + * ethumb_client_file_set() these values will be reset to @c NULL. + */ EAPI void ethumb_client_thumb_path_set(Ethumb_Client *client, const char *path, const char *key) { @@ -1321,6 +1499,27 @@ ethumb_client_thumb_path_set(Ethumb_Client *client, const char *path, const char ethumb_thumb_path_set(client->ethumb, path, key); } +/** + * Get the configured thumbnail path. + * + * This returns the value set with ethumb_client_thumb_path_set() or + * auto-generated by ethumb_client_thumb_exists() if it was not set. + * + * @param path where to return configured path. May be @c NULL. If + * there was no path configured with + * ethumb_client_thumb_path_set() and + * ethumb_client_thumb_exists() was not called, then it will + * probably return @c NULL. If not @c NULL, then it will be a + * pointer to a stringshared instance, but @b no references are + * added (do it with eina_stringshare_ref())! + * @param key where to return configured key. May be @c NULL. If + * there was no key configured with + * ethumb_client_thumb_key_set() and + * ethumb_client_thumb_exists() was not called, then it will + * probably return @c NULL. If not @c NULL, then it will be a + * pointer to a stringshared instance, but @b no references are + * added (do it with eina_stringshare_ref())! + */ EAPI void ethumb_client_thumb_path_get(Ethumb_Client *client, const char **path, const char **key) { @@ -1331,6 +1530,20 @@ ethumb_client_thumb_path_get(Ethumb_Client *client, const char **path, const cha ethumb_thumb_path_get(client->ethumb, path, key); } +/** + * Checks whenever file already exists (locally!) + * + * This will check locally (not calling server) if thumbnail already + * exists or not, also calculating the thumbnail path. See + * ethumb_client_thumb_path_get(). Path must be configured with + * ethumb_client_file_set() before using it and the last set file will + * be used! + * + * @param client client instance. Must @b not be @c NULL and client + * must be configured with ethumb_client_file_set(). + * + * @return #EINA_TRUE if it exists, #EINA_FALSE otherwise. + */ EAPI Eina_Bool ethumb_client_thumb_exists(Ethumb_Client *client) { @@ -1339,12 +1552,47 @@ ethumb_client_thumb_exists(Ethumb_Client *client) return ethumb_exists(client->ethumb); } -EAPI long -ethumb_client_generate(Ethumb_Client *client, generated_callback_t generated_cb, void *data, void (*free_data)(void *)) +/** + * Ask server to generate thumbnail. + * + * This process is asynchronous and will report back from main loop + * using @a generated_cb. One can cancel this request by calling + * ethumb_client_generate_cancel() or + * ethumb_client_generate_cancel_all(), but not that request might be + * processed by server already and no generated files will be removed + * if that is the case. + * + * This will not check if file already exists, this should be done by + * explicitly calling ethumb_client_thumb_exists(). That is, this + * function will override any existing thumbnail. + * + * @param client client instance. Must @b not be @c NULL and client + * must be connected (after connected_cb is called). + * @param generated_cb function to report generation results. + * @param data context argument to give back to @a generated_cb. May + * be @c NULL. + * @param data context to give back to @a generate_cb. May be @c + * NULL. + * @param free_data used to release @a data resources after @a + * generated_cb is called or user calls + * ethumb_client_disconnect(). + * + * @return identifier or -1 on error. If -1 is returned (error) then + * @a free_data is @b not called! + * + * @see ethumb_client_connect() + * @see ethumb_client_file_set() + * @see ethumb_client_thumb_exists() + * @see ethumb_client_generate_cancel() + * @see ethumb_client_generate_cancel_all() + */ +EAPI int +ethumb_client_generate(Ethumb_Client *client, Ethumb_Client_Generate_Cb generated_cb, const void *data, Eina_Free_Cb free_data) { const char *file, *key, *thumb, *thumb_key; - long id; + int id; EINA_SAFETY_ON_NULL_RETURN_VAL(client, -1); + EINA_SAFETY_ON_FALSE_RETURN_VAL(client->connected, -1); ethumb_file_get(client->ethumb, &file, &key); if (!file) diff --git a/legacy/ethumb/src/lib/client/Ethumb_Client.h b/legacy/ethumb/src/lib/client/Ethumb_Client.h index c90f6cc786..2035f6bea6 100644 --- a/legacy/ethumb/src/lib/client/Ethumb_Client.h +++ b/legacy/ethumb/src/lib/client/Ethumb_Client.h @@ -38,20 +38,17 @@ extern "C" { #endif typedef struct _Ethumb_Client Ethumb_Client; -typedef void (*ec_connect_callback_t)(Ethumb_Client *client, Eina_Bool success, void *data); -typedef void (*generated_callback_t)(long id, const char *file, const char *key, - const char *thumb_path, const char *thumb_key, - Eina_Bool success, void *data); +typedef void (*Ethumb_Client_Connect_Cb)(void *data, Ethumb_Client *client, Eina_Bool success); +typedef void (*Ethumb_Client_Die_Cb)(void *data, Ethumb_Client *client); +typedef void (*Ethumb_Client_Generate_Cb)(void *data, Ethumb_Client *client, int id, const char *file, const char *key, const char *thumb_path, const char *thumb_key, Eina_Bool success); +typedef void (*Ethumb_Client_Generate_Cancel_Cb)(void *data, Eina_Bool success); EAPI int ethumb_client_init(void); EAPI int ethumb_client_shutdown(void); -EAPI Ethumb_Client * ethumb_client_connect(ec_connect_callback_t connect_cb, void *data, void (*free_data)(void *)); +EAPI Ethumb_Client * ethumb_client_connect(Ethumb_Client_Connect_Cb connect_cb, const void *data, Eina_Free_Cb free_data); EAPI void ethumb_client_disconnect(Ethumb_Client *client); -EAPI void ethumb_client_on_server_die_callback_set(Ethumb_Client *client, void (*on_server_die_cb)(Ethumb_Client *client, void *data), void *data); - -EAPI void ethumb_client_queue_remove(Ethumb_Client *client, int id, void (*queue_remove_cb)(Eina_Bool success, void *data), void *data); -EAPI void ethumb_client_queue_clear(Ethumb_Client *client); +EAPI void ethumb_client_on_server_die_callback_set(Ethumb_Client *client, Ethumb_Client_Die_Cb server_die_cb, const void *data, Eina_Free_Cb free_data); EAPI void ethumb_client_fdo_set(Ethumb_Client *client, Ethumb_Thumb_FDO_Size s); EAPI void ethumb_client_size_set(Ethumb_Client *client, int tw, int th); @@ -87,7 +84,9 @@ EAPI void ethumb_client_file_free(Ethumb_Client *client); EAPI void ethumb_client_thumb_path_set(Ethumb_Client *client, const char *path, const char *key); EAPI void ethumb_client_thumb_path_get(Ethumb_Client *client, const char **path, const char **key); EAPI Eina_Bool ethumb_client_thumb_exists(Ethumb_Client *client); -EAPI long ethumb_client_generate(Ethumb_Client *client, generated_callback_t generated_cb, void *data, void (*free_data)(void *)); +EAPI int ethumb_client_generate(Ethumb_Client *client, Ethumb_Client_Generate_Cb generated_cb, const void *data, Eina_Free_Cb free_data); +EAPI void ethumb_client_generate_cancel(Ethumb_Client *client, int id, Ethumb_Client_Generate_Cancel_Cb cancel_cb, const void *data, Eina_Free_Cb free_data); +EAPI void ethumb_client_generate_cancel_all(Ethumb_Client *client); #ifdef __cplusplus } diff --git a/legacy/ethumb/src/lib/ethumb_private.h b/legacy/ethumb/src/lib/ethumb_private.h index cce6f0c1c1..ed7937bc3d 100644 --- a/legacy/ethumb/src/lib/ethumb_private.h +++ b/legacy/ethumb/src/lib/ethumb_private.h @@ -40,9 +40,9 @@ struct _Ethumb Evas *e, *sub_e; Evas_Object *o, *img; Ecore_Idler *finished_idler; - ethumb_generate_callback_t finished_cb; + Ethumb_Generate_Cb finished_cb; void *cb_data; - void (*cb_data_free)(void *); + Eina_Free_Cb cb_data_free; int cb_result; }; diff --git a/legacy/ethumb/src/tests/ethumb_dbus.c b/legacy/ethumb/src/tests/ethumb_dbus.c index 59a95bfdc9..3357c6f92f 100644 --- a/legacy/ethumb/src/tests/ethumb_dbus.c +++ b/legacy/ethumb/src/tests/ethumb_dbus.c @@ -33,21 +33,15 @@ #include static void -_on_server_die_cb(Ethumb_Client *client, void *data) +_on_server_die_cb(void *data __UNUSED__, Ethumb_Client *client __UNUSED__) { ecore_main_loop_quit(); } static void -_queue_add_cb(long id, const char *file, const char *key, const char *thumb_path, const char *thumb_key, Eina_Bool success, void *data) +_queue_add_cb(void *data __UNUSED__, Ethumb_Client *client __UNUSED__, int id, const char *file, const char *key __UNUSED__, const char *thumb_path, const char *thumb_key __UNUSED__, Eina_Bool success) { - fprintf(stderr, ">>> file ready: %s; thumb ready: %s; id = %ld\n", file, thumb_path, id); -} - -static void -_disconnect(Ethumb_Client *client) -{ - ethumb_client_disconnect(client); + fprintf(stderr, ">>> %hhu file ready: %s; thumb ready: %s; id = %d\n", success, file, thumb_path, id); } static void @@ -84,7 +78,7 @@ _request_thumbnails(Ethumb_Client *client, void *data) } static void -_connect_cb(Ethumb_Client *client, Eina_Bool success, void *data) +_connect_cb(void *data, Ethumb_Client *client, Eina_Bool success) { fprintf(stderr, "connected: %d\n", success); if (!success) @@ -116,12 +110,12 @@ main(int argc, char *argv[]) ethumb_client_shutdown(); return -1; } - ethumb_client_on_server_die_callback_set(client, _on_server_die_cb, NULL); + ethumb_client_on_server_die_callback_set(client, _on_server_die_cb, NULL, NULL); fprintf(stderr, "*** debug\n"); ecore_main_loop_begin(); - _disconnect(client); + ethumb_client_disconnect(client); ethumb_client_shutdown();