GNOME.org
 

[libgdata] documents: Rename add to/remove from folder methods

commit de5b50417d7e128bd7eed12ed81dbf0247c28ee0
Author: Philip Withnall <philip tecnocode co uk>
Date:   Thu Dec 9 15:40:02 2010 +0000

    documents: Rename add to/remove from folder methods
    
    To better indicate that the following methods can be used on documents and
    folders, and because â??moveâ?? was a misnomer (the document isn't moved; it's
    merely added to a new folder without being removed from its old ones), two
    methods in GDataDocumentsService have been renamed.
    
    The following API changes have been made:
     â?¢ gdata_documents_service_move_document_to_folder() has been renamed to
       gdata_documents_service_add_entry_to_folder()
     â?¢ gdata_documents_service_remove_document_from_folder() has been renamed to
       gdata_documents_service_remove_entry_from_folder()

 docs/reference/gdata-sections.txt                  |    4 +-
 gdata/gdata.symbols                                |    4 +-
 gdata/services/documents/gdata-documents-service.c |   84 ++++++++++----------
 gdata/services/documents/gdata-documents-service.h |   13 ++--
 gdata/tests/documents.c                            |   12 ++--
 5 files changed, 60 insertions(+), 57 deletions(-)
---
diff --git a/docs/reference/gdata-sections.txt b/docs/reference/gdata-sections.txt
index c80de81..515ffdb 100644
--- a/docs/reference/gdata-sections.txt
+++ b/docs/reference/gdata-sections.txt
@@ -1717,8 +1717,8 @@ gdata_documents_service_query_documents_async
 gdata_documents_service_upload_document
 gdata_documents_service_update_document
 gdata_documents_service_finish_upload
-gdata_documents_service_move_document_to_folder
-gdata_documents_service_remove_document_from_folder
+gdata_documents_service_add_entry_to_folder
+gdata_documents_service_remove_entry_from_folder
 gdata_documents_service_get_upload_uri
 <SUBSECTION Standard>
 gdata_documents_service_get_type
diff --git a/gdata/gdata.symbols b/gdata/gdata.symbols
index 018352d..30367aa 100644
--- a/gdata/gdata.symbols
+++ b/gdata/gdata.symbols
@@ -630,9 +630,7 @@ gdata_documents_service_query_documents
 gdata_documents_service_query_documents_async
 gdata_documents_service_upload_document
 gdata_documents_service_update_document
-gdata_documents_service_move_document_to_folder
 gdata_documents_service_get_upload_uri
-gdata_documents_service_remove_document_from_folder
 gdata_documents_feed_get_type
 gdata_documents_entry_get_type
 gdata_documents_entry_get_path
@@ -852,3 +850,5 @@ gdata_youtube_service_upload_video_finish
 gdata_picasaweb_service_insert_album_async
 gdata_picasaweb_service_query_files_async
 gdata_documents_service_finish_upload
+gdata_documents_service_add_entry_to_folder
+gdata_documents_service_remove_entry_from_folder
diff --git a/gdata/services/documents/gdata-documents-service.c b/gdata/services/documents/gdata-documents-service.c
index 55ab24c..a513b66 100644
--- a/gdata/services/documents/gdata-documents-service.c
+++ b/gdata/services/documents/gdata-documents-service.c
@@ -476,41 +476,42 @@ gdata_documents_service_finish_upload (GDataDocumentsService *self, GDataUploadS
 }
 
 /**
- * gdata_documents_service_move_document_to_folder:
+ * gdata_documents_service_add_entry_to_folder:
  * @self: an authenticated #GDataDocumentsService
- * @document: the #GDataDocumentsEntry to move
- * @folder: the #GDataDocumentsFolder to move @document into
+ * @entry: the #GDataDocumentsEntry to move
+ * @folder: the #GDataDocumentsFolder to move @entry into
  * @cancellable: optional #GCancellable object, or %NULL
  * @error: a #GError, or %NULL
  *
- * Move the given @document to the specified @folder. If the document is already in another folder, it will be added to
- * the new folder, but will also remain in any previous folders.
+ * Add the given @entry to the specified @folder, and return an updated #GDataDocumentsEntry for @entry. If the @entry is already in another folder, it
+ * will be added to the new folder, but will also remain  in its other folders. Note that @entry can be either a #GDataDocumentsDocument or a
+ * #GDataDocumentsFolder.
  *
- * Errors from #GDataServiceError can be returned for other exceptional conditions, as determined by the server.
+ * Errors from #GDataServiceError can be returned for exceptional conditions, as determined by the server.
  *
  * Return value: (transfer full): an updated #GDataDocumentsEntry, or %NULL; unref with g_object_unref()
  *
- * Since: 0.4.0
+ * Since: 0.8.0
  **/
 GDataDocumentsEntry *
-gdata_documents_service_move_document_to_folder (GDataDocumentsService *self, GDataDocumentsEntry *document, GDataDocumentsFolder *folder,
-                                                 GCancellable *cancellable, GError **error)
+gdata_documents_service_add_entry_to_folder (GDataDocumentsService *self, GDataDocumentsEntry *entry, GDataDocumentsFolder *folder,
+                                             GCancellable *cancellable, GError **error)
 {
-	GDataDocumentsEntry *new_document;
+	GDataDocumentsEntry *new_entry;
 	gchar *uri, *upload_data;
 	const gchar *folder_id;
 	SoupMessage *message;
 	guint status;
 
 	g_return_val_if_fail (GDATA_IS_DOCUMENTS_SERVICE (self), NULL);
-	g_return_val_if_fail (GDATA_IS_DOCUMENTS_ENTRY (document), NULL);
+	g_return_val_if_fail (GDATA_IS_DOCUMENTS_ENTRY (entry), NULL);
 	g_return_val_if_fail (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) {
 		g_set_error_literal (error, GDATA_SERVICE_ERROR, GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED,
-		                     _("You must be authenticated to move documents."));
+		                     _("You must be authenticated to move documents and folders."));
 		return NULL;
 	}
 
@@ -522,7 +523,7 @@ gdata_documents_service_move_document_to_folder (GDataDocumentsService *self, GD
 	g_free (uri);
 
 	/* Append the data */
-	upload_data = gdata_parsable_get_xml (GDATA_PARSABLE (document));
+	upload_data = gdata_parsable_get_xml (GDATA_PARSABLE (entry));
 	soup_message_set_request (message, "application/atom+xml", SOUP_MEMORY_TAKE, upload_data, strlen (upload_data));
 
 	/* Send the message */
@@ -542,75 +543,76 @@ gdata_documents_service_move_document_to_folder (GDataDocumentsService *self, GD
 		return NULL;
 	}
 
-	/* Parse the XML; and update the document */
+	/* Parse the XML; and update the entry */
 	g_assert (message->response_body->data != NULL);
-	new_document = GDATA_DOCUMENTS_ENTRY (gdata_parsable_new_from_xml (G_OBJECT_TYPE (document), message->response_body->data,
-	                                                                   message->response_body->length, error));
+	new_entry = GDATA_DOCUMENTS_ENTRY (gdata_parsable_new_from_xml (G_OBJECT_TYPE (entry), message->response_body->data,
+	                                                                message->response_body->length, error));
 	g_object_unref (message);
 
-	return new_document;
+	return new_entry;
 }
 
 /**
- * gdata_documents_service_remove_document_from_folder:
+ * gdata_documents_service_remove_entry_from_folder:
  * @self: a #GDataDocumentsService
- * @document: the #GDataDocumentsEntry to remove
- * @folder: the #GDataDocumentsFolder from which we should remove @document
+ * @entry: the #GDataDocumentsEntry to remove
+ * @folder: the #GDataDocumentsFolder from which we should remove @entry
  * @cancellable: optional #GCancellable object, or %NULL
  * @error: a #GError, or %NULL
  *
- * Remove the #GDataDocumentsEntry @document from the GDataDocumentsFolder @folder, and updates the document entry @document.
+ * Remove the given @entry from @folder, and return an updated #GDataDocumentsEntry for @entry. @entry will remain a member of any other folders it's
+ * currently in. Note that @entry can be either a #GDataDocumentsDocument or a #GDataDocumentsFolder.
  *
- * Errors from #GDataServiceError can be returned for other exceptional conditions, as determined by the server.
+ * Errors from #GDataServiceError can be returned for exceptional conditions, as determined by the server.
  *
  * Return value: (transfer full): an updated #GDataDocumentsEntry, or %NULL; unref with g_object_unref()
  *
- * Since: 0.4.0
+ * Since: 0.8.0
  **/
 GDataDocumentsEntry *
-gdata_documents_service_remove_document_from_folder (GDataDocumentsService *self, GDataDocumentsEntry *document, GDataDocumentsFolder *folder,
-                                                     GCancellable *cancellable, GError **error)
+gdata_documents_service_remove_entry_from_folder (GDataDocumentsService *self, GDataDocumentsEntry *entry, GDataDocumentsFolder *folder,
+                                                  GCancellable *cancellable, GError **error)
 {
-	const gchar *folder_id, *document_id;
+	const gchar *folder_id, *entry_id;
 	SoupMessage *message;
 	guint status;
 	gchar *uri;
 
 	g_return_val_if_fail (GDATA_IS_DOCUMENTS_SERVICE (self), NULL);
-	g_return_val_if_fail (GDATA_IS_DOCUMENTS_ENTRY (document), NULL);
+	g_return_val_if_fail (GDATA_IS_DOCUMENTS_ENTRY (entry), NULL);
 	g_return_val_if_fail (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) {
 		g_set_error_literal (error, GDATA_SERVICE_ERROR, GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED,
-		                     _("You must be authenticated to move documents."));
+		                     _("You must be authenticated to move documents and folders."));
 		return NULL;
 	}
 
 	/* Get the document ID */
 	folder_id = gdata_documents_entry_get_document_id (GDATA_DOCUMENTS_ENTRY (folder));
-	document_id = gdata_documents_entry_get_document_id (GDATA_DOCUMENTS_ENTRY (document));
+	entry_id = gdata_documents_entry_get_document_id (entry);
 	g_assert (folder_id != NULL);
-	g_assert (document_id != NULL);
+	g_assert (entry_id != NULL);
 
-	if (GDATA_IS_DOCUMENTS_PRESENTATION (document)) {
+	if (GDATA_IS_DOCUMENTS_PRESENTATION (entry)) {
 		uri = _gdata_service_build_uri (FALSE, "http://docs.google.com/feeds/folders/private/full/folder%%3A%s/presentation%%3A%s";,
-		                                folder_id, document_id);
-	} else if (GDATA_IS_DOCUMENTS_SPREADSHEET (document)) {
+		                                folder_id, entry_id);
+	} else if (GDATA_IS_DOCUMENTS_SPREADSHEET (entry)) {
 		uri = _gdata_service_build_uri (FALSE, "http://docs.google.com/feeds/folders/private/full/folder%%3A%s/spreadsheet%%3A%s";,
-		                                folder_id, document_id);
-	} else if (GDATA_IS_DOCUMENTS_TEXT (document)) {
+		                                folder_id, entry_id);
+	} else if (GDATA_IS_DOCUMENTS_TEXT (entry)) {
 		uri = _gdata_service_build_uri (FALSE, "http://docs.google.com/feeds/folders/private/full/folder%%3A%s/document%%3A%s";,
-		                                folder_id, document_id);
-	} else if (GDATA_IS_DOCUMENTS_FOLDER (document)) {
+		                                folder_id, entry_id);
+	} else if (GDATA_IS_DOCUMENTS_FOLDER (entry)) {
 		uri = _gdata_service_build_uri (FALSE, "http://docs.google.com/feeds/folders/private/full/folder%%3A%s/folder%%3A%s";,
-		                                folder_id, document_id);
+		                                folder_id, entry_id);
 	} else {
 		g_assert_not_reached ();
 	}
 
-	message = _gdata_service_build_message (GDATA_SERVICE (self), SOUP_METHOD_DELETE, uri, gdata_entry_get_etag (GDATA_ENTRY (document)), TRUE);
+	message = _gdata_service_build_message (GDATA_SERVICE (self), SOUP_METHOD_DELETE, uri, gdata_entry_get_etag (GDATA_ENTRY (entry)), TRUE);
 	g_free (uri);
 
 	/* Send the message */
@@ -634,8 +636,8 @@ gdata_documents_service_remove_document_from_folder (GDataDocumentsService *self
 
 	/* Google's servers don't return an updated copy of the entry, so we have to query for it again.
 	 * See: http://code.google.com/p/gdata-issues/issues/detail?id=1380 */
-	return GDATA_DOCUMENTS_ENTRY (gdata_service_query_single_entry (GDATA_SERVICE (self), gdata_entry_get_id (GDATA_ENTRY (document)), NULL,
-	                                                                G_OBJECT_TYPE (document), cancellable, error));
+	return GDATA_DOCUMENTS_ENTRY (gdata_service_query_single_entry (GDATA_SERVICE (self), gdata_entry_get_id (GDATA_ENTRY (entry)), NULL,
+	                                                                G_OBJECT_TYPE (entry), cancellable, error));
 }
 
 /**
diff --git a/gdata/services/documents/gdata-documents-service.h b/gdata/services/documents/gdata-documents-service.h
index 0befc1e..ba25c6f 100644
--- a/gdata/services/documents/gdata-documents-service.h
+++ b/gdata/services/documents/gdata-documents-service.h
@@ -99,12 +99,13 @@ GDataUploadStream *gdata_documents_service_update_document (GDataDocumentsServic
 GDataDocumentsDocument *gdata_documents_service_finish_upload (GDataDocumentsService *self, GDataUploadStream *upload_stream,
                                                                GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
 
-GDataDocumentsEntry *gdata_documents_service_move_document_to_folder (GDataDocumentsService *self, GDataDocumentsEntry *document,
-                                                                      GDataDocumentsFolder *folder, GCancellable *cancellable,
-                                                                      GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
-GDataDocumentsEntry *gdata_documents_service_remove_document_from_folder (GDataDocumentsService *self, GDataDocumentsEntry *document,
-                                                                          GDataDocumentsFolder *folder, GCancellable *cancellable,
-                                                                          GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
+GDataDocumentsEntry *gdata_documents_service_add_entry_to_folder (GDataDocumentsService *self, GDataDocumentsEntry *entry,
+                                                                  GDataDocumentsFolder *folder, GCancellable *cancellable,
+                                                                  GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
+GDataDocumentsEntry *gdata_documents_service_remove_entry_from_folder (GDataDocumentsService *self, GDataDocumentsEntry *entry,
+                                                                       GDataDocumentsFolder *folder, GCancellable *cancellable,
+                                                                       GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
+
 gchar *gdata_documents_service_get_upload_uri (GDataDocumentsFolder *folder) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC;
 
 G_END_DECLS
diff --git a/gdata/tests/documents.c b/gdata/tests/documents.c
index b7b46a8..76abded 100644
--- a/gdata/tests/documents.c
+++ b/gdata/tests/documents.c
@@ -388,9 +388,9 @@ test_add_remove_file_from_folder (gconstpointer service)
 	g_assert (check_document_is_in_folder (new_document, new_folder) == TRUE);
 
 	/* Remove the document from the folder */
-	new_document2 = GDATA_DOCUMENTS_DOCUMENT (gdata_documents_service_remove_document_from_folder (GDATA_DOCUMENTS_SERVICE (service),
-	                                                                                               GDATA_DOCUMENTS_ENTRY (new_document),
-	                                                                                               new_folder, NULL, &error));
+	new_document2 = GDATA_DOCUMENTS_DOCUMENT (gdata_documents_service_remove_entry_from_folder (GDATA_DOCUMENTS_SERVICE (service),
+	                                                                                            GDATA_DOCUMENTS_ENTRY (new_document),
+	                                                                                            new_folder, NULL, &error));
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_DOCUMENTS_PRESENTATION (new_document2));
 
@@ -476,9 +476,9 @@ test_add_file_folder_and_move (gconstpointer service)
 	g_assert (check_document_is_in_folder (new_document, new_folder) == FALSE);
 
 	/* Move the document from the folder */
-	new_document2 = GDATA_DOCUMENTS_DOCUMENT (gdata_documents_service_move_document_to_folder (GDATA_DOCUMENTS_SERVICE (service),
-	                                                                                           GDATA_DOCUMENTS_ENTRY (new_document),
-	                                                                                           new_folder, NULL, &error));
+	new_document2 = GDATA_DOCUMENTS_DOCUMENT (gdata_documents_service_add_entry_to_folder (GDATA_DOCUMENTS_SERVICE (service),
+	                                                                                       GDATA_DOCUMENTS_ENTRY (new_document),
+	                                                                                       new_folder, NULL, &error));
 	g_assert_no_error (error);
 	g_assert (GDATA_IS_DOCUMENTS_TEXT (new_document2));
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]