GDataDocumentsDocument

GDataDocumentsDocument — GData documents document object

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── GDataParsable
        ╰── GDataEntry
            ╰── GDataDocumentsEntry
                ╰── GDataDocumentsDocument
                    ├── GDataDocumentsDrawing
                    ├── GDataDocumentsPdf
                    ├── GDataDocumentsPresentation
                    ├── GDataDocumentsSpreadsheet
                    ╰── GDataDocumentsText

Implemented Interfaces

GDataDocumentsDocument implements GDataAccessHandler.

Includes

#include <gdata/services/documents/gdata-documents-document.h>

Description

GDataDocumentsDocument is a subclass of GDataDocumentsEntry to represent an arbitrary Google Documents 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 “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 Documents' GData API, see the

online documentation.

Example 33. Downloading a Document

1

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 online documentation on sharing documents.

Example 34. Retrieving the Access Control List for a Document

1

Functions

gdata_documents_document_new ()

GDataDocumentsDocument *
gdata_documents_document_new (const gchar *id);

Creates a new GDataDocumentsDocument with the given entry ID (“id”).

Parameters

id

the entry's ID (not the document ID), or NULL.

[allow-none]

Returns

a new GDataDocumentsDocument, or NULL; unref with g_object_unref().

[transfer full]

Since: 0.13.0


gdata_documents_document_download ()

GDataDownloadStream *
gdata_documents_document_download (GDataDocumentsDocument *self,
                                   GDataDocumentsService *service,
                                   const gchar *export_format,
                                   GCancellable *cancellable,
                                   GError **error);

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

GData protocol specification 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 “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.

Parameters

self

a GDataDocumentsDocument

 

service

a GDataDocumentsService

 

export_format

the format in which the document should be exported

 

cancellable

a GCancellable for the entire download stream, or NULL.

[allow-none]

error

a GError, or NULL

 

Returns

a GDataDownloadStream to download the document with, or NULL; unref with g_object_unref().

[transfer full]

Since: 0.8.0


gdata_documents_document_get_download_uri ()

gchar *
gdata_documents_document_get_download_uri
                               (GDataDocumentsDocument *self,
                                const gchar *export_format);

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.

Parameters

self

a GDataDocumentsDocument

 

export_format

the format in which the document should be exported when downloaded

 

Returns

the download URI; free with g_free()

Since: 0.7.0


gdata_documents_document_get_thumbnail_uri ()

const gchar *
gdata_documents_document_get_thumbnail_uri
                               (GDataDocumentsDocument *self);

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 35. Downloading a Document Thumbnail

1

Parameters

Returns

the URI of the document's thumbnail, or NULL.

[allow-none]

Since: 0.13.1

Types and Values

GDataDocumentsDocument

typedef struct _GDataDocumentsDocument GDataDocumentsDocument;

All the fields in the GDataDocumentsDocument structure are private and should never be accessed directly.

Since: 0.7.0


GDataDocumentsDocumentClass

typedef struct {
} GDataDocumentsDocumentClass;

All the fields in the GDataDocumentsDocumentClass structure are private and should never be accessed directly.

Since: 0.7.0