[libgdata] documents: Add a cancellable parameter to the upload/update methods

[Philip Withnall <pwithnall src gnome org>]

commit 2641a723031b13b129cbe9b8e864115f0024a398
Author: Philip Withnall <philip tecnocode co uk>
Date:   Fri Dec 17 23:26:53 2010 +0000

    documents: Add a cancellable parameter to the upload/update methods
    
    Add a cancellable parameter to gdata_documents_service_upload_document()
    and gdata_documents_service_update_document() to mirror
    GDataUploadStream:cancellable. The tests have been updated accordingly.
    
    This breaks the following API:
     â?¢ gdata_documents_service_upload_document()
     â?¢ gdata_documents_service_update_document()
    
    Helps: bgo#637036

 gdata/services/documents/gdata-documents-service.c |   24 +++++++++++++++-----
 gdata/services/documents/gdata-documents-service.h |    5 ++-
 gdata/tests/documents.c                            |   14 +++++-----
 3 files changed, 28 insertions(+), 15 deletions(-)
---
diff --git a/gdata/services/documents/gdata-documents-service.c b/gdata/services/documents/gdata-documents-service.c
index 0e3c260..fdcb24a 100644
--- a/gdata/services/documents/gdata-documents-service.c
+++ b/gdata/services/documents/gdata-documents-service.c
@@ -291,7 +291,7 @@ notify_proxy_uri_cb (GObject *service, GParamSpec *pspec, GObject *self)
 
 static GDataUploadStream *
 upload_update_document (GDataDocumentsService *self, GDataDocumentsDocument *document, const gchar *slug, const gchar *content_type,
-                        const gchar *method, const gchar *upload_uri)
+                        const gchar *method, const gchar *upload_uri, GCancellable *cancellable)
 {
 	/* Corrects a bug on spreadsheet content types handling
 	 * The content type for ODF spreadsheets is "application/vnd.oasis.opendocument.spreadsheet" for my ODF spreadsheet;
@@ -303,7 +303,7 @@ upload_update_document (GDataDocumentsService *self, GDataDocumentsDocument *doc
 
 	/* We need streaming file I/O: GDataUploadStream */
 	return GDATA_UPLOAD_STREAM (gdata_upload_stream_new (GDATA_SERVICE (self), method, upload_uri, GDATA_ENTRY (document), slug, content_type,
-	                                                     NULL));
+	                                                     cancellable));
 }
 
 /**
@@ -313,6 +313,7 @@ upload_update_document (GDataDocumentsService *self, GDataDocumentsDocument *doc
  * @slug: the filename to give to the uploaded document
  * @content_type: the content type of the uploaded data
  * @folder: (allow-none): the folder to which the document should be uploaded, or %NULL
+ * @cancellable: (allow-none): a #GCancellable for the entire upload stream, or %NULL
  * @error: a #GError, or %NULL
  *
  * Uploads a document to Google Documents, using the properties from @document and the document data written to the resulting #GDataUploadStream. If
@@ -325,6 +326,10 @@ upload_update_document (GDataDocumentsService *self, GDataDocumentsDocument *doc
  * is closed (using g_output_stream_close()), gdata_documents_service_finish_upload() should be called on it to parse and return the updated
  * #GDataDocumentsDocument for the document. This must be done, as @document isn't updated in-place.
  *
+ * In order to cancel the upload, a #GCancellable passed in to @cancellable must be cancelled using g_cancellable_cancel(). Cancelling the individual
+ * #GOutputStream operations on the #GDataUploadStream will not cancel the entire upload; merely the write or close operation in question. See the
+ * #GDataUploadStream:cancellable for more details.
+ *
  * Any upload errors will be thrown by the stream methods, and may come from the #GDataServiceError domain.
  *
  * Return value: (transfer full): a #GDataUploadStream to write the document data to, or %NULL; unref with g_object_unref()
@@ -333,7 +338,7 @@ upload_update_document (GDataDocumentsService *self, GDataDocumentsDocument *doc
  **/
 GDataUploadStream *
 gdata_documents_service_upload_document (GDataDocumentsService *self, GDataDocumentsDocument *document, const gchar *slug, const gchar *content_type,
-                                         GDataDocumentsFolder *folder, GError **error)
+                                         GDataDocumentsFolder *folder, GCancellable *cancellable, GError **error)
 {
 	GDataUploadStream *upload_stream;
 	gchar *upload_uri;
@@ -343,6 +348,7 @@ gdata_documents_service_upload_document (GDataDocumentsService *self, GDataDocum
 	g_return_val_if_fail (slug != NULL && *slug != '\0', NULL);
 	g_return_val_if_fail (content_type != NULL && *content_type != '\0', NULL);
 	g_return_val_if_fail (folder == NULL || GDATA_IS_DOCUMENTS_FOLDER (folder), NULL);
+	g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 	g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 
 	if (gdata_service_is_authenticated (GDATA_SERVICE (self)) == FALSE) {
@@ -358,7 +364,7 @@ gdata_documents_service_upload_document (GDataDocumentsService *self, GDataDocum
 	}
 
 	upload_uri = gdata_documents_service_get_upload_uri (folder);
-	upload_stream = upload_update_document (self, document, slug, content_type, SOUP_METHOD_POST, upload_uri);
+	upload_stream = upload_update_document (self, document, slug, content_type, SOUP_METHOD_POST, upload_uri, cancellable);
 	g_free (upload_uri);
 
 	return upload_stream;
@@ -370,6 +376,7 @@ gdata_documents_service_upload_document (GDataDocumentsService *self, GDataDocum
  * @document: the #GDataDocumentsDocument to update
  * @slug: the filename to give to the uploaded document
  * @content_type: the content type of the uploaded data
+ * @cancellable: (allow-none): a #GCancellable for the entire upload stream, or %NULL
  * @error: a #GError, or %NULL
  *
  * Update the document using the properties from @document and the document data written to the resulting #GDataUploadStream. If the document data does
@@ -379,6 +386,10 @@ gdata_documents_service_upload_document (GDataDocumentsService *self, GDataDocum
  * is closed (using g_output_stream_close()), gdata_documents_service_finish_upload() should be called on it to parse and return the updated
  * #GDataDocumentsDocument for the document. This must be done, as @document isn't updated in-place.
  *
+ * In order to cancel the update, a #GCancellable passed in to @cancellable must be cancelled using g_cancellable_cancel(). Cancelling the individual
+ * #GOutputStream operations on the #GDataUploadStream will not cancel the entire update; merely the write or close operation in question. See the
+ * #GDataUploadStream:cancellable for more details.
+ *
  * Any upload errors will be thrown by the stream methods, and may come from the #GDataServiceError domain.
  *
  * For more information, see gdata_service_update_entry().
@@ -389,7 +400,7 @@ gdata_documents_service_upload_document (GDataDocumentsService *self, GDataDocum
  **/
 GDataUploadStream *
 gdata_documents_service_update_document (GDataDocumentsService *self, GDataDocumentsDocument *document, const gchar *slug, const gchar *content_type,
-                                         GError **error)
+                                         GCancellable *cancellable, GError **error)
 {
 	GDataLink *update_link;
 
@@ -397,6 +408,7 @@ gdata_documents_service_update_document (GDataDocumentsService *self, GDataDocum
 	g_return_val_if_fail (GDATA_IS_DOCUMENTS_DOCUMENT (document), NULL);
 	g_return_val_if_fail (slug != NULL && *slug != '\0', NULL);
 	g_return_val_if_fail (content_type != NULL && *content_type != '\0', NULL);
+	g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
 	g_return_val_if_fail (error == NULL || *error == NULL, NULL);
 
 	if (gdata_service_is_authenticated (GDATA_SERVICE (self)) == FALSE) {
@@ -408,7 +420,7 @@ gdata_documents_service_update_document (GDataDocumentsService *self, GDataDocum
 	update_link = gdata_entry_look_up_link (GDATA_ENTRY (document), GDATA_LINK_EDIT_MEDIA);
 	g_assert (update_link != NULL);
 
-	return upload_update_document (self, document, slug, content_type, SOUP_METHOD_PUT, gdata_link_get_uri (update_link));
+	return upload_update_document (self, document, slug, content_type, SOUP_METHOD_PUT, gdata_link_get_uri (update_link), cancellable);
 }
 
 /**
diff --git a/gdata/services/documents/gdata-documents-service.h b/gdata/services/documents/gdata-documents-service.h
index d9b2eee..8a25e31 100644
--- a/gdata/services/documents/gdata-documents-service.h
+++ b/gdata/services/documents/gdata-documents-service.h
@@ -93,9 +93,10 @@ void gdata_documents_service_query_documents_async (GDataDocumentsService *self,
 
 GDataUploadStream *gdata_documents_service_upload_document (GDataDocumentsService *self, GDataDocumentsDocument *document, const gchar *slug,
                                                             const gchar *content_type, GDataDocumentsFolder *folder,
-                                                            GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
+                                                            GCancellable *cancellable, GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
 GDataUploadStream *gdata_documents_service_update_document (GDataDocumentsService *self, GDataDocumentsDocument *document, const gchar *slug,
-                                                            const gchar *content_type, GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
+                                                            const gchar *content_type, GCancellable *cancellable,
+                                                            GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
 GDataDocumentsDocument *gdata_documents_service_finish_upload (GDataDocumentsService *self, GDataUploadStream *upload_stream,
                                                                GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
 
diff --git a/gdata/tests/documents.c b/gdata/tests/documents.c
index 0995978..51c22f3 100644
--- a/gdata/tests/documents.c
+++ b/gdata/tests/documents.c
@@ -231,7 +231,7 @@ test_upload_metadata_file (gconstpointer service)
 
 	/* Prepare the upload stream */
 	upload_stream = gdata_documents_service_upload_document (GDATA_DOCUMENTS_SERVICE (service), document, g_file_info_get_display_name (file_info),
-	                                                         g_file_info_get_content_type (file_info), NULL, &error);
+	                                                         g_file_info_get_content_type (file_info), NULL, NULL, &error);
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_UPLOAD_STREAM (upload_stream));
 
@@ -282,7 +282,7 @@ test_upload_file_get_entry (gconstpointer service)
 
 	/* Prepare the upload stream */
 	upload_stream = gdata_documents_service_upload_document (GDATA_DOCUMENTS_SERVICE (service), NULL, g_file_info_get_display_name (file_info),
-	                                                         g_file_info_get_content_type (file_info), NULL, &error);
+	                                                         g_file_info_get_content_type (file_info), NULL, NULL, &error);
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_UPLOAD_STREAM (upload_stream));
 
@@ -364,7 +364,7 @@ setup_folders (FoldersData *data, GDataDocumentsService *service, gboolean initi
 	/* Prepare the upload stream */
 	upload_stream = gdata_documents_service_upload_document (service, document, g_file_info_get_display_name (file_info),
 	                                                         g_file_info_get_content_type (file_info),
-	                                                         (initially_in_folder == TRUE) ? data->folder : NULL, &error);
+	                                                         (initially_in_folder == TRUE) ? data->folder : NULL, NULL, &error);
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_UPLOAD_STREAM (upload_stream));
 
@@ -679,7 +679,7 @@ test_upload_file_metadata_in_new_folder (gconstpointer service)
 
 	/* Prepare the upload stream */
 	upload_stream = gdata_documents_service_upload_document (GDATA_DOCUMENTS_SERVICE (service), document, g_file_info_get_display_name (file_info),
-	                                                         g_file_info_get_content_type (file_info), new_folder, &error);
+	                                                         g_file_info_get_content_type (file_info), new_folder, NULL, &error);
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_UPLOAD_STREAM (upload_stream));
 
@@ -811,7 +811,7 @@ test_update_metadata_file (gconstpointer service)
 	/* Prepare the upload stream */
 	upload_stream = gdata_documents_service_update_document (GDATA_DOCUMENTS_SERVICE (service), new_document2,
 	                                                         g_file_info_get_display_name (file_info), g_file_info_get_content_type (file_info),
-	                                                         &error);
+	                                                         NULL, &error);
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_UPLOAD_STREAM (upload_stream));
 
@@ -866,7 +866,7 @@ test_update_file (gconstpointer service)
 
 	/* Prepare the upload stream */
 	upload_stream = gdata_documents_service_upload_document (GDATA_DOCUMENTS_SERVICE (service), NULL, g_file_info_get_display_name (file_info),
-	                                                         g_file_info_get_content_type (file_info), NULL, &error);
+	                                                         g_file_info_get_content_type (file_info), NULL, NULL, &error);
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_UPLOAD_STREAM (upload_stream));
 
@@ -913,7 +913,7 @@ test_update_file (gconstpointer service)
 	/* Prepare the upload stream */
 	upload_stream = gdata_documents_service_update_document (GDATA_DOCUMENTS_SERVICE (service), new_document2,
 	                                                         g_file_info_get_display_name (file_info), g_file_info_get_content_type (file_info),
-	                                                         &error);
+	                                                         NULL, &error);
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_UPLOAD_STREAM (upload_stream));