Top |
Functions
EClientCache * | e_client_cache_new () |
ESourceRegistry * | e_client_cache_ref_registry () |
EClient * | e_client_cache_get_client_sync () |
void | e_client_cache_get_client () |
EClient * | e_client_cache_get_client_finish () |
EClient * | e_client_cache_ref_cached_client () |
gboolean | e_client_cache_is_backend_dead () |
void | e_client_cache_emit_allow_auth_prompt () |
Signals
void | allow-auth-prompt | Run First |
void | backend-died | Run Last |
void | backend-error | Run Last |
void | client-connected | Run First |
void | client-created | Run First |
void | client-notify | No Hooks |
Description
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.
Functions
e_client_cache_new ()
EClientCache *
e_client_cache_new (ESourceRegistry *registry
);
Creates a new EClientCache instance.
e_client_cache_ref_registry ()
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.
e_client_cache_get_client_sync ()
EClient * e_client_cache_get_client_sync (EClientCache *client_cache
,ESource *source
,const gchar *extension_name
,guint32 wait_for_connected_seconds
,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.
The wait_for_connected_seconds
argument had been added since 3.16,
to let the caller decide how long to wait for the backend to fully
connect to its (possibly remote) data store. This is required due
to a change in the authentication process, which is fully asynchronous
and done on the client side, while not every client is supposed to
response to authentication requests. In case the backend will not connect
within the set interval, then it is opened in an offline mode. A special
value -1 can be used to not wait for the connected state at all.
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
.
Parameters
client_cache |
an EClientCache |
|
source |
an ESource |
|
extension_name |
an extension name |
|
wait_for_connected_seconds |
timeout, in seconds, to wait for the backend to be fully connected |
|
cancellable |
optional GCancellable object, or |
|
error |
e_client_cache_get_client ()
void e_client_cache_get_client (EClientCache *client_cache
,ESource *source
,const gchar *extension_name
,guint32 wait_for_connected_seconds
,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.
The wait_for_connected_seconds
argument had been added since 3.16,
to let the caller decide how long to wait for the backend to fully
connect to its (possibly remote) data store. This is required due
to a change in the authentication process, which is fully asynchronous
and done on the client side, while not every client is supposed to
response to authentication requests. In case the backend will not connect
within the set interval, then it is opened in an offline mode. A special
value -1 can be used to not wait for the connected state at all.
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.
Parameters
client_cache |
an EClientCache |
|
source |
an ESource |
|
extension_name |
an extension name |
|
wait_for_connected_seconds |
timeout, in seconds, to wait for the backend to be fully connected |
|
cancellable |
optional GCancellable object, or |
|
callback |
a GAsyncReadyCallback to call when the request is satisfied |
|
user_data |
data to pass to the callback function |
e_client_cache_get_client_finish ()
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
.
e_client_cache_ref_cached_client ()
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.
e_client_cache_is_backend_dead ()
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.
e_client_cache_emit_allow_auth_prompt ()
void e_client_cache_emit_allow_auth_prompt (EClientCache *client_cache
,ESource *source
);
Emits 'allow-auth-prompt' on client_cache
for source
. This lets
any listeners know to enable credentials prompt for this source
.
Since: 3.16
Signal Details
The “allow-auth-prompt”
signal
void user_function (EClientCache *client_cache, ESource *source, gpointer user_data)
This signal is emitted with e_client_cache_emit_allow_auth_prompt()
to let
any listeners know to enable credentials prompt for the given source
.
Parameters
client_cache |
an EClientCache, which sent the signal |
|
source |
an ESource |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
Since: 3.16
The “backend-died”
signal
void user_function (EClientCache *client_cache, EClient *client, EAlert *alert, gpointer user_data)
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.
Parameters
client_cache |
the EClientCache that received the signal |
|
client |
the EClient that received the D-Bus notification |
|
alert |
an EAlert with a user-friendly error description |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “backend-error”
signal
void user_function (EClientCache *client_cache, EClient *client, EAlert *alert, gpointer user_data)
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.
Parameters
client_cache |
the EClientCache that received the signal |
|
client |
the EClient that received the D-Bus notification |
|
alert |
an EAlert with a user-friendly error description |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “client-connected”
signal
void user_function (EClientCache *client_cache, EClient *client, gpointer user_data)
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.
Parameters
client_cache |
the EClientCache that received the signal |
|
client |
the newly-created EClient |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “client-created”
signal
void user_function (EClientCache *client_cache, EClient *client, gpointer user_data)
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.
Parameters
client_cache |
the EClientCache that received the signal |
|
client |
the newly-created EClient |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
The “client-notify”
signal
void user_function (EClientCache *client_cache, EClient *client, GParamSpec *pspec, gpointer user_data)
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.
Parameters
client_cache |
the EClientCache that received the signal |
|
client |
the EClient whose property changed |
|
pspec |
the GParamSpec of the property that changed |
|
user_data |
user data set when the signal handler was connected. |
Flags: No Hooks