EPhotoCache

EPhotoCache — Search for photos by email address

Synopsis

#include <e-util/e-util.h>

struct              EPhotoCache;
EPhotoCache *       e_photo_cache_new                   (EClientCache *client_cache);
EClientCache *      e_photo_cache_ref_client_cache      (EPhotoCache *photo_cache);
void                e_photo_cache_add_photo_source      (EPhotoCache *photo_cache,
                                                         EPhotoSource *photo_source);
GList *             e_photo_cache_list_photo_sources    (EPhotoCache *photo_cache);
gboolean            e_photo_cache_remove_photo_source   (EPhotoCache *photo_cache,
                                                         EPhotoSource *photo_source);
void                e_photo_cache_add_photo             (EPhotoCache *photo_cache,
                                                         const gchar *email_address,
                                                         GBytes *bytes);
gboolean            e_photo_cache_remove_photo          (EPhotoCache *photo_cache,
                                                         const gchar *email_address);
gboolean            e_photo_cache_get_photo_sync        (EPhotoCache *photo_cache,
                                                         const gchar *email_address,
                                                         GCancellable *cancellable,
                                                         GInputStream **out_stream,
                                                         GError **error);
void                e_photo_cache_get_photo             (EPhotoCache *photo_cache,
                                                         const gchar *email_address,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_photo_cache_get_photo_finish      (EPhotoCache *photo_cache,
                                                         GAsyncResult *result,
                                                         GInputStream **out_stream,
                                                         GError **error);

Object Hierarchy

  GObject
   +----EPhotoCache

Implemented Interfaces

EPhotoCache implements EExtensible.

Properties

  "client-cache"             EClientCache*         : Read / Write / Construct Only

Description

EPhotoCache finds photos associated with an email address.

A limited internal cache is employed to speed up frequently searched email addresses. The exact caching semantics are private and subject to change.

Details

struct EPhotoCache

struct EPhotoCache;

Contains only private data that should be read and manipulated using the functions below.


e_photo_cache_new ()

EPhotoCache *       e_photo_cache_new                   (EClientCache *client_cache);

Creates a new EPhotoCache instance.

client_cache :

an EClientCache

Returns :

an EPhotoCache

e_photo_cache_ref_client_cache ()

EClientCache *      e_photo_cache_ref_client_cache      (EPhotoCache *photo_cache);

Returns the EClientCache passed to e_photo_cache_new().

The returned EClientCache is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

photo_cache :

an EPhotoCache

Returns :

an EClientCache

e_photo_cache_add_photo_source ()

void                e_photo_cache_add_photo_source      (EPhotoCache *photo_cache,
                                                         EPhotoSource *photo_source);

Adds photo_source as a potential source of photos.

photo_cache :

an EPhotoCache

photo_source :

an EPhotoSource

e_photo_cache_list_photo_sources ()

GList *             e_photo_cache_list_photo_sources    (EPhotoCache *photo_cache);

Returns a list of photo sources for photo_cache.

The sources returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned list itself with g_list_free().

An easy way to free the list property in one step is as follows:

1
g_list_free_full (list, g_object_unref);

photo_cache :

an EPhotoCache

Returns :

a sorted list of photo sources

e_photo_cache_remove_photo_source ()

gboolean            e_photo_cache_remove_photo_source   (EPhotoCache *photo_cache,
                                                         EPhotoSource *photo_source);

Removes photo_source as a potential source of photos.

photo_cache :

an EPhotoCache

photo_source :

an EPhotoSource

Returns :

TRUE if photo_source was found and removed, FALSE if not

e_photo_cache_add_photo ()

void                e_photo_cache_add_photo             (EPhotoCache *photo_cache,
                                                         const gchar *email_address,
                                                         GBytes *bytes);

Adds a cache entry for email_address, such that subsequent photo requests for email_address will yield a GMemoryInputStream loaded with bytes without consulting available photo sources.

The bytes argument can also be NULL to indicate no photo is available for email_address. Subsequent photo requests for email_address will yield no input stream.

The entry may be removed without notice however, subject to photo_cache's internal caching policy.

photo_cache :

an EPhotoCache

email_address :

an email address

bytes :

a GBytes containing photo data, or NULL

e_photo_cache_remove_photo ()

gboolean            e_photo_cache_remove_photo          (EPhotoCache *photo_cache,
                                                         const gchar *email_address);

Removes the cache entry for email_address, if such an entry exists.

photo_cache :

an EPhotoCache

email_address :

an email address

Returns :

TRUE if a cache entry was found and removed

e_photo_cache_get_photo_sync ()

gboolean            e_photo_cache_get_photo_sync        (EPhotoCache *photo_cache,
                                                         const gchar *email_address,
                                                         GCancellable *cancellable,
                                                         GInputStream **out_stream,
                                                         GError **error);

Searches available photo sources for a photo associated with email_address.

If a match is found, a GInputStream from which to read image data is returned through the out_stream return location. If no match is found, the out_stream return location is set to NULL.

The return value indicates whether the search completed successfully, not whether a match was found. If an error occurs, the function will set error and return FALSE.

photo_cache :

an EPhotoCache

email_address :

an email address

cancellable :

optional GCancellable object, or NULL

out_stream :

return location for a GInputStream, or NULL

error :

return location for a GError, or NULL

Returns :

whether the search completed successfully

e_photo_cache_get_photo ()

void                e_photo_cache_get_photo             (EPhotoCache *photo_cache,
                                                         const gchar *email_address,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously searches available photo sources for a photo associated with email_address.

When the operation is finished, callback will be called. You can then call e_photo_cache_get_photo_finish() to get the result of the operation.

photo_cache :

an EPhotoCache

email_address :

an email address

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

e_photo_cache_get_photo_finish ()

gboolean            e_photo_cache_get_photo_finish      (EPhotoCache *photo_cache,
                                                         GAsyncResult *result,
                                                         GInputStream **out_stream,
                                                         GError **error);

Finishes the operation started with e_photo_cache_get_photo().

If a match was found, a GInputStream from which to read image data is returned through the out_stream return location. If no match was found, the out_stream return location is set to NULL.

The return value indicates whether the search completed successfully, not whether a match was found. If an error occurred, the function will set error and return FALSE.

photo_cache :

an EPhotoCache

result :

a GAsyncResult

out_stream :

return location for a GInputStream, or NULL

error :

return location for a GError, or NULL

Returns :

whether the search completed successfully

Property Details

The "client-cache" property

  "client-cache"             EClientCache*         : Read / Write / Construct Only

Cache of shared EClient instances.