GData.DocumentsService

g GData.Batchable GData.Batchable GData.DocumentsService GData.DocumentsService GData.Batchable->GData.DocumentsService GData.Service GData.Service GData.Service->GData.DocumentsService GObject.GInterface GObject.GInterface GObject.GInterface->GData.Batchable GObject.Object GObject.Object GObject.Object->GData.Service

Subclasses:

None

Methods

Inherited:

GData.Service (27), GObject.Object (37), GData.Batchable (1)

Structs:

GObject.ObjectClass (5)

class

get_primary_authorization_domain ()

class

get_spreadsheet_authorization_domain ()

class

get_upload_uri (folder)

class

new (authorizer)

add_entry_to_folder (entry, folder, cancellable)

add_entry_to_folder_async (entry, folder, cancellable, callback, *user_data)

add_entry_to_folder_finish (async_result)

copy_document (document, cancellable)

copy_document_async (document, cancellable, callback, *user_data)

copy_document_finish (async_result)

finish_upload (upload_stream)

get_metadata (cancellable)

get_metadata_async (cancellable, callback, *user_data)

get_metadata_finish (async_result)

query_documents (query, cancellable, progress_callback, *progress_user_data)

query_documents_async (query, cancellable, progress_callback, progress_user_data, callback, *user_data)

query_drives (query, cancellable, progress_callback, *progress_user_data)

query_drives_async (query, cancellable, progress_callback, progress_user_data, callback, *user_data)

remove_entry_from_folder (entry, folder, cancellable)

remove_entry_from_folder_async (entry, folder, cancellable, callback, *user_data)

remove_entry_from_folder_finish (async_result)

update_document (document, slug, content_type, cancellable)

update_document_resumable (document, slug, content_type, content_length, cancellable)

upload_document (document, slug, content_type, folder, cancellable)

upload_document_resumable (document, slug, content_type, content_length, query, cancellable)

Virtual Methods

Inherited:

GData.Service (2), GObject.Object (7)

Properties

Inherited:

GData.Service (5)

Signals

Inherited:

GObject.Object (1)

Fields

Inherited:

GObject.Object (1)

Name

Type

Access

Description

parent

GData.Service

r

Class Details

class GData.DocumentsService(**kwargs)
Bases:

GData.Service, GData.Batchable

Abstract:

No

Structure:

GData.DocumentsServiceClass

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

New in version 0.4.0.

classmethod get_primary_authorization_domain()
Returns:

the service’s authorization domain

Return type:

GData.AuthorizationDomain

The primary GData.AuthorizationDomain for interacting with Google Documents. This will not normally need to be used, as it’s used internally by the GData.DocumentsService methods. However, if using the plain GData.Service methods to implement custom queries or requests which libgdata does not support natively, then this domain may be needed to authorize the requests.

The domain never changes, and is interned so that pointer comparison can be used to differentiate it from other authorization domains.

New in version 0.9.0.

classmethod get_spreadsheet_authorization_domain()
Returns:

the service’s authorization domain

Return type:

GData.AuthorizationDomain

The GData.AuthorizationDomain for interacting with spreadsheet data. This will not normally need to be used, as it’s automatically used internally by the GData.DocumentsService methods. However, if using the plain GData.Service methods to implement custom queries or requests which libgdata does not support natively, then this domain may be needed to authorize the requests which pertain to the Google Spreadsheets Data API, such as requests to download or upload spreadsheet documents.

The domain never changes, and is interned so that pointer comparison can be used to differentiate it from other authorization domains.

New in version 0.9.0.

classmethod get_upload_uri(folder)
Parameters:

folder (GData.DocumentsFolder or None) – the GData.DocumentsFolder into which to upload the document, or None

Returns:

the URI permitting the upload of documents to folder, or None; free with GLib.free()

Return type:

str

Gets the upload URI for documents for the service.

If folder is None, the URI will be the one to upload documents to the “root” folder.

New in version 0.5.0.

classmethod new(authorizer)
Parameters:

authorizer (GData.Authorizer or None) – a GData.Authorizer to authorize the service’s requests, or None

Returns:

a new GData.DocumentsService, or None; unref with GObject.Object.unref()

Return type:

GData.DocumentsService

Creates a new GData.DocumentsService using the given GData.Authorizer. If authorizer is None, all requests are made as an unauthenticated user.

New in version 0.9.0.

add_entry_to_folder(entry, folder, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

an updated GData.DocumentsEntry, or None; unref with GObject.Object.unref()

Return type:

GData.DocumentsEntry

Add the given entry to the specified folder, and return an updated GData.DocumentsEntry for entry. If the entry is already in another folder, a copy will be added to the new folder. The copy and original will have different IDs. Note that entry can’t be a GData.DocumentsFolder that already exists on the server. It can be a new GData.DocumentsFolder, or a GData.DocumentsDocument that is either new or already present on the server.

Errors from GData.ServiceError can be returned for exceptional conditions, as determined by the server.

New in version 0.8.0.

add_entry_to_folder_async(entry, folder, cancellable, callback, *user_data)
Parameters:

Add the given entry to the specified folder. self, entry and folder are all reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see GData.DocumentsService.add_entry_to_folder(), which is the synchronous version of this function.

When the operation is finished, callback will be called. You can then call GData.DocumentsService.add_entry_to_folder_finish() to get the results of the operation.

New in version 0.8.0.

add_entry_to_folder_finish(async_result)
Parameters:

async_result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

an updated GData.DocumentsEntry, or None; unref with GObject.Object.unref()

Return type:

GData.DocumentsEntry

Finish an asynchronous operation to add a GData.DocumentsEntry to a folder started with GData.DocumentsService.add_entry_to_folder_async().

New in version 0.8.0.

copy_document(document, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

the duplicate GData.DocumentsDocument, or None; unref with GObject.Object.unref()

Return type:

GData.DocumentsDocument

Copy the given document, producing a duplicate document in the same folder and returning its GData.DocumentsDocument.

Errors from GData.ServiceError can be returned for exceptional conditions, as determined by the server.

New in version 0.13.1.

copy_document_async(document, cancellable, callback, *user_data)
Parameters:

Copy the given document, producing a duplicate document in the same folder and returning its GData.DocumentsDocument. self and document are both reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see GData.DocumentsService.copy_document(), which is the synchronous version of this function.

When the operation is finished, callback will be called. You can then call GData.DocumentsService.copy_document_finish() to get the results of the operation.

New in version 0.13.1.

copy_document_finish(async_result)
Parameters:

async_result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

the duplicate GData.DocumentsDocument, or None; unref with GObject.Object.unref()

Return type:

GData.DocumentsDocument

Finish an asynchronous operation to copy a GData.DocumentsDocument started with GData.DocumentsService.copy_document_async().

New in version 0.13.1.

finish_upload(upload_stream)
Parameters:

upload_stream (GData.UploadStream) – the GData.UploadStream from the operation

Raises:

GLib.Error

Returns:

the new or updated GData.DocumentsDocument, or None; unref with GObject.Object.unref()

Return type:

GData.DocumentsDocument

Finish off a document upload or update operation started by GData.DocumentsService.upload_document() or GData.DocumentsService.update_document(), parsing the result and returning the new or updated GData.DocumentsDocument.

If an error occurred during the upload or update operation, it will have been returned during the operation (e.g. by Gio.OutputStream.splice() or one of the other stream methods). In such a case, None will be returned but error will remain unset. error is only set in the case that the server indicates that the operation was successful, but an error is encountered in parsing the result sent by the server.

In the case that no GData.DocumentsDocument was passed (to GData.DocumentsService.upload_document() or GData.DocumentsService.update_document()) when starting the operation, GData.DocumentsServiceError.TYPE will be thrown in error if the content type of the uploaded data could not be mapped to a document type with which to interpret the response from the server.

New in version 0.8.0.

get_metadata(cancellable)
Parameters:

cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

the service’s metadata object; unref with GObject.Object.unref()

Return type:

GData.DocumentsMetadata

Gets a GData.DocumentsMetadata object containing metadata about the documents service itself, like how large the user quota is.

New in version 0.17.9.

get_metadata_async(cancellable, callback, *user_data)
Parameters:

Gets a GData.DocumentsMetadata object containing metadata about the documents service itself, like how large the user quota is.

For more details, see GData.DocumentsService.get_metadata(), which is the synchronous version of this function.

When the operation is finished, callback will be called. You can then call GData.DocumentsService.get_metadata_finish() to get the results of the operation.

New in version 0.17.9.

get_metadata_finish(async_result)
Parameters:

async_result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

the service’s metadata object; unref with GObject.Object.unref()

Return type:

GData.DocumentsMetadata

Finish an asynchronous operation to get a GData.DocumentsMetadata started with GData.DocumentsService.get_metadata_async().

New in version 0.17.9.

query_documents(query, cancellable, progress_callback, *progress_user_data)
Parameters:
Raises:

GLib.Error

Returns:

a GData.DocumentsFeed of query results; unref with GObject.Object.unref()

Return type:

GData.DocumentsFeed

Queries the service to return a list of documents matching the given query. Note that query has to be a GData.DocumentsQuery, rather than just a GData.Query, as it uses the folder ID specified in GData.DocumentsQuery :folder-id.

For more details, see GData.Service.query().

New in version 0.4.0.

query_documents_async(query, cancellable, progress_callback, progress_user_data, callback, *user_data)
Parameters:

Queries the service to return a list of documents matching the given query. self and query are both reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see GData.DocumentsService.query_documents(), which is the synchronous version of this function, and GData.Service.query_async(), which is the base asynchronous query function.

New in version 0.9.1.

query_drives(query, cancellable, progress_callback, *progress_user_data)
Parameters:
Raises:

GLib.Error

Returns:

a GData.DocumentsFeed of query results; unref with GObject.Object.unref()

Return type:

GData.DocumentsFeed

Queries the service to return a list of shared drives matching the given query.

For more details, see GData.Service.query().

New in version 0.18.0.

query_drives_async(query, cancellable, progress_callback, progress_user_data, callback, *user_data)
Parameters:

Queries the service to return a list of shared drives matching the given query. self and query are both reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see GData.DocumentsService.query_drives(), which is the synchronous version of this function, and GData.Service.query_async(), which is the base asynchronous query function.

New in version 0.18.0.

remove_entry_from_folder(entry, folder, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

an updated GData.DocumentsEntry, or None; unref with GObject.Object.unref()

Return type:

GData.DocumentsEntry

Remove the given entry from folder, and return an updated GData.DocumentsEntry for entry. entry will remain a member of any other folders it’s currently in. Note that entry can be either a GData.DocumentsDocument or a GData.DocumentsFolder.

Errors from GData.ServiceError can be returned for exceptional conditions, as determined by the server.

New in version 0.8.0.

remove_entry_from_folder_async(entry, folder, cancellable, callback, *user_data)
Parameters:

Remove the given entry from the specified folder. self, entry and folder are all reffed when this function is called, so can safely be unreffed after this function returns.

For more details, see GData.DocumentsService.remove_entry_from_folder(), which is the synchronous version of this function.

When the operation is finished, callback will be called. You can then call GData.DocumentsService.remove_entry_from_folder_finish() to get the results of the operation.

New in version 0.8.0.

remove_entry_from_folder_finish(async_result)
Parameters:

async_result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

an updated GData.DocumentsEntry, or None; unref with GObject.Object.unref()

Return type:

GData.DocumentsEntry

Finish an asynchronous operation to remove a GData.DocumentsEntry from a folder started with GData.DocumentsService.remove_entry_from_folder_async().

New in version 0.8.0.

update_document(document, slug, content_type, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a GData.UploadStream to write the document data to; unref with GObject.Object.unref()

Return type:

GData.UploadStream

Update the document using the properties from document and the document data written to the resulting GData.UploadStream. If the document data does not need to be changed, just the metadata, use GData.Service.update_entry() instead.

This performs a non-resumable upload, unlike GData.DocumentsService.update_document(). This means that errors during transmission will cause the upload to fail, and the entire document will have to be re-uploaded. It is recommended that GData.DocumentsService.update_document_resumable() be used instead.

The stream returned by this function should be written to using the standard Gio.OutputStream methods, asynchronously or synchronously. Once the stream is closed (using Gio.OutputStream.close()), GData.DocumentsService.finish_upload() should be called on it to parse and return the updated GData.DocumentsDocument for the document. This must be done, as document isn’t updated in-place.

In order to cancel the update, a Gio.Cancellable passed in to cancellable must be cancelled using Gio.Cancellable.cancel(). Cancelling the individual Gio.OutputStream operations on the GData.UploadStream will not cancel the entire update; merely the write or close operation in question. See the GData.UploadStream :cancellable for more details.

Any upload errors will be thrown by the stream methods, and may come from the GData.ServiceError domain.

For more information, see GData.Service.update_entry().

New in version 0.8.0.

update_document_resumable(document, slug, content_type, content_length, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a GData.UploadStream to write the document data to; unref with GObject.Object.unref()

Return type:

GData.UploadStream

Update the document using the properties from document and the document data written to the resulting GData.UploadStream. If the document data does not need to be changed, just the metadata, use GData.Service.update_entry() instead.

Unlike GData.DocumentsService.update_document(), this method performs a

resumable upload which allows for correction of transmission errors without re-uploading the entire file. Use of this method is preferred over GData.DocumentsService.update_document().

The stream returned by this function should be written to using the standard Gio.OutputStream methods, asynchronously or synchronously. Once the stream is closed (using Gio.OutputStream.close()), GData.DocumentsService.finish_upload() should be called on it to parse and return the updated GData.DocumentsDocument for the document. This must be done, as document isn’t updated in-place.

In order to cancel the update, a Gio.Cancellable passed in to cancellable must be cancelled using Gio.Cancellable.cancel(). Cancelling the individual Gio.OutputStream operations on the GData.UploadStream will not cancel the entire update; merely the write or close operation in question. See the GData.UploadStream :cancellable for more details.

Any upload errors will be thrown by the stream methods, and may come from the GData.ServiceError domain.

For more information, see GData.Service.update_entry().

New in version 0.13.0.

upload_document(document, slug, content_type, folder, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a GData.UploadStream to write the document data to, or None; unref with GObject.Object.unref()

Return type:

GData.UploadStream

Uploads a document to Google Documents, using the properties from document and the document data written to the resulting GData.UploadStream. If the document data does not need to be provided at the moment, just the metadata, use GData.Service.insert_entry() instead (e.g. in the case of creating a new, empty file to be edited at a later date).

This performs a non-resumable upload, unlike GData.DocumentsService.upload_document(). This means that errors during transmission will cause the upload to fail, and the entire document will have to be re-uploaded. It is recommended that GData.DocumentsService.upload_document_resumable() be used instead.

If document is None, only the document data will be uploaded. The new document entry will be named using slug, and will have default metadata.

The stream returned by this function should be written to using the standard Gio.OutputStream methods, asynchronously or synchronously. Once the stream is closed (using Gio.OutputStream.close()), GData.DocumentsService.finish_upload() should be called on it to parse and return the updated GData.DocumentsDocument for the document. This must be done, as document isn’t updated in-place.

In order to cancel the upload, a Gio.Cancellable passed in to cancellable must be cancelled using Gio.Cancellable.cancel(). Cancelling the individual Gio.OutputStream operations on the GData.UploadStream will not cancel the entire upload; merely the write or close operation in question. See the GData.UploadStream :cancellable for more details.

Any upload errors will be thrown by the stream methods, and may come from the GData.ServiceError domain.

New in version 0.8.0.

upload_document_resumable(document, slug, content_type, content_length, query, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a GData.UploadStream to write the document data to, or None; unref with GObject.Object.unref()

Return type:

GData.UploadStream

Uploads a document to Google Documents, using the properties from document and the document data written to the resulting GData.UploadStream. If the document data does not need to be provided at the moment, just the metadata, use GData.Service.insert_entry() instead (e.g. in the case of creating a new, empty file to be edited at a later date).

Unlike GData.DocumentsService.upload_document(), this method performs a

resumable upload which allows for correction of transmission errors without re-uploading the entire file. Use of this method is preferred over GData.DocumentsService.upload_document().

If document is None, only the document data will be uploaded. The new document entry will be named using slug, and will have default metadata.

If non-None, the query specifies parameters for the upload, such as a GData.DocumentsFolder to upload the document into; and whether to treat the document as an opaque file, or convert it to a standard format. If query is None, the document will be uploaded into the root folder, and automatically converted to a standard format. No OCR or automatic language translation will be performed by default.

If query is non-None and GData.DocumentsUploadQuery :convert is False, document must be an instance of GData.DocumentsDocument. Otherwise, document must be a subclass of it, such as GData.DocumentsPresentation.

The stream returned by this function should be written to using the standard Gio.OutputStream methods, asynchronously or synchronously. Once the stream is closed (using Gio.OutputStream.close()), GData.DocumentsService.finish_upload() should be called on it to parse and return the updated GData.DocumentsDocument for the document. This must be done, as document isn’t updated in-place.

In order to cancel the upload, a Gio.Cancellable passed in to cancellable must be cancelled using Gio.Cancellable.cancel(). Cancelling the individual Gio.OutputStream operations on the GData.UploadStream will not cancel the entire upload; merely the write or close operation in question. See the GData.UploadStream :cancellable for more details.

Any upload errors will be thrown by the stream methods, and may come from the GData.ServiceError domain.

New in version 0.13.0.