Ethumb Client Basics
Ethumb » Ethumb Client

Functions that all users must know of to use Ethumb_Client. More...

## Typedefs

typedef struct _Ethumb_Client | Ethumb_Client
| client handle.
typedef struct _Ethumb_Exists | Ethumb_Exists
| client exists request handle.
typedef void(* | Ethumb_Client_Connect_Cb) (void *data, Ethumb_Client *client, Eina_Bool success)
| reports results of ethumb_client_connect()
typedef void(* | Ethumb_Client_Die_Cb) (void *data, Ethumb_Client *client)
| reports server connection ended.
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().
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().
typedef void(* | Ethumb_Client_Generate_Cancel_Cb) (void *data, Eina_Bool success)
| reports results of ethumb_client_generate_cancel()
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.
EAPI int | ethumb_client_shutdown (void)
| Shut down the Ethumb_Client library.
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.
EAPI void | ethumb_client_disconnect (Ethumb_Client *client)
| Disconnect the client, releasing all client resources.
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.
EAPI Eina_Bool | ethumb_client_file_set (Ethumb_Client *client, const char *path, const char *key)
| Set source file to be thumbnailed.
EAPI void | ethumb_client_file_get (Ethumb_Client *client, const char **path, const char **key)
| Get values set with ethumb_client_file_get().
EAPI void | ethumb_client_file_free (Ethumb_Client *client)
| Reset previously set file to `NULL`.
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!).
EAPI void | ethumb_client_thumb_exists_cancel (Ethumb_Exists *exists)
| Cancel an ongoing exists request.
EAPI Eina_Bool | ethumb_client_thumb_exists_check (Ethumb_Exists *exists)
| Check if an exists 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.
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.
EAPI void | ethumb_client_generate_cancel_all (Ethumb_Client *client)
| Ask server to cancel generation of all thumbnails.
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_hash_stringshared_new(), eina_init(), eina_log_domain_register(), EINA_LOG_ERR, eina_shutdown(), eldbus_init(), ethumb_client_init(), and ethumb_init().

Referenced by elm_need_ethumb(), and ethumb_client_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(), eina_shutdown(), 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_FALSE, EINA_REFCOUNT_INIT, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, eldbus_connection_get(), eldbus_name_owner_changed_callback_add(), eldbus_name_start(), ERR, ethumb_free(), 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_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, ethumb_client_ethumb_setup(), ethumb_cmp(), ethumb_file_get(), and ethumb_free().

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

References _Eina_List::data, eina_list_append(), eina_list_remove_list(), EINA_SAFETY_ON_FALSE_RETURN, EINA_SAFETY_ON_NULL_RETURN, eina_stringshare_del(), eldbus_pending_cancel(), eldbus_proxy_call(), and _Eina_List::next.

## 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, EINA_SAFETY_ON_NULL_RETURN, eina_stringshare_del(), eldbus_pending_cancel(), and eldbus_proxy_call().