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

[Philip Withnall <pwithnall src gnome org>]

commit 63e1cc0b4e8440f851549552da334fe0c58bdc47
Author: Philip Withnall <philip tecnocode co uk>
Date:   Sat Dec 18 12:43:07 2010 +0000

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

 gdata/media/gdata-media-content.c               |   10 ++++++++--
 gdata/media/gdata-media-content.h               |    2 +-
 gdata/services/picasaweb/gdata-picasaweb-file.c |    2 +-
 gdata/tests/picasaweb.c                         |    2 +-
 4 files changed, 11 insertions(+), 5 deletions(-)
---
diff --git a/gdata/media/gdata-media-content.c b/gdata/media/gdata-media-content.c
index a34caba..990f3c6 100644
--- a/gdata/media/gdata-media-content.c
+++ b/gdata/media/gdata-media-content.c
@@ -538,6 +538,7 @@ gdata_media_content_get_width (GDataMediaContent *self)
  * gdata_media_content_download:
  * @self: a #GDataMediaContent
  * @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 content represented by @self to be read.
@@ -546,22 +547,27 @@ gdata_media_content_get_width (GDataMediaContent *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 content with, or %NULL; unref with g_object_unref()
  *
  * Since: 0.8.0
  **/
 GDataDownloadStream *
-gdata_media_content_download (GDataMediaContent *self, GDataService *service, GError **error)
+gdata_media_content_download (GDataMediaContent *self, GDataService *service, GCancellable *cancellable, GError **error)
 {
 	const gchar *src_uri;
 
 	g_return_val_if_fail (GDATA_IS_MEDIA_CONTENT (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_content_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-content.h b/gdata/media/gdata-media-content.h
index da634e3..76ff476 100644
--- a/gdata/media/gdata-media-content.h
+++ b/gdata/media/gdata-media-content.h
@@ -108,7 +108,7 @@ gint64 gdata_media_content_get_duration (GDataMediaContent *self) G_GNUC_PURE;
 guint gdata_media_content_get_height (GDataMediaContent *self) G_GNUC_PURE;
 guint gdata_media_content_get_width (GDataMediaContent *self) G_GNUC_PURE;
 
-GDataDownloadStream *gdata_media_content_download (GDataMediaContent *self, GDataService *service,
+GDataDownloadStream *gdata_media_content_download (GDataMediaContent *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-file.c b/gdata/services/picasaweb/gdata-picasaweb-file.c
index ddbf932..7d64421 100644
--- a/gdata/services/picasaweb/gdata-picasaweb-file.c
+++ b/gdata/services/picasaweb/gdata-picasaweb-file.c
@@ -67,7 +67,7 @@
  *			content = GDATA_MEDIA_CONTENT (contents->data);
  *			/<!-- -->* Do something fun with the actual images, like download them to a file.
  *			 * Note that this is a blocking operation. *<!-- -->/
- *			download_stream = gdata_media_content_download (content, GDATA_SERVICE (service), NULL);
+ *			download_stream = gdata_media_content_download (content, GDATA_SERVICE (service), NULL, NULL);
  *			new_file = g_file_new_for_path (file_path);
  *			file_stream = g_file_create (new_file, G_FILE_CREATE_NONE, NULL, NULL);
  *			g_output_stream_splice (G_OUTPUT_STREAM (file_stream), G_INPUT_STREAM (download_stream),
diff --git a/gdata/tests/picasaweb.c b/gdata/tests/picasaweb.c
index cf12fe2..0895267 100644
--- a/gdata/tests/picasaweb.c
+++ b/gdata/tests/picasaweb.c
@@ -248,7 +248,7 @@ test_download (gconstpointer _service)
 	content = GDATA_MEDIA_CONTENT (media_contents->data);
 
 	/* Prepare a download stream */
-	download_stream = gdata_media_content_download (content, service, &error);
+	download_stream = gdata_media_content_download (content, service, NULL, &error);
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_DOWNLOAD_STREAM (download_stream));