Typedefs | Functions
Ethumb Client Basics

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_Clientethumb_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_Existsethumb_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

◆ Ethumb_Client

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.

◆ Ethumb_Exists

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

◆ Ethumb_Client_Connect_Cb

typedef void(* Ethumb_Client_Connect_Cb) (void *data, Ethumb_Client *client, Eina_Bool success)

reports results of ethumb_client_connect()

Parameters
dataextra context given to ethumb_client_connect().
clienthandle of the current connection to server.
successEINA_TRUE if connected or EINA_FALSE if it was not possible.

◆ Ethumb_Client_Die_Cb

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
dataextra context given to ethumb_client_on_server_die_callback_set().
clienthandle of the current connection to server.

◆ Ethumb_Client_Generate_Cb

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
dataextra context given to ethumb_client_generate().
clienthandle of the current connection to server.
ididentifier returned by ethumb_client_generate().
filepath set with ethumb_client_file_set().
keyvalue set with ethumb_client_file_set() or NULL.
thumb_pathwhere thumbnail was stored, either set with ethumb_client_thumb_path_set() or automatically calculated using parameters.
thumb_keykey inside thumb_path where thumbnail was stored or NULL.
successEINA_TRUE if generated or EINA_FALSE on errors.

◆ Ethumb_Client_Thumb_Exists_Cb

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
clienthandle of the current connection to server.
existsEINA_TRUE if the thumbnail exists.
dataextra context given to ethumb_client_thumb_exists().

During the execution of the callback the state of the client is temporarily really restored to what it was when the call to ethumb_client_thumb_exists() was done.

◆ Ethumb_Client_Generate_Cancel_Cb

typedef void(* Ethumb_Client_Generate_Cancel_Cb) (void *data, Eina_Bool success)

reports results of ethumb_client_generate_cancel()

Parameters
dataextra context given to ethumb_client_generate_cancel()
clienthandle of the current connection to server.

Function Documentation

◆ ethumb_client_init()

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.

See also
ethumb_client_shutdown()
ethumb_client_connect()
Client-Server Thumbnailing Tutorial

References eina_init().

◆ ethumb_client_shutdown()

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.

References eina_hash_free(), eina_log_domain_unregister(), eldbus_shutdown(), and ethumb_shutdown().

◆ ethumb_client_connect()

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_cbfunction 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().
datacontext to give back to connect_cb. May be NULL.
free_datafunction 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 with success=EINA_FALSE. The client instance is not ready to be used until connect_cb is called.

References EINA_SAFETY_ON_NULL_RETURN_VAL, eldbus_connection_get(), ERR, and ethumb_new().

◆ ethumb_client_disconnect()

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
clientclient instance to be destroyed. Must not be NULL.

References EINA_REFCOUNT_UNREF, and EINA_SAFETY_ON_NULL_RETURN.

◆ ethumb_client_on_server_die_callback_set()

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
clientthe client instance to monitor. Must not be NULL.
server_die_cbfunction to call back when server dies. The first parameter will be the argument data. May be NULL.
datacontext to give back to server_die_cb. May be NULL.
free_dataused to release data resources after server_die_cb is called or user calls ethumb_client_disconnect().

References EINA_SAFETY_ON_NULL_RETURN.

◆ ethumb_client_file_set()

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
clientthe client instance to use. Must not be NULL. May be pending connected (can be called before connected_cb)
paththe filesystem path to use. May be NULL.
keythe 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.

References EINA_SAFETY_ON_NULL_RETURN_VAL, and ethumb_file_set().

◆ ethumb_client_file_get()

EAPI void ethumb_client_file_get ( Ethumb_Client client,
const char **  path,
const char **  key 
)

Get values set with ethumb_client_file_get()

Parameters
clientthe client instance to use. Must not be NULL. May be pending connected (can be called before connected_cb)
pathwhere to return configured path. May be NULL. If not NULL, then it will be a pointer to a stringshared instance, but no references are added (do it with eina_stringshare_ref())!
keywhere to return configured key. May be NULL.If not NULL, then it will be a pointer to a stringshared instance, but no references are added (do it with eina_stringshare_ref())!

References EINA_SAFETY_ON_NULL_RETURN, and ethumb_file_get().

◆ ethumb_client_file_free()

EAPI void ethumb_client_file_free ( Ethumb_Client client)

Reset previously set file to NULL.

Parameters
clientthe client instance to use. Must not be NULL. May be pending connected (can be called before connected_cb)

References EINA_SAFETY_ON_NULL_RETURN, and ethumb_file_free().

◆ ethumb_client_thumb_exists()

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
clientclient instance. Must not be NULL and client must be configured with ethumb_client_file_set().
Returns
NULL on failure, a valid Ethumb_Exists pointer otherwise

References ecore_thread_run(), EINA_FALSE, eina_hash_direct_add(), eina_hash_find(), eina_list_append(), EINA_REFCOUNT_REF, EINA_SAFETY_ON_NULL_RETURN_VAL, eina_stringshare_del(), eina_stringshare_ref(), ethumb_dup(), ethumb_file_get(), and ethumb_free().

◆ ethumb_client_thumb_exists_cancel()

EAPI void ethumb_client_thumb_exists_cancel ( Ethumb_Exists exists)

Cancel an ongoing exists request.

Parameters
existsthe request to cancel.

References ecore_thread_cancel(), eina_list_count(), eina_list_remove(), EINA_REFCOUNT_UNREF, and ethumb_free().

◆ ethumb_client_thumb_exists_check()

EAPI Eina_Bool ethumb_client_thumb_exists_check ( Ethumb_Exists exists)

Check if an exists request was cancelled.

Parameters
existsthe request to check.
Returns
return EINA_TRUE if the request was cancelled.

References ecore_thread_check(), EINA_FALSE, and EINA_TRUE.

◆ ethumb_client_generate()

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
clientclient instance. Must not be NULL and client must be connected (after connected_cb is called).
generated_cbfunction to report generation results.
datacontext argument to give back to generated_cb. May be NULL.
datacontext to give back to generate_cb. May be NULL.
free_dataused 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 EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, ERR, and ethumb_file_get().

◆ ethumb_client_generate_cancel()

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
clientclient instance. Must not be NULL and client must be connected (after connected_cb is called).
idvalid id returned by ethumb_client_generate()
cancel_cbfunction to report cancellation results.
datacontext argument to give back to cancel_cb. May be NULL.
datacontext to give back to cancel_cb. May be NULL.
free_dataused to release data resources after cancel_cb is called or user calls ethumb_client_disconnect().

◆ ethumb_client_generate_cancel_all()

EAPI void ethumb_client_generate_cancel_all ( Ethumb_Client client)

Ask server to cancel generation of all thumbnails.

Parameters
clientclient instance. Must not be NULL and client must be connected (after connected_cb is called).
See also
ethumb_client_generate_cancel()

References EINA_LIST_FREE, and EINA_SAFETY_ON_NULL_RETURN.