Functions that all users must know of to use Ethumb_Client. More...
Typedefs | |
typedef struct _Ethumb_Client | Ethumb_Client |
client handle. More... | |
typedef struct _Ethumb_Exists | Ethumb_Exists |
client exists request handle. More... | |
typedef void(* | Ethumb_Client_Connect_Cb )(void *data, Ethumb_Client *client, Eina_Bool success) |
reports results of ethumb_client_connect() More... | |
typedef void(* | Ethumb_Client_Die_Cb )(void *data, Ethumb_Client *client) |
reports server connection ended. More... | |
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) |
reports results of ethumb_client_generate(). More... | |
typedef void(* | Ethumb_Client_Thumb_Exists_Cb )(void *data, Ethumb_Client *client, Ethumb_Exists *thread, Eina_Bool exists) |
report results of ethumb_client_thumb_exists(). More... | |
typedef void(* | Ethumb_Client_Generate_Cancel_Cb )(void *data, Eina_Bool success) |
reports results of ethumb_client_generate_cancel() More... | |
typedef void(* | Ethumb_Client_Async_Done_Cb )(Ethumb_Client *ethumbd, const char *thumb_path, const char *thumb_key, void *data) |
typedef void(* | Ethumb_Client_Async_Error_Cb )(Ethumb_Client *ethumbd, void *data) |
typedef struct _Ethumb_Client_Async | Ethumb_Client_Async |
Functions | |
EAPI int | ethumb_client_init (void) |
Initialize the Ethumb_Client library. More... | |
EAPI int | ethumb_client_shutdown (void) |
Shut down the Ethumb_Client library. More... | |
EAPI Ethumb_Client * | ethumb_client_connect (Ethumb_Client_Connect_Cb connect_cb, const void *data, Eina_Free_Cb free_data) |
Connects to Ethumb server and return the client instance. More... | |
EAPI void | ethumb_client_disconnect (Ethumb_Client *client) |
Disconnect the client, releasing all client resources. More... | |
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) |
Sets the callback to report server died. More... | |
EAPI Eina_Bool | ethumb_client_file_set (Ethumb_Client *client, const char *path, const char *key) |
Set source file to be thumbnailed. More... | |
EAPI void | ethumb_client_file_get (Ethumb_Client *client, const char **path, const char **key) |
Get values set with ethumb_client_file_get() More... | |
EAPI void | ethumb_client_file_free (Ethumb_Client *client) |
Reset previously set file to NULL . More... | |
EAPI Ethumb_Exists * | ethumb_client_thumb_exists (Ethumb_Client *client, Ethumb_Client_Thumb_Exists_Cb exists_cb, const void *data) |
Checks whenever file already exists (locally!) More... | |
EAPI void | ethumb_client_thumb_exists_cancel (Ethumb_Exists *exists) |
Cancel an ongoing exists request. More... | |
EAPI Eina_Bool | ethumb_client_thumb_exists_check (Ethumb_Exists *exists) |
Check if an exists request was cancelled. More... | |
EAPI int | ethumb_client_generate (Ethumb_Client *client, Ethumb_Client_Generate_Cb generated_cb, const void *data, Eina_Free_Cb free_data) |
Ask server to generate thumbnail. More... | |
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) |
Ask server to cancel generation of thumbnail. More... | |
EAPI void | ethumb_client_generate_cancel_all (Ethumb_Client *client) |
Ask server to cancel generation of all thumbnails. More... | |
EAPI Ethumb_Client_Async * | ethumb_client_thumb_async_get (Ethumb_Client *client, Ethumb_Client_Async_Done_Cb done, Ethumb_Client_Async_Error_Cb error, const void *data) |
EAPI void | ethumb_client_thumb_async_cancel (Ethumb_Client *client, Ethumb_Client_Async *request) |
Detailed Description
Functions that all users must know of to use Ethumb_Client.
Typedef Documentation
typedef struct _Ethumb_Client Ethumb_Client |
client handle.
The client handle is created by ethumb_client_connect() and destroyed by ethumb_client_disconnect(). The connection and requests are asynchronous and callbacks should be used to report both success and failure of calls.
typedef struct _Ethumb_Exists Ethumb_Exists |
client exists request handle.
The exists request handle is created by ethumb_client_thumb_exists(), automatically destroyed when it end and cancelled when requested by ethumb_client_thumb_exists_cancel().
typedef void(* Ethumb_Client_Connect_Cb)(void *data, Ethumb_Client *client, Eina_Bool success) |
reports results of ethumb_client_connect()
- Parameters
-
data extra context given to ethumb_client_connect(). client handle of the current connection to server. success EINA_TRUE
if connected orEINA_FALSE
if it was not possible.
typedef void(* Ethumb_Client_Die_Cb)(void *data, Ethumb_Client *client) |
reports server connection ended.
Functions of this type may be called if they are set with ethumb_client_on_server_die_callback_set().
- Parameters
-
data extra context given to ethumb_client_on_server_die_callback_set(). client handle of the current connection to server.
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) |
reports results of ethumb_client_generate().
- Parameters
-
data extra context given to ethumb_client_generate(). client handle of the current connection to server. id identifier returned by ethumb_client_generate(). file path set with ethumb_client_file_set(). key value set with ethumb_client_file_set() or NULL
.thumb_path where thumbnail was stored, either set with ethumb_client_thumb_path_set() or automatically calculated using parameters. thumb_key key inside thumb_path where thumbnail was stored or NULL
.success EINA_TRUE
if generated orEINA_FALSE
on errors.
typedef void(* Ethumb_Client_Thumb_Exists_Cb)(void *data, Ethumb_Client *client, Ethumb_Exists *thread, Eina_Bool exists) |
report results of ethumb_client_thumb_exists().
- Parameters
-
client handle of the current connection to server. exists EINA_TRUE if the thumbnail exists. data extra context given to ethumb_client_thumb_exists().
During the execution of the callback the state of the client
is temporarily realy restored to what it was when the call to ethumb_client_thumb_exists() was done.
typedef void(* Ethumb_Client_Generate_Cancel_Cb)(void *data, Eina_Bool success) |
reports results of ethumb_client_generate_cancel()
- Parameters
-
data extra context given to ethumb_client_generate_cancel() client handle of the current connection to server.
Function Documentation
EAPI int ethumb_client_init | ( | void | ) |
Initialize the Ethumb_Client library.
- Returns
- 1 or greater on success, 0 on error.
This function sets up all the Ethumb_Client module dependencies. It returns 0 on failure (that is, when one of the dependency fails to initialize), otherwise it returns the number of times it has already been called.
When Ethumb_Client is not used anymore, call ethumb_client_shutdown() to shut down the Ethumb_Client library.
EAPI int ethumb_client_shutdown | ( | void | ) |
Shut down the Ethumb_Client library.
- Returns
- 0 when everything is shut down, 1 or greater if there are other users of the Ethumb_Client library pending shutdown.
This function shuts down the Ethumb_Client library. It returns 0 when it has been called the same number of times than ethumb_client_init(). In that case it shut down all the Ethumb_Client modules dependencies.
Once this function succeeds (that is, 0
is returned), you must not call any of the Eina function anymore. You must call ethumb_client_init() again to use the Ethumb_Client functions again.
EAPI Ethumb_Client* ethumb_client_connect | ( | Ethumb_Client_Connect_Cb | connect_cb, |
const void * | data, | ||
Eina_Free_Cb | free_data | ||
) |
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 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().
- Parameters
-
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 data. Must not be NULL
. This function will not be called if user explicitly calls ethumb_client_disconnect().data context to give back to connect_cb. May be NULL
.free_data function used to release data resources, if any. May be NULL
. If this function exists, it will be called immediately after connect_cb is called or if user explicitly calls ethumb_client_disconnect() before such (that is, don't rely on data after connect_cb was called!)
- Returns
- client instance or NULL if failed. If connect_cb is missing it returns
NULL
. If it fail for other conditions,NULL
is also returned and connect_cb is called withsuccess=EINA_FALSE
. The client instance is not ready to be used until connect_cb is called.
EAPI void ethumb_client_disconnect | ( | Ethumb_Client * | client | ) |
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.
- Parameters
-
client client instance to be destroyed. Must not be NULL
.
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 | ||
) |
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!
- Parameters
-
client the client instance to monitor. Must not be NULL
.server_die_cb function to call back when server dies. The first parameter will be the argument data. May be NULL
.data context to give back to server_die_cb. May be NULL
.free_data used to release data resources after server_die_cb is called or user calls ethumb_client_disconnect().
EAPI Eina_Bool ethumb_client_file_set | ( | Ethumb_Client * | client, |
const char * | path, | ||
const char * | key | ||
) |
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().
- Parameters
-
client the client instance to use. Must not be NULL
. May be pending connected (can be called beforeconnected_cb
)path the filesystem path to use. May be NULL
.key the extra argument/key inside path to read image from. This is only used for formats that allow multiple resources in one file, like EET or Edje (group name).
- Returns
EINA_TRUE
on success,EINA_FALSE
on failure.
EAPI void ethumb_client_file_get | ( | Ethumb_Client * | client, |
const char ** | path, | ||
const char ** | key | ||
) |
Get values set with ethumb_client_file_get()
- Parameters
-
client the client instance to use. Must not be NULL
. May be pending connected (can be called beforeconnected_cb
)path where to return configured path. May be NULL
. If notNULL
, then it will be a pointer to a stringshared instance, but no references are added (do it with eina_stringshare_ref())!key where to return configured key. May be NULL.If
notNULL
, then it will be a pointer to a stringshared instance, but no references are added (do it with eina_stringshare_ref())!
EAPI void ethumb_client_file_free | ( | Ethumb_Client * | client | ) |
Reset previously set file to NULL
.
- Parameters
-
client the client instance to use. Must not be NULL
. May be pending connected (can be called beforeconnected_cb
)
EAPI Ethumb_Exists* ethumb_client_thumb_exists | ( | Ethumb_Client * | client, |
Ethumb_Client_Thumb_Exists_Cb | exists_cb, | ||
const void * | data | ||
) |
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!
- Parameters
-
client client instance. Must not be NULL
and client must be configured with ethumb_client_file_set().
- Returns
EINA_TRUE
if it exists,EINA_FALSE
otherwise.
EAPI void ethumb_client_thumb_exists_cancel | ( | Ethumb_Exists * | exists | ) |
Cancel an ongoing exists request.
- Parameters
-
exists the request to cancel.
EAPI Eina_Bool ethumb_client_thumb_exists_check | ( | Ethumb_Exists * | exists | ) |
Check if an exists request was cancelled.
- Parameters
-
exists the request to check.
- Returns
- return EINA_TRUE if the request was cancelled.
EAPI int ethumb_client_generate | ( | Ethumb_Client * | client, |
Ethumb_Client_Generate_Cb | generated_cb, | ||
const void * | data, | ||
Eina_Free_Cb | free_data | ||
) |
Ask server to generate thumbnail.
This process is asynchronous and will report back from main loop using 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.
- Parameters
-
client client instance. Must not be NULL
and client must be connected (after connected_cb is called).generated_cb function to report generation results. data context argument to give back to generated_cb. May be NULL
.data context to give back to generate_cb. May be NULL
.free_data used to release data resources after generated_cb is called or user calls ethumb_client_disconnect().
- Returns
- identifier or -1 on error. If -1 is returned (error) then free_data is not called!
- See Also
- ethumb_client_connect()
- ethumb_client_file_set()
- ethumb_client_thumb_exists()
- ethumb_client_generate_cancel()
- ethumb_client_generate_cancel_all()
References ethumb_client_ethumb_setup().
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 | ||
) |
Ask server to cancel generation of thumbnail.
- Parameters
-
client client instance. Must not be NULL
and client must be connected (after connected_cb is called).id valid id returned by ethumb_client_generate() cancel_cb function to report cancellation results. data context argument to give back to cancel_cb. May be NULL
.data context to give back to cancel_cb. May be NULL
.free_data used to release data resources after cancel_cb is called or user calls ethumb_client_disconnect().
EAPI void ethumb_client_generate_cancel_all | ( | Ethumb_Client * | client | ) |
Ask server to cancel generation of all thumbnails.
- Parameters
-
client client instance. Must not be NULL
and client must be connected (after connected_cb is called).
- See Also
- ethumb_client_generate_cancel()