Ethumb_Client_Basics(3)

NAME
Ethumb_Client_Basics - Ethumb Client Basics

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

SYNOPSIS

  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

  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 or EINA_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 or EINA_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 really 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.

See also
    ethumb_client_shutdown()

    ethumb_client_connect()

    Client-Server Thumbnailing Tutorial

References eina_init().

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

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

  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.

  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.

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

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

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

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

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

  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.

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

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

References EINA_LIST_FREE, and EINA_SAFETY_ON_NULL_RETURN.

Author

Generated automatically by Doxygen for EFL from the source code.