[evolution] Add EPhotoSource interface.

[Matthew Barnes <mbarnes src gnome org>]

commit 5991b04ac5b48980f4d384951d619b3ec696e17f
Author: Matthew Barnes <mbarnes redhat com>
Date:   Fri Apr 19 08:15:03 2013 -0400

    Add EPhotoSource interface.
    
    EPhotoSource is an interface used to extend the functionality of
    EPhotoCache.  You can add an object implementing EPhotoSource to an
    EPhotoCache with e_photo_cache_add_photo_source() and remove it with
    e_photo_cache_remove_photo_source().  When EPhotoCache needs a photo
    for an email address, it will invoke e_photo_source_get_photo() on all
    available EPhotoSource objects simultaneously and select one photo.

 doc/reference/libeutil/libeutil-docs.sgml    |    1 +
 doc/reference/libeutil/libeutil-sections.txt |   15 +++
 doc/reference/libeutil/libeutil.types        |    1 +
 e-util/Makefile.am                           |    2 +
 e-util/e-photo-source.c                      |  123 ++++++++++++++++++++++++++
 e-util/e-photo-source.h                      |   76 ++++++++++++++++
 e-util/e-util.h                              |    1 +
 7 files changed, 219 insertions(+), 0 deletions(-)
---
diff --git a/doc/reference/libeutil/libeutil-docs.sgml b/doc/reference/libeutil/libeutil-docs.sgml
index 2d705be..0928cda 100644
--- a/doc/reference/libeutil/libeutil-docs.sgml
+++ b/doc/reference/libeutil/libeutil-docs.sgml
@@ -249,6 +249,7 @@
     <xi:include href="xml/e-online-button.xml"/>
     <xi:include href="xml/e-paned.xml"/>
     <xi:include href="xml/e-photo-cache.xml"/>
+    <xi:include href="xml/e-photo-source.xml"/>
     <xi:include href="xml/e-picture-gallery.xml"/>
     <xi:include href="xml/e-poolv.xml"/>
     <xi:include href="xml/e-popup-action.xml"/>
diff --git a/doc/reference/libeutil/libeutil-sections.txt b/doc/reference/libeutil/libeutil-sections.txt
index 0c89894..4942067 100644
--- a/doc/reference/libeutil/libeutil-sections.txt
+++ b/doc/reference/libeutil/libeutil-sections.txt
@@ -2507,6 +2507,21 @@ EPhotoCachePrivate
 </SECTION>
 
 <SECTION>
+<FILE>e-photo-source</FILE>
+<TITLE>EPhotoSource</TITLE>
+EPhotoSource
+EPhotoSourceInterface
+e_photo_source_get_photo
+e_photo_source_get_photo_finish
+<SUBSECTION Standard>
+E_PHOTO_SOURCE
+E_IS_PHOTO_SOURCE
+E_TYPE_PHOTO_SOURCE
+E_PHOTO_SOURCE_GET_INTERFACE
+e_photo_source_get_type
+</SECTION>
+
+<SECTION>
 <FILE>e-picture-gallery</FILE>
 <TITLE>EPictureGallery</TITLE>
 EPictureGallery
diff --git a/doc/reference/libeutil/libeutil.types b/doc/reference/libeutil/libeutil.types
index bd867ba..41065e0 100644
--- a/doc/reference/libeutil/libeutil.types
+++ b/doc/reference/libeutil/libeutil.types
@@ -92,6 +92,7 @@ e_name_selector_model_get_type
 e_online_button_get_type
 e_paned_get_type
 e_photo_cache_get_type
+e_photo_source_get_type
 e_picture_gallery_get_type
 e_plugin_get_type
 e_plugin_hook_get_type
diff --git a/e-util/Makefile.am b/e-util/Makefile.am
index e7a8f79..933bdd8 100644
--- a/e-util/Makefile.am
+++ b/e-util/Makefile.am
@@ -216,6 +216,7 @@ eutilinclude_HEADERS =  \
        e-paned.h \
        e-passwords.h \
        e-photo-cache.h \
+       e-photo-source.h \
        e-picture-gallery.h \
        e-plugin-ui.h \
        e-plugin.h \
@@ -464,6 +465,7 @@ libeutil_la_SOURCES = \
        e-paned.c \
        e-passwords.c \
        e-photo-cache.c \
+       e-photo-source.c \
        e-picture-gallery.c \
        e-plugin-ui.c \
        e-plugin.c \
diff --git a/e-util/e-photo-source.c b/e-util/e-photo-source.c
new file mode 100644
index 0000000..d3c65c9
--- /dev/null
+++ b/e-util/e-photo-source.c
@@ -0,0 +1,123 @@
+/*
+ * e-photo-source.c
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with the program; if not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+/**
+ * SECTION: e-photo-source
+ * @include: e-util/e-util.h
+ * @short_description: A source of email address photos
+ *
+ * #EPhotoSource is an interface used to extend the functionality of
+ * #EPhotoCache.  You can add an object implementing #EPhotoSource to an
+ * #EPhotoCache with e_photo_cache_add_photo_source() and remove it with
+ * e_photo_cache_remove_photo_source().  When #EPhotoCache needs a photo
+ * for an email addres, it will invoke e_photo_source_get_photo() on all
+ * available #EPhotoSource objects simultaneously and select one photo.
+ **/
+
+#include "e-photo-source.h"
+
+G_DEFINE_INTERFACE (
+       EPhotoSource,
+       e_photo_source,
+       G_TYPE_OBJECT)
+
+static void
+e_photo_source_default_init (EPhotoSourceInterface *interface)
+{
+}
+
+/**
+ * e_photo_source_get_photo:
+ * @photo_source: an #EPhotoSource
+ * @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
+ *
+ * Asynchronously searches for a photo or logo for @email_address.
+ *
+ * When the operation is finished, @callback will be called.  You can then
+ * call e_photo_source_get_photo_finish() to get the result of the operation.
+ **/
+void
+e_photo_source_get_photo (EPhotoSource *photo_source,
+                          const gchar *email_address,
+                          GCancellable *cancellable,
+                          GAsyncReadyCallback callback,
+                          gpointer user_data)
+{
+       EPhotoSourceInterface *interface;
+
+       g_return_if_fail (E_IS_PHOTO_SOURCE (photo_source));
+       g_return_if_fail (email_address != NULL);
+
+       interface = E_PHOTO_SOURCE_GET_INTERFACE (photo_source);
+       g_return_if_fail (interface->get_photo != NULL);
+
+       interface->get_photo (
+               photo_source, email_address,
+               cancellable, callback, user_data);
+}
+
+/**
+ * e_photo_source_get_photo_finish:
+ * @photo_source: an #EPhotoSource
+ * @result: a #GAsyncResult
+ * @out_stream: return location for a #GInputStream
+ * @out_priority: return location for a priority value, or %NULL
+ * @error: return location for a #GError, or %NULL
+ *
+ * Finishes the operation started with e_photo_source_get_photo().
+ *
+ * If a match was found, a #GInputStream from which to read image data is
+ * returned through the @out_stream return location, and a suggested priority
+ * value for the match is returned through the @out_priority return location.
+ *
+ * You can use the @out_priority value to rank this result among other
+ * #EPhotoSource results.  The value is usually @G_PRIORITY_DEFAULT, but
+ * may be @G_PRIORITY_LOW if the result is a fallback image.
+ *
+ * If no match was found, the @out_stream return location is set to %NULL
+ * (the @out_priority return location will remain unset).
+ *
+ * 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.
+ *
+ * Returns: whether the search completed successfully
+ **/
+gboolean
+e_photo_source_get_photo_finish (EPhotoSource *photo_source,
+                                 GAsyncResult *result,
+                                 GInputStream **out_stream,
+                                 gint *out_priority,
+                                 GError **error)
+{
+       EPhotoSourceInterface *interface;
+
+       g_return_val_if_fail (E_IS_PHOTO_SOURCE (photo_source), FALSE);
+       g_return_val_if_fail (G_IS_ASYNC_RESULT (result), FALSE);
+       g_return_val_if_fail (out_stream != NULL, FALSE);
+
+       interface = E_PHOTO_SOURCE_GET_INTERFACE (photo_source);
+       g_return_val_if_fail (interface->get_photo_finish != NULL, FALSE);
+
+       return interface->get_photo_finish (
+               photo_source, result, out_stream, out_priority, error);
+}
+
diff --git a/e-util/e-photo-source.h b/e-util/e-photo-source.h
new file mode 100644
index 0000000..dfbaf26
--- /dev/null
+++ b/e-util/e-photo-source.h
@@ -0,0 +1,76 @@
+/*
+ * e-photo-source.h
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with the program; if not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+#if !defined (__E_UTIL_H_INSIDE__) && !defined (LIBEUTIL_COMPILATION)
+#error "Only <e-util/e-util.h> should be included directly."
+#endif
+
+#ifndef E_PHOTO_SOURCE_H
+#define E_PHOTO_SOURCE_H
+
+#include <gio/gio.h>
+
+/* Standard GObject macros */
+#define E_TYPE_PHOTO_SOURCE \
+       (e_photo_source_get_type ())
+#define E_PHOTO_SOURCE(obj) \
+       (G_TYPE_CHECK_INSTANCE_CAST \
+       ((obj), E_TYPE_PHOTO_SOURCE, EPhotoSource))
+#define E_IS_PHOTO_SOURCE(obj) \
+       (G_TYPE_CHECK_INSTANCE_TYPE \
+       ((obj), E_TYPE_PHOTO_SOURCE))
+#define E_PHOTO_SOURCE_GET_INTERFACE(obj) \
+       (G_TYPE_INSTANCE_GET_INTERFACE \
+       ((obj), E_TYPE_PHOTO_SOURCE, EPhotoSourceInterface))
+
+G_BEGIN_DECLS
+
+typedef struct _EPhotoSource EPhotoSource;
+typedef struct _EPhotoSourceInterface EPhotoSourceInterface;
+
+struct _EPhotoSourceInterface {
+       GTypeInterface parent_interface;
+
+       void            (*get_photo)            (EPhotoSource *photo_source,
+                                                const gchar *email_address,
+                                                GCancellable *cancellable,
+                                                GAsyncReadyCallback callback,
+                                                gpointer user_data);
+       gboolean        (*get_photo_finish)     (EPhotoSource *photo_source,
+                                                GAsyncResult *result,
+                                                GInputStream **out_stream,
+                                                gint *out_priority,
+                                                GError **error);
+};
+
+GType          e_photo_source_get_type         (void) G_GNUC_CONST;
+void           e_photo_source_get_photo        (EPhotoSource *photo_source,
+                                                const gchar *email_address,
+                                                GCancellable *cancellable,
+                                                GAsyncReadyCallback callback,
+                                                gpointer user_data);
+gboolean       e_photo_source_get_photo_finish (EPhotoSource *photo_source,
+                                                GAsyncResult *result,
+                                                GInputStream **out_stream,
+                                                gint *out_priority,
+                                                GError **error);
+
+G_END_DECLS
+
+#endif /* E_PHOTO_SOURCE_H */
+
diff --git a/e-util/e-util.h b/e-util/e-util.h
index 3870c45..34d4586 100644
--- a/e-util/e-util.h
+++ b/e-util/e-util.h
@@ -132,6 +132,7 @@
 #include <e-util/e-paned.h>
 #include <e-util/e-passwords.h>
 #include <e-util/e-photo-cache.h>
+#include <e-util/e-photo-source.h>
 #include <e-util/e-picture-gallery.h>
 #include <e-util/e-plugin-ui.h>
 #include <e-util/e-plugin.h>