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

◆ 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

data	extra context given to ethumb_client_connect().
client	handle of the current connection to server.
success	`EINA_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

data	extra context given to ethumb_client_on_server_die_callback_set().
client	handle 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

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

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

data	extra context given to ethumb_client_generate_cancel()
client	handle 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_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 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

client client 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

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

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

client	the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_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.

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

client	the client instance to use. Must not be `NULL`. May be pending connected (can be called before `connected_cb`)
path	where 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())!
key	where 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

client the 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

client client 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

exists the 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

exists the 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

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

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

◆ ethumb_client_generate_cancel_all()

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

References EINA_LIST_FREE, and EINA_SAFETY_ON_NULL_RETURN.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ Ethumb_Client

◆ Ethumb_Exists

◆ Ethumb_Client_Connect_Cb

◆ Ethumb_Client_Die_Cb

◆ Ethumb_Client_Generate_Cb

◆ Ethumb_Client_Thumb_Exists_Cb

◆ Ethumb_Client_Generate_Cancel_Cb

Function Documentation

◆ ethumb_client_init()

◆ ethumb_client_shutdown()

◆ ethumb_client_connect()

◆ ethumb_client_disconnect()

◆ ethumb_client_on_server_die_callback_set()

◆ ethumb_client_file_set()

◆ ethumb_client_file_get()

◆ ethumb_client_file_free()

◆ ethumb_client_thumb_exists()

◆ ethumb_client_thumb_exists_cancel()

◆ ethumb_client_thumb_exists_check()

◆ ethumb_client_generate()

◆ ethumb_client_generate_cancel()

◆ ethumb_client_generate_cancel_all()