EPhotoCache: Evolution Utilities Reference Manual

## EPhotoCache EPhotoCache — Search for photos by email address |

## Functions

EPhotoCache * | e_photo_cache_new ()
EClientCache * | e_photo_cache_ref_client_cache ()
void | e_photo_cache_add_photo_source ()
GList * | e_photo_cache_list_photo_sources ()
gboolean | e_photo_cache_remove_photo_source ()
void | e_photo_cache_add_photo ()
gboolean | e_photo_cache_remove_photo ()
gboolean | e_photo_cache_get_photo_sync ()
void | e_photo_cache_get_photo ()
gboolean | e_photo_cache_get_photo_finish ()

## Properties

EClientCache * | client-cache | Read / Write / Construct Only

## Types and Values

struct | EPhotoCache

## Object Hierarchy

        GObject
        ╰── EPhotoCache

## Implemented Interfaces

EPhotoCache implements EExtensible.

## Includes

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

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

## Functions

### e_photo_cache_new ()

    EPhotoCache *
    e_photo_cache_new (EClientCache *client_cache);

Creates a new EPhotoCache instance.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

## Types and Values

### struct EPhotoCache

    struct EPhotoCache;

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

## Property Details

### The `“client-cache”` property

      “client-cache”             EClientCache *

Cache of shared EClient instances.

Flags: Read / Write / Construct Only