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