/* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
/*
* GData Client
* Copyright (C) Philip Withnall 2010 <philip@tecnocode.co.uk>
* Copyright (C) Red Hat, Inc. 2015
*
* GData Client is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* GData Client is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with GData Client. If not, see <http://www.gnu.org/licenses/>.
*/
/**
* SECTION:gdata-documents-document
* @short_description: GData documents document object
* @stability: Stable
* @include: gdata/services/documents/gdata-documents-document.h
*
* #GDataDocumentsDocument is a subclass of #GDataDocumentsEntry to represent an arbitrary Google Drive document (i.e. an arbitrary file which
* isn't a Google Documents presentation, text document, PDF, drawing or spreadsheet). It is subclassed by #GDataDocumentsPresentation, #GDataDocumentsText,
* #GDataDocumentsPdf, #GDataDocumentsDrawing and #GDataDocumentsSpreadsheet, which represent those specific types of Google Document, respectively.
*
* #GDataDocumentsDocument used to be abstract, but was made instantiable in version 0.13.0 to allow for arbitrary file uploads. This can be achieved
* by setting #GDataDocumentsUploadQuery:convert to %FALSE when making an upload using gdata_documents_service_upload_document_resumable(). See the
* documentation for #GDataDocumentsUploadQuery for an example.
*
* It should be noted that #GDataDocumentsDocument should only be used to represent arbitrary files; its subclasses should be used any time a standard
* Google Document (spreadsheet, text document, presentation, etc.) is to be represented.
*
* For more details of Google Drive’s GData API, see the
* <ulink type="http" url="https://developers.google.com/drive/v2/web/about-sdk">online documentation</ulink>.
*
* <example>
* <title>Downloading a Document</title>
* <programlisting>
* GDataDocumentsService *service;
* GDataDocumentsDocument *document;
* GFile *destination_file;
* const gchar *download_format;
* GDataDownloadStream *download_stream;
* GFileOutputStream *output_stream;
* GError *error = NULL;
*
* /<!-- -->* Create a service and retrieve the document to download and the file and format to save the download in *<!-- -->/
* service = create_youtube_service ();
* document = get_document_to_download (service);
* destination_file = query_user_for_destination_file (document);
* download_format = query_user_for_download_format (document);
*
* /<!-- -->* Create the download stream *<!-- -->/
* download_stream = gdata_documents_document_download (document, service, download_format, NULL, &error);
*
* g_object_unref (document);
* g_object_unref (service);
*
* if (error != NULL) {
* g_error ("Error creating download stream: %s", error->message);
* g_error_free (error);
* g_object_unref (destination_file);
* return;
* }
*
* /<!-- -->* Create the file output stream *<!-- -->/
* output_stream = g_file_replace (destination_file, NULL, FALSE, G_FILE_CREATE_REPLACE_DESTINATION, NULL, &error);
*
* g_object_unref (destination_file);
*
* if (error != NULL) {
* g_error ("Error creating destination file: %s", error->message);
* g_error_free (error);
* g_object_unref (download_stream);
* return;
* }
*
* /<!-- -->* Download the document. This should almost always be done asynchronously. *<!-- -->/
* g_output_stream_splice (G_OUTPUT_STREAM (output_stream), G_INPUT_STREAM (download_stream),
* G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE | G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET, NULL, &error);
*
* g_object_unref (output_stream);
* g_object_unref (download_stream);
*
* if (error != NULL) {
* g_error ("Error downloading document: %s", error->message);
* g_error_free (error);
* return;
* }
* </programlisting>
* </example>
*
* Each document accessible through the service has an access control list (ACL) which defines the level of access to the document to each user, and
* which users the document is shared with. For more information about ACLs for documents, see the <ulink type="http"
* url="https://developers.google.com/google-apps/documents-list/#managing_sharing_permissions_of_resources_via_access_control_lists_acls">online
* documentation on sharing documents</ulink>.
*
* <example>
* <title>Retrieving the Access Control List for a Document</title>
* <programlisting>
* GDataDocumentsService *service;
* GDataDocumentsDocument *document;
* GDataFeed *acl_feed;
* GDataAccessRule *rule, *new_rule;
* GDataLink *acl_link;
* GList *i;
* GError *error = NULL;
*
* /<!-- -->* Create a service and retrieve a document to work on *<!-- -->/
* service = create_documents_service ();
* document = get_document (service);
*
* /<!-- -->* Query the service for the ACL for the given document *<!-- -->/
* acl_feed = gdata_access_handler_get_rules (GDATA_ACCESS_HANDLER (document), GDATA_SERVICE (service), NULL, NULL, NULL, &error);
*
* if (error != NULL) {
* g_error ("Error getting ACL feed for document: %s", error->message);
* g_error_free (error);
* g_object_unref (document);
* g_object_unref (service);
* return;
* }
*
* /<!-- -->* Iterate through the ACL *<!-- -->/
* for (i = gdata_feed_get_entries (acl_feed); i != NULL; i = i->next) {
* const gchar *scope_value;
*
* rule = GDATA_ACCESS_RULE (i->data);
*
* /<!-- -->* Do something with the access rule here. As an example, we update the rule applying to test@gmail.com and delete all
* * the other rules. We then insert another rule for example@gmail.com below. *<!-- -->/
* gdata_access_rule_get_scope (rule, NULL, &scope_value);
* if (scope_value != NULL && strcmp (scope_value, "test@gmail.com") == 0) {
* GDataAccessRule *updated_rule;
*
* /<!-- -->* Update the rule to make test@gmail.com a writer (full read/write access to the document, but they can't change
* * the ACL or delete the document). *<!-- -->/
* gdata_access_rule_set_role (rule, GDATA_DOCUMENTS_ACCESS_ROLE_WRITER);
* updated_rule = GDATA_ACCESS_RULE (gdata_service_update_entry (GDATA_SERVICE (service), GDATA_ENTRY (rule), NULL, &error));
*
* if (error != NULL) {
* g_error ("Error updating access rule for %s: %s", scope_value, error->message);
* g_error_free (error);
* g_object_unref (acl_feed);
* g_object_unref (document);
* g_object_unref (service);
* return;
* }
*
* g_object_unref (updated_rule);
* } else {
* /<!-- -->* Delete any rule which doesn't apply to test@gmail.com *<!-- -->/
* gdata_service_delete_entry (GDATA_SERVICE (service), GDATA_ENTRY (rule), NULL, &error);
*
* if (error != NULL) {
* g_error ("Error deleting access rule for %s: %s", scope_value, error->message);
* g_error_free (error);
* g_object_unref (acl_feed);
* g_object_unref (document);
* g_object_unref (service);
* return;
* }
* }
* }
*
* g_object_unref (acl_feed);
*
* /<!-- -->* Create and insert a new access rule for example@gmail.com which allows them read-only access to the document. *<!-- -->/
* rule = gdata_access_rule_new (NULL);
* gdata_access_rule_set_role (rule, GDATA_DOCUMENTS_ACCESS_ROLE_READER);
* gdata_access_rule_set_scope (rule, GDATA_ACCESS_SCOPE_USER, "example@gmail.com");
*
* acl_link = gdata_entry_look_up_link (GDATA_ENTRY (document), GDATA_LINK_ACCESS_CONTROL_LIST);
* new_rule = GDATA_ACCESS_RULE (gdata_service_insert_entry (GDATA_SERVICE (service), gdata_link_get_uri (acl_link), GDATA_ENTRY (rule),
* NULL, &error));
*
* g_object_unref (rule);
* g_object_unref (document);
* g_object_unref (service);
*
* if (error != NULL) {
* g_error ("Error inserting access rule: %s", error->message);
* g_error_free (error);
* return;
* }
*
* g_object_unref (acl_link);
* </programlisting>
* </example>
*
* Since: 0.7.0
*/
#include <config.h>
#include <glib.h>
#include <glib/gi18n-lib.h>
#include "gdata-documents-document.h"
#include "gdata-documents-drawing.h"
#include "gdata-documents-entry.h"
#include "gdata-documents-presentation.h"
#include "gdata-documents-spreadsheet.h"
#include "gdata-documents-text.h"
#include "gdata-documents-utils.h"
#include "gdata-download-stream.h"
#include "gdata-private.h"
#include "gdata-service.h"
static void gdata_documents_document_finalize (GObject *object);
static gboolean parse_json (GDataParsable *parsable, JsonReader *reader, gpointer user_data, GError **error);
struct _GDataDocumentsDocumentPrivate {
GHashTable *export_links; /* owned string → owned string */
};
G_DEFINE_TYPE (GDataDocumentsDocument, gdata_documents_document, GDATA_TYPE_DOCUMENTS_ENTRY)
static void
gdata_documents_document_class_init (GDataDocumentsDocumentClass *klass)
{
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
GDataParsableClass *parsable_class = GDATA_PARSABLE_CLASS (klass);
GDataEntryClass *entry_class = GDATA_ENTRY_CLASS (klass);
g_type_class_add_private (klass, sizeof (GDataDocumentsDocumentPrivate));
gobject_class->finalize = gdata_documents_document_finalize;
parsable_class->parse_json = parse_json;
entry_class->kind_term = "http://schemas.google.com/docs/2007#file";
}
static void
gdata_documents_document_init (GDataDocumentsDocument *self)
{
self->priv = G_TYPE_INSTANCE_GET_PRIVATE (self, GDATA_TYPE_DOCUMENTS_DOCUMENT, GDataDocumentsDocumentPrivate);
self->priv->export_links = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, g_free);
}
static void
gdata_documents_document_finalize (GObject *object)
{
GDataDocumentsDocumentPrivate *priv = GDATA_DOCUMENTS_DOCUMENT (object)->priv;
g_hash_table_unref (priv->export_links);
G_OBJECT_CLASS (gdata_documents_document_parent_class)->finalize (object);
}
static gboolean
parse_json (GDataParsable *parsable, JsonReader *reader, gpointer user_data, GError **error)
{
GDataDocumentsDocumentPrivate *priv = GDATA_DOCUMENTS_DOCUMENT (parsable)->priv;
gboolean success;
gchar *content_uri = NULL;
gchar *thumbnail_uri = NULL;
/* JSON format: https://developers.google.com/drive/v2/reference/files */
if (gdata_parser_string_from_json_member (reader, "downloadUrl", P_DEFAULT, &content_uri, &success, error) == TRUE) {
if (success && content_uri != NULL && content_uri[0] != '\0')
gdata_entry_set_content_uri (GDATA_ENTRY (parsable), content_uri);
g_free (content_uri);
return success;
} else if (gdata_parser_string_from_json_member (reader, "thumbnailLink", P_DEFAULT, &thumbnail_uri, &success, error) == TRUE) {
if (success && thumbnail_uri != NULL && thumbnail_uri[0] != '\0') {
GDataLink *_link;
_link = gdata_link_new (thumbnail_uri, "http://schemas.google.com/docs/2007/thumbnail");
gdata_entry_add_link (GDATA_ENTRY (parsable), _link);
g_object_unref (_link);
}
g_free (thumbnail_uri);
return success;
} else if (g_strcmp0 (json_reader_get_member_name (reader), "exportLinks") == 0) {
guint i, members;
if (json_reader_is_object (reader) == FALSE) {
g_set_error (error, GDATA_PARSER_ERROR, GDATA_PARSER_ERROR_PARSING_STRING,
/* Translators: the parameter is an error message */
_("Error parsing JSON: %s"),
"JSON node ‘exportLinks’ is not an object.");
return FALSE;
}
for (i = 0, members = (guint) json_reader_count_members (reader); i < members; i++) {
const gchar *format;
gchar *uri = NULL;
json_reader_read_element (reader, i);
format = json_reader_get_member_name (reader);
g_assert (gdata_parser_string_from_json_member (reader, format, P_REQUIRED | P_NON_EMPTY, &uri, &success, NULL));
if (success) {
g_hash_table_insert (priv->export_links, g_strdup (format), uri);
uri = NULL;
}
json_reader_end_element (reader);
g_free (uri);
}
return TRUE;
}
return GDATA_PARSABLE_CLASS (gdata_documents_document_parent_class)->parse_json (parsable, reader, user_data, error);
}
/**
* gdata_documents_document_new:
* @id: (allow-none): the entry's ID (not the document ID), or %NULL
*
* Creates a new #GDataDocumentsDocument with the given entry ID (#GDataEntry:id).
*
* Return value: (transfer full): a new #GDataDocumentsDocument, or %NULL; unref with g_object_unref()
*
* Since: 0.13.0
*/
GDataDocumentsDocument *
gdata_documents_document_new (const gchar *id)
{
return GDATA_DOCUMENTS_DOCUMENT (g_object_new (GDATA_TYPE_DOCUMENTS_DOCUMENT, "id", id, NULL));
}
/**
* gdata_documents_document_download:
* @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
* is set in @error.
*
* @export_format should be the file extension of the desired output format for the document, from the list accepted by Google Documents. For example:
* %GDATA_DOCUMENTS_PRESENTATION_PDF, %GDATA_DOCUMENTS_SPREADSHEET_ODS or %GDATA_DOCUMENTS_TEXT_ODT.
*
* If @self is a #GDataDocumentsSpreadsheet, only the first grid, or sheet, in the spreadsheet will be downloaded for some export formats. To download
* a specific a specific grid, use gdata_documents_spreadsheet_get_download_uri() with #GDataDownloadStream to download the grid manually. See the
* <ulink type="http" url="https://developers.google.com/google-apps/documents-list/#downloading_spreadsheets">GData protocol
* specification</ulink> for more information.
*
* To get the content type of the downloaded file, gdata_download_stream_get_content_type() can be called on the returned #GDataDownloadStream.
* 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 the given @export_format is unrecognised or not supported for this document, %GDATA_SERVICE_ERROR_NOT_FOUND will be returned.
*
* 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.
*
* Return value: (transfer full): a #GDataDownloadStream to download the document with, or %NULL; unref with g_object_unref()
*
* Since: 0.8.0
*/
GDataDownloadStream *
gdata_documents_document_download (GDataDocumentsDocument *self, GDataDocumentsService *service, const gchar *export_format, GCancellable *cancellable,
GError **error)
{
gchar *download_uri;
GDataAuthorizationDomain *domain;
GDataDownloadStream *download_stream;
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);
/* If we're downloading a spreadsheet we have to use a different authorization domain. */
if (GDATA_IS_DOCUMENTS_SPREADSHEET (self)) {
domain = gdata_documents_service_get_spreadsheet_authorization_domain ();
} else {
domain = gdata_documents_service_get_primary_authorization_domain ();
}
/* Ensure we're authenticated first */
if (gdata_authorizer_is_authorized_for_domain (gdata_service_get_authorizer (GDATA_SERVICE (service)), domain) == FALSE) {
g_set_error_literal (error, GDATA_SERVICE_ERROR, GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED,
_("You must be authenticated to download documents."));
return NULL;
}
/* Get the download URI and create a stream for it */
download_uri = gdata_documents_document_get_download_uri (self, export_format);
if (download_uri == NULL) {
g_set_error (error, GDATA_SERVICE_ERROR, GDATA_SERVICE_ERROR_NOT_FOUND,
_("Unknown or unsupported document export format ‘%s’."), export_format);
return NULL;
}
download_stream = GDATA_DOWNLOAD_STREAM (gdata_download_stream_new (GDATA_SERVICE (service), domain, download_uri, cancellable));
g_free (download_uri);
return download_stream;
}
/**
* gdata_documents_document_get_download_uri:
* @self: a #GDataDocumentsDocument
* @export_format: the format in which the document should be exported when downloaded
*
* Builds and returns the download URI for the given #GDataDocumentsDocument in the desired format. Note that directly downloading the document using
* this URI isn't possible, as authentication is required. You should instead use gdata_download_stream_new() with the URI, and use the resulting
* #GInputStream.
*
* @export_format should be the file extension of the desired output format for the document, from the list accepted by Google Documents. For example:
* %GDATA_DOCUMENTS_PRESENTATION_PDF, %GDATA_DOCUMENTS_SPREADSHEET_ODS or %GDATA_DOCUMENTS_TEXT_ODT.
*
* If the @export_format is not recognised or not supported for this document, %NULL is returned.
*
* Return value: (nullable): the download URI, or %NULL; free with g_free()
*
* Since: 0.7.0
*/
gchar *
gdata_documents_document_get_download_uri (GDataDocumentsDocument *self, const gchar *export_format)
{
const gchar *format;
const gchar *mime_type;
g_return_val_if_fail (GDATA_IS_DOCUMENTS_DOCUMENT (self), NULL);
g_return_val_if_fail (export_format != NULL && *export_format != '\0', NULL);
if (g_strcmp0 (export_format, "html") == 0)
format = "text/html";
else if (g_strcmp0 (export_format, "jpeg") == 0)
format = "image/jpeg";
else if (g_strcmp0 (export_format, "pdf") == 0)
format = "application/pdf";
else if (g_strcmp0 (export_format, "png") == 0)
format = "image/png";
else if (g_strcmp0 (export_format, "txt") == 0)
format = "text/plain";
else if (g_strcmp0 (export_format, GDATA_DOCUMENTS_DRAWING_SVG) == 0)
format = "image/svg+xml";
else if (g_strcmp0 (export_format, GDATA_DOCUMENTS_PRESENTATION_PPT) == 0)
format = "application/vnd.openxmlformats-officedocument.presentationml.presentation";
else if (g_strcmp0 (export_format, GDATA_DOCUMENTS_SPREADSHEET_CSV) == 0)
format = "text/csv";
else if (g_strcmp0 (export_format, GDATA_DOCUMENTS_SPREADSHEET_ODS) == 0)
format = "application/x-vnd.oasis.opendocument.spreadsheet";
else if (g_strcmp0 (export_format, GDATA_DOCUMENTS_SPREADSHEET_XLS) == 0)
format = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
else if (g_strcmp0 (export_format, GDATA_DOCUMENTS_TEXT_ODT) == 0)
format = "application/vnd.oasis.opendocument.text";
else if (g_strcmp0 (export_format, GDATA_DOCUMENTS_TEXT_RTF) == 0)
format = "application/rtf";
else
format = export_format;
/* We use the exportLinks JSON member to do the format conversion during download. Unfortunately, there
* won't be any hits if the export format matches the original MIME type. We resort to downloadUrl in
* those cases.
*/
mime_type = gdata_documents_utils_get_content_type (GDATA_DOCUMENTS_ENTRY (self));
if (g_content_type_equals (mime_type, format))
return g_strdup (gdata_entry_get_content_uri (GDATA_ENTRY (self)));
return g_strdup (g_hash_table_lookup (self->priv->export_links, format));
}
/**
* gdata_documents_document_get_thumbnail_uri:
* @self: a #GDataDocumentsDocument
*
* Gets the URI of the thumbnail for the #GDataDocumentsDocument. If no thumbnail exists for the document, %NULL will be returned.
*
* The thumbnail may then be downloaded using a #GDataDownloadStream.
*
* <example>
* <title>Downloading a Document Thumbnail</title>
* <programlisting>
* GDataDocumentsService *service;
* const gchar *thumbnail_uri;
* GCancellable *cancellable;
* GdkPixbuf *pixbuf;
* GError *error = NULL;
*
* service = get_my_documents_service ();
* thumbnail_uri = gdata_documents_document_get_thumbnail_uri (my_document);
* cancellable = g_cancellable_new ();
*
* /<!-- -->* Prepare a download stream *<!-- -->/
* download_stream = GDATA_DOWNLOAD_STREAM (gdata_download_stream_new (GDATA_SERVICE (service), NULL, thumbnail_uri, cancellable));
*
* /<!-- -->* Download into a new GdkPixbuf. This can be cancelled using 'cancellable'. *<!-- -->/
* pixbuf = gdk_pixbuf_new_from_stream (G_INPUT_STREAM (download_stream), NULL, &error);
*
* if (error != NULL) {
* /<!-- -->* Handle the error. *<!-- -->/
* g_error_free (error);
* }
*
* g_object_unref (download_stream);
* g_object_unref (cancellable);
*
* /<!-- -->* Do something with the GdkPixbuf. *<!-- -->/
*
* g_object_unref (pixbuf);
* </programlisting>
* </example>
*
* Return value: (allow-none): the URI of the document's thumbnail, or %NULL
*
* Since: 0.13.1
*/
const gchar *
gdata_documents_document_get_thumbnail_uri (GDataDocumentsDocument *self)
{
GDataLink *thumbnail_link;
g_return_val_if_fail (GDATA_IS_DOCUMENTS_DOCUMENT (self), NULL);
/* Get the thumbnail URI (if it exists). */
thumbnail_link = gdata_entry_look_up_link (GDATA_ENTRY (self), "http://schemas.google.com/docs/2007/thumbnail");
if (thumbnail_link == NULL) {
return NULL;
}
return gdata_link_get_uri (thumbnail_link);
}