|  |  |  | Evolution Utilities Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals | ||||
#include <e-util/e-util.h> struct EClientCache; EClientCache * e_client_cache_new (ESourceRegistry *registry); ESourceRegistry * e_client_cache_ref_registry (EClientCache *client_cache); EClient * e_client_cache_get_client_sync (EClientCache *client_cache,ESource *source,const gchar *extension_name,GCancellable *cancellable,GError **error); void e_client_cache_get_client (EClientCache *client_cache,ESource *source,const gchar *extension_name,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); EClient * e_client_cache_get_client_finish (EClientCache *client_cache,GAsyncResult *result,GError **error); EClient * e_client_cache_ref_cached_client (EClientCache *client_cache,ESource *source,const gchar *extension_name); gboolean e_client_cache_is_backend_dead (EClientCache *client_cache,ESource *source,const gchar *extension_name);
"backend-died" :Run Last"backend-error" :Run Last"client-connected" :Run First"client-created" :Run First"client-notify" :No Hooks
EClientCache provides for application-wide sharing of EClient instances and centralized rebroadcasting of "backend-died", "backend-error" and "notify" signals from cached EClient instances.
EClientCache automatically invalidates cache entries in response to "backend-died" signals. The EClient instance is discarded, and a new instance is created on the next request.
struct EClientCache;
Contains only private data that should be read and manipulated using the functions below.
EClientCache *      e_client_cache_new                  (ESourceRegistry *registry);
Creates a new EClientCache instance.
| 
 | an ESourceRegistry | 
| Returns : | an EClientCache | 
ESourceRegistry *   e_client_cache_ref_registry         (EClientCache *client_cache);
Returns the ESourceRegistry passed to e_client_cache_new().
The returned ESourceRegistry is referenced for thread-safety and must be
unreferenced with g_object_unref() when finished with it.
| 
 | an EClientCache | 
| Returns : | an ESourceRegistry | 
EClient * e_client_cache_get_client_sync (EClientCache *client_cache,ESource *source,const gchar *extension_name,GCancellable *cancellable,GError **error);
Obtains a shared EClient instance for source, or else creates a new
EClient instance to be shared.
The extension_name determines the type of EClient to obtain.  Valid
extension_name values are:
E_SOURCE_EXTENSION_ADDRESS_BOOK will obtain an EBookClient.
E_SOURCE_EXTENSION_CALENDAR will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_EVENTS.
E_SOURCE_EXTENSION_MEMO_LIST will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_MEMOS.
E_SOURCE_EXTENSION_TASK_LIST will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_TASKS.
The source must already have an ESourceExtension by that name
for this function to work.  All other extension_name values will
result in an error.
If a request for the same source and extension_name is already in
progress when this function is called, this request will "piggyback"
on the in-progress request such that they will both succeed or fail
simultaneously.
Unreference the returned EClient with g_object_unref() when finished
with it.  If an error occurs, the function will set error and return
NULL.
| 
 | an EClientCache | 
| 
 | an ESource | 
| 
 | an extension name | 
| 
 | optional GCancellable object, or NULL | 
| 
 | return location for a GError, or NULL | 
| Returns : | an EClient, or NULL | 
void e_client_cache_get_client (EClientCache *client_cache,ESource *source,const gchar *extension_name,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously obtains a shared EClient instance for source, or else
creates a new EClient instance to be shared.
The extension_name determines the type of EClient to obtain.  Valid
extension_name values are:
E_SOURCE_EXTENSION_ADDRESS_BOOK will obtain an EBookClient.
E_SOURCE_EXTENSION_CALENDAR will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_EVENTS.
E_SOURCE_EXTENSION_MEMO_LIST will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_MEMOS.
E_SOURCE_EXTENSION_TASK_LIST will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_TASKS.
The source must already have an ESourceExtension by that name
for this function to work.  All other extension_name values will
result in an error.
If a request for the same source and extension_name is already in
progress when this function is called, this request will "piggyback"
on the in-progress request such that they will both succeed or fail
simultaneously.
When the operation is finished, callback will be called.  You can
then call e_client_cache_get_client_finish() to get the result of the
operation.
| 
 | an EClientCache | 
| 
 | an ESource | 
| 
 | an extension name | 
| 
 | optional GCancellable object, or NULL | 
| 
 | a GAsyncReadyCallback to call when the request is satisfied | 
| 
 | data to pass to the callback function | 
EClient * e_client_cache_get_client_finish (EClientCache *client_cache,GAsyncResult *result,GError **error);
Finishes the operation started with e_client_cache_get_client().
Unreference the returned EClient with g_object_unref() when finished
with it.  If an error occurred, the function will set error and return
NULL.
| 
 | an EClientCache | 
| 
 | a GAsyncResult | 
| 
 | return location for a GError, or NULL | 
| Returns : | an EClient, or NULL | 
EClient * e_client_cache_ref_cached_client (EClientCache *client_cache,ESource *source,const gchar *extension_name);
Returns a shared EClient instance for source and extension_name if
such an instance is already cached, or else NULL.  This function does
not create a new EClient instance, and therefore does not block.
See e_client_cache_get_client() for valid extension_name values.
The returned EClient is referenced for thread-safety and must be
unreferenced with g_object_unref() when finished with it.
| 
 | an EClientCache | 
| 
 | an ESource | 
| 
 | an extension name | 
| Returns : | an EClient, or NULL | 
gboolean e_client_cache_is_backend_dead (EClientCache *client_cache,ESource *source,const gchar *extension_name);
Returns TRUE if an EClient instance for source and extension_name
was recently discarded after having emitted a "backend-died"
signal, and a replacement EClient instance has not yet been created.
| 
 | an EClientCache | 
| 
 | an ESource | 
| 
 | an extension name | 
| Returns : | whether the backend for sourceandextension_namedied | 
"backend-died" signalvoid                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        EAlert       *alert,
                                                        gpointer      user_data)         : Run Last
Rebroadcasts a "backend-died" signal emitted by client,
along with a pre-formatted EAlert.
As a convenience to signal handlers, this signal is always
emitted from the GMainContext that was thread-default when
the client_cache was created.
| 
 | the EClientCache that received the signal | 
| 
 | the EClient that received the D-Bus notification | 
| 
 | an EAlert with a user-friendly error description | 
| 
 | user data set when the signal handler was connected. | 
"backend-error" signalvoid                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        EAlert       *alert,
                                                        gpointer      user_data)         : Run Last
Rebroadcasts a "backend-error" signal emitted by client,
along with a pre-formatted EAlert.
As a convenience to signal handlers, this signal is always
emitted from the GMainContext that was thread-default when
the client_cache was created.
| 
 | the EClientCache that received the signal | 
| 
 | the EClient that received the D-Bus notification | 
| 
 | an EAlert with a user-friendly error description | 
| 
 | user data set when the signal handler was connected. | 
"client-connected" signalvoid                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        gpointer      user_data)         : Run First
This signal is emitted when a call to e_client_cache_get_client()
triggers the creation of a new EClient instance, immediately after
the client's opening phase is over.
See the difference with EClientCache::client-created, which is called on idle.
| 
 | the EClientCache that received the signal | 
| 
 | the newly-created EClient | 
| 
 | user data set when the signal handler was connected. | 
"client-created" signalvoid                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        gpointer      user_data)         : Run First
This signal is emitted when a call to e_client_cache_get_client()
triggers the creation of a new EClient instance, invoked in an idle
callback.
See the difference with EClientCache::client-connected, which is called immediately.
| 
 | the EClientCache that received the signal | 
| 
 | the newly-created EClient | 
| 
 | user data set when the signal handler was connected. | 
"client-notify" signalvoid                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        GParamSpec   *pspec,
                                                        gpointer      user_data)         : No Hooks
Rebroadcasts a "notify" signal emitted by client.
This signal supports "::detail" appendices to the signal name just like the "notify" signal, so you can connect to change notification signals for specific EClient properties.
As a convenience to signal handlers, this signal is always
emitted from the GMainContext that was thread-default when
the client_cache was created.
| 
 | the EClientCache that received the signal | 
| 
 | the EClient whose property changed | 
| 
 | the GParamSpec of the property that changed | 
| 
 | user data set when the signal handler was connected. |