[libgdata] media: Add a cancellable parameter to gdata_media_thumbnail_download()

[Philip Withnall <pwithnall src gnome org>]

commit 4d2061ee2f614f5ff923d2f49f9218a8db38ddfd
Author: Philip Withnall <philip tecnocode co uk>
Date:   Sat Dec 18 12:46:07 2010 +0000

    media: Add a cancellable parameter to gdata_media_thumbnail_download()
    
    Add a cancellable parameter to gdata_media_thumbnail_download() to mirror
    GDataDownloadStream:cancellable. The tests have been updated accordingly.
    
    This breaks the following API:
    â?¢ gdata_media_thumbnail_download()
    
    Helps: bgo#637036

 gdata/media/gdata-media-thumbnail.c              |   10 ++++++++--
 gdata/media/gdata-media-thumbnail.h              |    2 +-
 gdata/services/picasaweb/gdata-picasaweb-album.c |    2 +-
 gdata/tests/picasaweb.c                          |    4 ++--
 4 files changed, 12 insertions(+), 6 deletions(-)
---
diff --git a/gdata/media/gdata-media-thumbnail.c b/gdata/media/gdata-media-thumbnail.c
index 0133850..ac985c9 100644
--- a/gdata/media/gdata-media-thumbnail.c
+++ b/gdata/media/gdata-media-thumbnail.c
@@ -365,6 +365,7 @@ gdata_media_thumbnail_get_time (GDataMediaThumbnail *self)
  * gdata_media_thumbnail_download:
  * @self: a #GDataMediaThumbnail
  * @service: the #GDataService
+ * @cancellable: (allow-none): a #GCancellable for the entire download stream, or %NULL
  * @error: a #GError, or %NULL
  *
  * Downloads and returns a #GDataDownloadStream allowing the thumbnail data represented by @self to be read.
@@ -373,22 +374,27 @@ gdata_media_thumbnail_get_time (GDataMediaThumbnail *self)
  * Calling gdata_download_stream_get_content_length() on the stream will not return a meaningful result, however, as the stream is encoded in chunks,
  * rather than by content length.
  *
+ * In order to cancel the download, a #GCancellable passed in to @cancellable must be cancelled using g_cancellable_cancel(). Cancelling the individual
+ * #GInputStream operations on the #GDataDownloadStream will not cancel the entire download; merely the read or close operation in question. See the
+ * #GDataDownloadStream:cancellable for more details.
+ *
  * Return value: (transfer full): a #GDataDownloadStream to download the thumbnail with, or %NULL; unref with g_object_unref()
  *
  * Since: 0.8.0
  **/
 GDataDownloadStream *
-gdata_media_thumbnail_download (GDataMediaThumbnail *self, GDataService *service, GError **error)
+gdata_media_thumbnail_download (GDataMediaThumbnail *self, GDataService *service, GCancellable *cancellable, GError **error)
 {
 	const gchar *src_uri;
 
 	g_return_val_if_fail (GDATA_IS_MEDIA_THUMBNAIL (self), NULL);
 	g_return_val_if_fail (GDATA_IS_SERVICE (service), NULL);
+	g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 	g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 
 	/* We keep a GError in the argument list so that we can add authentication errors, etc., in future if necessary */
 
 	/* Get the download URI and create a stream for it */
 	src_uri = gdata_media_thumbnail_get_uri (self);
-	return GDATA_DOWNLOAD_STREAM (gdata_download_stream_new (service, src_uri, NULL));
+	return GDATA_DOWNLOAD_STREAM (gdata_download_stream_new (service, src_uri, cancellable));
 }
diff --git a/gdata/media/gdata-media-thumbnail.h b/gdata/media/gdata-media-thumbnail.h
index c79548c..d033688 100644
--- a/gdata/media/gdata-media-thumbnail.h
+++ b/gdata/media/gdata-media-thumbnail.h
@@ -67,7 +67,7 @@ guint gdata_media_thumbnail_get_height (GDataMediaThumbnail *self) G_GNUC_PURE;
 guint gdata_media_thumbnail_get_width (GDataMediaThumbnail *self) G_GNUC_PURE;
 gint64 gdata_media_thumbnail_get_time (GDataMediaThumbnail *self) G_GNUC_PURE;
 
-GDataDownloadStream *gdata_media_thumbnail_download (GDataMediaThumbnail *self, GDataService *service,
+GDataDownloadStream *gdata_media_thumbnail_download (GDataMediaThumbnail *self, GDataService *service, GCancellable *cancellable,
                                                      GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
 
 G_END_DECLS
diff --git a/gdata/services/picasaweb/gdata-picasaweb-album.c b/gdata/services/picasaweb/gdata-picasaweb-album.c
index 240e6c1..f0f5fbe 100644
--- a/gdata/services/picasaweb/gdata-picasaweb-album.c
+++ b/gdata/services/picasaweb/gdata-picasaweb-album.c
@@ -65,7 +65,7 @@
  *			/<!-- -->* Do something fun with the thumbnails, like download and display them. We could just as easily download them into
  *			 * files using g_file_create() and g_output_stream_splice(), rather than create GdkPixbuf<!-- -->s directly from them.
  *			 * Note that this is a blocking operation. *<!-- -->/
- *			download_stream = gdata_media_thumbnail_download (thumbnail, GDATA_SERVICE (service), NULL);
+ *			download_stream = gdata_media_thumbnail_download (thumbnail, GDATA_SERVICE (service), NULL, NULL);
  *			pixbuf = gdk_pixbuf_new_from_stream (G_INPUT_STREAM (download_stream), NULL, NULL);
  *			g_object_unref (download_stream);
  *			/<!-- -->* ... *<!-- -->/
diff --git a/gdata/tests/picasaweb.c b/gdata/tests/picasaweb.c
index 0895267..21949c4 100644
--- a/gdata/tests/picasaweb.c
+++ b/gdata/tests/picasaweb.c
@@ -145,7 +145,7 @@ test_download_thumbnails (gconstpointer _service)
 	thumbnail = GDATA_MEDIA_THUMBNAIL (thumbnails->data);
 
 	/* Download a single thumbnail to a file for testing (in case we weren't compiled with GdkPixbuf support) */
-	download_stream = gdata_media_thumbnail_download (thumbnail, service, &error);
+	download_stream = gdata_media_thumbnail_download (thumbnail, service, NULL, &error);
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_DOWNLOAD_STREAM (download_stream));
 
@@ -182,7 +182,7 @@ test_download_thumbnails (gconstpointer _service)
 		thumbnail = GDATA_MEDIA_THUMBNAIL (node->data);
 
 		/* Prepare a download stream */
-		download_stream = gdata_media_thumbnail_download (thumbnail, service, &error);
+		download_stream = gdata_media_thumbnail_download (thumbnail, service, NULL, &error);
 		g_assert_no_error (error);
 		g_assert (GDATA_IS_DOWNLOAD_STREAM (download_stream));