[libgdata] documents: Add a cancellable parameter to gdata_documents_document_download()

[Philip Withnall <pwithnall src gnome org>]

commit 032a5bc08986f66735846ffec3d1daafcd62cd0f
Author: Philip Withnall <philip tecnocode co uk>
Date:   Sat Dec 18 12:39:43 2010 +0000

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

 .../services/documents/gdata-documents-document.c  |   11 +++++++++--
 .../services/documents/gdata-documents-document.h  |    2 +-
 gdata/tests/documents.c                            |    6 +++---
 3 files changed, 13 insertions(+), 6 deletions(-)
---
diff --git a/gdata/services/documents/gdata-documents-document.c b/gdata/services/documents/gdata-documents-document.c
index f2e62dd..21ec781 100644
--- a/gdata/services/documents/gdata-documents-document.c
+++ b/gdata/services/documents/gdata-documents-document.c
@@ -62,6 +62,7 @@ gdata_documents_document_init (GDataDocumentsDocument *self)
  * @self: a #GDataDocumentsDocument
  * @service: a #GDataDocumentsService
  * @export_format: the format in which the document should be exported
+ * @cancellable: (allow-none): a #GCancellable for the entire download stream, or %NULL
  * @error: a #GError, or %NULL
  *
  * Downloads and returns the document file represented by the #GDataDocumentsDocument. If the document doesn't exist, %NULL is returned, but no error
@@ -79,6 +80,10 @@ gdata_documents_document_init (GDataDocumentsDocument *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.
+ *
  * If @service isn't authenticated, a %GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED will be returned.
  *
  * If there is an error getting the document, a %GDATA_SERVICE_ERROR_PROTOCOL_ERROR error will be returned.
@@ -88,7 +93,8 @@ gdata_documents_document_init (GDataDocumentsDocument *self)
  * Since: 0.8.0
  **/
 GDataDownloadStream *
-gdata_documents_document_download (GDataDocumentsDocument *self, GDataDocumentsService *service, const gchar *export_format, GError **error)
+gdata_documents_document_download (GDataDocumentsDocument *self, GDataDocumentsService *service, const gchar *export_format, GCancellable *cancellable,
+                                   GError **error)
 {
 	gchar *download_uri;
 	GDataService *_service;
@@ -97,6 +103,7 @@ gdata_documents_document_download (GDataDocumentsDocument *self, GDataDocumentsS
 	g_return_val_if_fail (GDATA_IS_DOCUMENTS_DOCUMENT (self), NULL);
 	g_return_val_if_fail (GDATA_IS_SERVICE (service), NULL);
 	g_return_val_if_fail (export_format != NULL && *export_format != '\0', NULL);
+	g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 	g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 
 	/* Horrible hack to force use of the spreadsheet service if the document we're downloading is a spreadsheet. This is necessary because it's
@@ -115,7 +122,7 @@ gdata_documents_document_download (GDataDocumentsDocument *self, GDataDocumentsS
 
 	/* Get the download URI and create a stream for it */
 	download_uri = gdata_documents_document_get_download_uri (self, export_format);
-	download_stream = GDATA_DOWNLOAD_STREAM (gdata_download_stream_new (_service, download_uri, NULL));
+	download_stream = GDATA_DOWNLOAD_STREAM (gdata_download_stream_new (_service, download_uri, cancellable));
 	g_free (download_uri);
 
 	return download_stream;
diff --git a/gdata/services/documents/gdata-documents-document.h b/gdata/services/documents/gdata-documents-document.h
index 1493d3e..2385fd7 100644
--- a/gdata/services/documents/gdata-documents-document.h
+++ b/gdata/services/documents/gdata-documents-document.h
@@ -66,7 +66,7 @@ GType gdata_documents_document_get_type (void) G_GNUC_CONST;
 #include <gdata/services/documents/gdata-documents-service.h>
 
 GDataDownloadStream *gdata_documents_document_download (GDataDocumentsDocument *self, GDataDocumentsService *service, const gchar *export_format,
-                                                        GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
+                                                        GCancellable *cancellable, GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
 gchar *gdata_documents_document_get_download_uri (GDataDocumentsDocument *self, const gchar *export_format) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
 
 G_END_DECLS
diff --git a/gdata/tests/documents.c b/gdata/tests/documents.c
index 51c22f3..12dcb72 100644
--- a/gdata/tests/documents.c
+++ b/gdata/tests/documents.c
@@ -969,17 +969,17 @@ test_download_all_documents (gconstpointer service)
 			/* Presentation */
 			destination_file_extension = "odp";
 			download_stream = gdata_documents_document_download (GDATA_DOCUMENTS_DOCUMENT (i->data), GDATA_DOCUMENTS_SERVICE (service),
-			                                                     GDATA_DOCUMENTS_PRESENTATION_PPT, &error);
+			                                                     GDATA_DOCUMENTS_PRESENTATION_PPT, NULL, &error);
 		} else if (GDATA_IS_DOCUMENTS_SPREADSHEET (i->data)) {
 			/* Spreadsheet */
 			destination_file_extension = "ods";
 			download_stream = gdata_documents_document_download (GDATA_DOCUMENTS_DOCUMENT (i->data), GDATA_DOCUMENTS_SERVICE (service),
-			                                                     GDATA_DOCUMENTS_SPREADSHEET_ODS, &error);
+			                                                     GDATA_DOCUMENTS_SPREADSHEET_ODS, NULL, &error);
 		} else if (GDATA_IS_DOCUMENTS_TEXT (i->data)) {
 			/* Text document */
 			destination_file_extension = "odt";
 			download_stream = gdata_documents_document_download (GDATA_DOCUMENTS_DOCUMENT (i->data), GDATA_DOCUMENTS_SERVICE (service),
-			                                                     GDATA_DOCUMENTS_TEXT_ODT, &error);
+			                                                     GDATA_DOCUMENTS_TEXT_ODT, NULL, &error);
 		} else {
 			/* Error! */
 			g_assert_not_reached ();