GDataDocumentsService: GData Reference Manual

## GDataDocumentsService GDataDocumentsService — GData Documents service object |

## Stability Level

Stable, unless otherwise indicated

## Functions

GDataDocumentsService * | gdata_documents_service_new ()
GDataAuthorizationDomain * | gdata_documents_service_get_primary_authorization_domain ()
GDataAuthorizationDomain * | gdata_documents_service_get_spreadsheet_authorization_domain ()
GDataDocumentsMetadata * | gdata_documents_service_get_metadata ()
void | gdata_documents_service_get_metadata_async ()
GDataDocumentsMetadata * | gdata_documents_service_get_metadata_finish ()
GDataDocumentsFeed * | gdata_documents_service_query_documents ()
void | gdata_documents_service_query_documents_async ()
GDataDocumentsFeed * | gdata_documents_service_query_drives ()
void | gdata_documents_service_query_drives_async ()
GDataUploadStream * | gdata_documents_service_upload_document ()
GDataUploadStream * | gdata_documents_service_upload_document_resumable ()
GDataUploadStream * | gdata_documents_service_update_document ()
GDataUploadStream * | gdata_documents_service_update_document_resumable ()
GDataDocumentsDocument * | gdata_documents_service_finish_upload ()
GDataDocumentsDocument * | gdata_documents_service_copy_document ()
void | gdata_documents_service_copy_document_async ()
GDataDocumentsDocument * | gdata_documents_service_copy_document_finish ()
GDataDocumentsEntry * | gdata_documents_service_add_entry_to_folder ()
void | gdata_documents_service_add_entry_to_folder_async ()
GDataDocumentsEntry * | gdata_documents_service_add_entry_to_folder_finish ()
GDataDocumentsEntry * | gdata_documents_service_remove_entry_from_folder ()
void | gdata_documents_service_remove_entry_from_folder_async ()
GDataDocumentsEntry * | gdata_documents_service_remove_entry_from_folder_finish ()
gchar * | gdata_documents_service_get_upload_uri ()

## Types and Values

| GDataDocumentsService
| GDataDocumentsServiceClass
enum | GDataDocumentsServiceError

## Object Hierarchy

        GObject
        ╰── GDataService
            ╰── GDataDocumentsService

## Implemented Interfaces

GDataDocumentsService implements GDataBatchable.

## Includes

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

## Description

GDataDocumentsService is a subclass of GDataService for communicating with the GData API of Google Drive. It supports querying for, inserting, editing and deleting documents, as well as a folder hierarchy. The API is named ‘documents’ rather than ‘drive’ as it used to use the Google Documents API, which has since been deprecated.

For more details of Google Drive's GData API, see the

online documentation.

Fore more details about the spreadsheet downloads handling, see the

online explanation about the problem.

Example 26. Uploading a Document from Disk

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    GDataDocumentsService *service;
    GDataDocumentsDocument *document, *uploaded_document;
    GFile *document_file;
    GDataDocumentsFolder *destination_folder;
    GFileInfo *file_info;
    const gchar *slug, *content_type;
    GFileInputStream *file_stream;
    GDataUploadStream *upload_stream;
    GError *error = NULL;

    /* Create a service */
    service = create_documents_service ();

    /* Get the document file to upload and the folder to upload it into */
    document_file = g_file_new_for_path ("document.odt");
    destination_folder = query_user_for_destination_folder (service);

    /* Get the file's display name and content type */
    file_info = g_file_query_info (document_file, G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME "," G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE,
                                   G_FILE_QUERY_INFO_NONE, NULL, &error);

    if (error != NULL) {
    	g_error ("Error getting document file information: %s", error->message);
    	g_error_free (error);
    	g_object_unref (destination_folder);
    	g_object_unref (document_file);
    	g_object_unref (service);
    	return;
    }

    slug = g_file_info_get_display_name (file_info);
    content_type = g_file_info_get_content_type (file_info);

    /* Get an input stream for the file */
    file_stream = g_file_read (document_file, NULL, &error);

    g_object_unref (document_file);

    if (error != NULL) {
    	g_error ("Error getting document file stream: %s", error->message);
    	g_error_free (error);
    	g_object_unref (file_info);
    	g_object_unref (destination_folder);
    	g_object_unref (service);
    	return;
    }

    /* Create the document metadata to upload */
    document = gdata_documents_text_new (NULL);
    gdata_entry_set_title (GDATA_ENTRY (document), "Document Title");

    /* Get an upload stream for the document */
    upload_stream = gdata_documents_service_upload_document (service, document, slug, content_type, destination_folder, NULL, &error);

    g_object_unref (document);
    g_object_unref (file_info);
    g_object_unref (destination_folder);

    if (error != NULL) {
    	g_error ("Error getting upload stream: %s", error->message);
    	g_error_free (error);
    	g_object_unref (file_stream);
    	g_object_unref (service);
    	return;
    }

    /* Upload the document. This is a blocking operation, and should normally be done asynchronously. */
    g_output_stream_splice (G_OUTPUT_STREAM (upload_stream), G_INPUT_STREAM (file_stream),
                            G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE | G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET, NULL, &error);

    g_object_unref (file_stream);

    if (error != NULL) {
    	g_error ("Error splicing streams: %s", error->message);
    	g_error_free (error);
    	g_object_unref (upload_stream);
    	g_object_unref (service);
    	return;
    }

    /* Finish off the upload by parsing the returned updated document metadata entry */
    uploaded_document = gdata_documents_service_finish_upload (service, upload_stream, &error);

    g_object_unref (upload_stream);
    g_object_unref (service);

    if (error != NULL) {
    	g_error ("Error uploading document: %s", error->message);
    	g_error_free (error);
    	return;
    }

    /* Do something with the uploaded document */

    g_object_unref (uploaded_document);

The Drive service can be manipulated using batch operations, too. See the

online documentation on batch operations for more information.

Example 27. Performing a Batch Operation on Documents

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    GDataDocumentsService *service;
    GDataBatchOperation *operation;
    GDataFeed *feed;
    GDataLink *batch_link;
    GList *i;
    GError *error = NULL;

    /* Create a service */
    service = create_documents_service ();

    /* Create the batch operation; this requires that we have done a query first so that we can get the batch link */
    feed = do_some_query (service);
    batch_link = gdata_feed_look_up_link (feed, GDATA_LINK_BATCH);
    operation = gdata_batchable_create_operation (GDATA_BATCHABLE (service), gdata_link_get_uri (batch_link));
    g_object_unref (feed);

    gdata_batch_operation_add_query (operation, presentation_entry_id_to_query, GDATA_TYPE_DOCUMENTS_PRESENTATION,
                                     (GDataBatchOperationCallback) batch_query_cb, user_data);
    gdata_batch_operation_add_insertion (operation, new_entry, (GDataBatchOperationCallback) batch_insertion_cb, user_data);
    gdata_batch_operation_add_update (operation, old_entry, (GDataBatchOperationCallback) batch_update_cb, user_data);
    gdata_batch_operation_add_deletion (operation, entry_to_delete, (GDataBatchOperationCallback) batch_deletion_cb, user_data);

    /* Run the batch operation and handle the results in the various callbacks */
    gdata_test_batch_operation_run (operation, NULL, &error);

    g_object_unref (operation);
    g_object_unref (service);

    if (error != NULL) {
    	g_error ("Error running batch operation: %s", error->message);
    	g_error_free (error);
    	return;
    }

    static void
    batch_query_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
    {
    	/* operation_type == GDATA_BATCH_OPERATION_QUERY */
    	/* Reference and do something with the returned entry. */
    }

    static void
    batch_insertion_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
    {
    	/* operation_type == GDATA_BATCH_OPERATION_INSERTION */
    	/* Reference and do something with the returned entry. */
    }

    static void
    batch_update_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
    {
    	/* operation_type == GDATA_BATCH_OPERATION_UPDATE */
    	/* Reference and do something with the returned entry. */
    }

    static void
    batch_deletion_cb (guint operation_id, GDataBatchOperationType operation_type, GDataEntry *entry, GError *error, gpointer user_data)
    {
    	/* operation_type == GDATA_BATCH_OPERATION_DELETION, entry == NULL */
    }

Starred documents are denoted by being in the `GDATA_CATEGORY_SCHEMA_LABELS_STARRED` category of the `GDATA_CATEGORY_SCHEMA_LABELS` schema. Documents can be starred or unstarred simply by adding or removing this category from them and updating the document:

Example 28. Starring a Document

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    GDataDocumentsService *service;
    GDataDocumentsEntry *document, *updated_document;
    GDataCategory *starred_category;
    GError *error = NULL;

    /* Create a service and retrieve the document to be starred */
    service = create_documents_service ();
    document = get_document_to_be_starred (service);

    /* Add the “starred” category to the document */
    starred_category = gdata_category_new (GDATA_CATEGORY_SCHEMA_LABELS_STARRED, GDATA_CATEGORY_SCHEMA_LABELS, "starred");
    gdata_entry_add_category (GDATA_ENTRY (document), starred_category);
    g_object_unref (starred_category);

    /* Propagate the updated document to the server */
    updated_document = GDATA_DOCUMENTS_ENTRY (gdata_service_update_entry (GDATA_SERVICE (service),
                                                                          gdata_documents_service_get_primary_authorization_domain (),
                                                                          GDATA_ENTRY (document), NULL, &error));

    g_object_unref (document);
    g_object_unref (service);

    if (error != NULL) {
    	g_error ("Error starring document: %s", error->message);
    	g_error_free (error);
    	return;
    }

    /* Do something with the newly-starred document, like update it in the UI */

    g_object_unref (updated_document);

## Functions

### gdata_documents_service_new ()

    GDataDocumentsService *
    gdata_documents_service_new (GDataAuthorizer *authorizer);

Creates a new GDataDocumentsService using the given GDataAuthorizer. If `authorizer` is `NULL`, all requests are made as an unauthenticated user.

#### Parameters

authorizer | a GDataAuthorizer to authorize the service's requests, or `NULL`. | [allow-none]

#### Returns

a new GDataDocumentsService, or `NULL`; unref with `g_object_unref()`

Since: 0.9.0

### gdata_documents_service_get_primary_authorization_domain ()

    GDataAuthorizationDomain *
    gdata_documents_service_get_primary_authorization_domain
                                   (void);

The primary GDataAuthorizationDomain for interacting with Google Documents. This will not normally need to be used, as it's used internally by the GDataDocumentsService methods. However, if using the plain GDataService 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.

#### Returns

the service's authorization domain.

[transfer none]

Since: 0.9.0

### gdata_documents_service_get_spreadsheet_authorization_domain ()

    GDataAuthorizationDomain *
    gdata_documents_service_get_spreadsheet_authorization_domain
                                   (void);

The GDataAuthorizationDomain for interacting with spreadsheet data. This will not normally need to be used, as it's automatically used internally by the GDataDocumentsService methods. However, if using the plain GDataService 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.

#### Returns

the service's authorization domain.

[transfer none]

Since: 0.9.0

### gdata_documents_service_get_metadata ()

    GDataDocumentsMetadata *
    gdata_documents_service_get_metadata (GDataDocumentsService *self,
                                          GCancellable *cancellable,
                                          GError **error);

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

#### Parameters

self | a GDataDocumentsService |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

the service's metadata object; unref with `g_object_unref()`.

[transfer full]

Since: 0.17.9

### gdata_documents_service_get_metadata_async ()

    void
    gdata_documents_service_get_metadata_async
                                   (GDataDocumentsService *self,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

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

For more details, see `gdata_documents_service_get_metadata()`, which is the synchronous version of this function.

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

#### Parameters

self | a GDataDocumentsService |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
callback | a GAsyncReadyCallback to call when the operation is finished, or `NULL` |
user_data | data to pass to the `callback` function. | [closure]

Since: 0.17.9

### gdata_documents_service_get_metadata_finish ()

    GDataDocumentsMetadata *
    gdata_documents_service_get_metadata_finish
                                   (GDataDocumentsService *self,
                                    GAsyncResult *async_result,
                                    GError **error);

Finish an asynchronous operation to get a GDataDocumentsMetadata started with `gdata_documents_service_get_metadata_async()`.

#### Parameters

self | a GDataDocumentsService |
async_result | a GAsyncResult |
error | a GError, or `NULL` |

#### Returns

the service's metadata object; unref with `g_object_unref()`.

[transfer full]

Since: 0.17.9

### gdata_documents_service_query_documents ()

    GDataDocumentsFeed *
    gdata_documents_service_query_documents
                                   (GDataDocumentsService *self,
                                    GDataDocumentsQuery *query,
                                    GCancellable *cancellable,
                                    GDataQueryProgressCallback progress_callback,
                                    gpointer progress_user_data,
                                    GError **error);

Queries the service to return a list of documents matching the given `query` . Note that `query` has to be a GDataDocumentsQuery, rather than just a GDataQuery, as it uses the folder ID specified in “folder-id”.

For more details, see `gdata_service_query()`.

#### Parameters

self | a GDataDocumentsService |
query | a GDataDocumentsQuery with the query parameters, or `NULL`. | [allow-none]
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
progress_callback | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. | [allow-none][scope call][closure progress_user_data]
progress_user_data | data to pass to the `progress_callback` function. | [closure]
error | a GError, or `NULL` |

#### Returns

a GDataDocumentsFeed of query results; unref with `g_object_unref()`.

[transfer full]

Since: 0.4.0

### gdata_documents_service_query_documents_async ()

    void
    gdata_documents_service_query_documents_async
                                   (GDataDocumentsService *self,
                                    GDataDocumentsQuery *query,
                                    GCancellable *cancellable,
                                    GDataQueryProgressCallback progress_callback,
                                    gpointer progress_user_data,
                                    GDestroyNotify destroy_progress_user_data,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

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_documents_service_query_documents()`, which is the synchronous version of this function, and `gdata_service_query_async()`, which is the base asynchronous query function.

#### Parameters

self | a GDataDocumentsService |
query | a GDataDocumentsQuery with the query parameters, or `NULL`. | [allow-none]
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
progress_callback | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. | [allow-none][closure progress_user_data]
progress_user_data | data to pass to the `progress_callback` function. | [closure]
destroy_progress_user_data | the function to call when `progress_callback` will not be called any more, or `NULL`. This function will be called with `progress_user_data` as a parameter and can be used to free any memory allocated for it. | [allow-none]
callback | a GAsyncReadyCallback to call when authentication is finished |
user_data | data to pass to the `callback` function. | [closure]

Since: 0.9.1

### gdata_documents_service_query_drives ()

    GDataDocumentsFeed *
    gdata_documents_service_query_drives (GDataDocumentsService *self,
                                          GDataDocumentsDriveQuery *query,
                                          GCancellable *cancellable,
                                          GDataQueryProgressCallback progress_callback,
                                          gpointer progress_user_data,
                                          GError **error);

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

For more details, see `gdata_service_query()`.

#### Parameters

self | a GDataDocumentsService |
query | a GDataDocumentsDriveQuery with the query parameters, or `NULL`. | [nullable]
cancellable | optional GCancellable object, or `NULL`. | [nullable]
progress_callback | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. | [nullable][scope call][closure progress_user_data]
progress_user_data | data to pass to the `progress_callback` function. | [closure]
error | a GError, or `NULL` |

#### Returns

a GDataDocumentsFeed of query results; unref with `g_object_unref()`.

[transfer full]

Since: 0.18.0

### gdata_documents_service_query_drives_async ()

    void
    gdata_documents_service_query_drives_async
                                   (GDataDocumentsService *self,
                                    GDataDocumentsDriveQuery *query,
                                    GCancellable *cancellable,
                                    GDataQueryProgressCallback progress_callback,
                                    gpointer progress_user_data,
                                    GDestroyNotify destroy_progress_user_data,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

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_documents_service_query_drives()`, which is the synchronous version of this function, and `gdata_service_query_async()`, which is the base asynchronous query function.

#### Parameters

self | a GDataDocumentsService |
query | a GDataDocumentsDriveQuery with the query parameters, or `NULL`. | [nullable]
cancellable | optional GCancellable object, or `NULL`. | [nullable]
progress_callback | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. | [nullable][closure progress_user_data]
progress_user_data | data to pass to the `progress_callback` function. | [closure]
destroy_progress_user_data | the function to call when `progress_callback` will not be called any more, or `NULL`. This function will be called with `progress_user_data` as a parameter and can be used to free any memory allocated for it. | [nullable]
callback | a GAsyncReadyCallback to call when authentication is finished |
user_data | data to pass to the `callback` function. | [closure]

Since: 0.18.0

### gdata_documents_service_upload_document ()

    GDataUploadStream *
    gdata_documents_service_upload_document
                                   (GDataDocumentsService *self,
                                    GDataDocumentsDocument *document,
                                    const gchar *slug,
                                    const gchar *content_type,
                                    GDataDocumentsFolder *folder,
                                    GCancellable *cancellable,
                                    GError **error);

Uploads a document to Google Documents, using the properties from `document` and the document data written to the resulting GDataUploadStream. 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_documents_service_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_documents_service_upload_document_resumable()` be used instead.

If `document` is `NULL`, 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 GOutputStream methods, asynchronously or synchronously. Once the stream 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 “cancellable” for more details.

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

#### Parameters

self | an authenticated GDataDocumentsService |
document | the GDataDocumentsDocument to insert, or `NULL`. | [allow-none]
slug | the filename to give to the uploaded document |
content_type | the content type of the uploaded data |
folder | the folder to which the document should be uploaded, or `NULL`. | [allow-none]
cancellable | a GCancellable for the entire upload stream, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

a GDataUploadStream to write the document data to, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.8.0

### gdata_documents_service_upload_document_resumable ()

    GDataUploadStream *
    gdata_documents_service_upload_document_resumable
                                   (GDataDocumentsService *self,
                                    GDataDocumentsDocument *document,
                                    const gchar *slug,
                                    const gchar *content_type,
                                    goffset content_length,
                                    GDataDocumentsUploadQuery *query,
                                    GCancellable *cancellable,
                                    GError **error);

Uploads a document to Google Documents, using the properties from `document` and the document data written to the resulting GDataUploadStream. 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_documents_service_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_documents_service_upload_document()`.

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

If non-`NULL`, the `query` specifies parameters for the upload, such as a GDataDocumentsFolder 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 `NULL`, 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-`NULL` and “convert” is `FALSE`, `document` must be an instance of GDataDocumentsDocument. Otherwise, `document` must be a subclass of it, such as GDataDocumentsPresentation.

The stream returned by this function should be written to using the standard GOutputStream methods, asynchronously or synchronously. Once the stream 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 “cancellable” for more details.

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

#### Parameters

self | an authenticated GDataDocumentsService |
document | the GDataDocumentsDocument to insert, or `NULL`. | [allow-none]
slug | the filename to give to the uploaded document |
content_type | the content type of the uploaded data |
content_length | the size (in bytes) of the file being uploaded |
query | a query specifying parameters for the upload, or `NULL`. | [allow-none]
cancellable | a GCancellable for the entire upload stream, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

a GDataUploadStream to write the document data to, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.13.0

### gdata_documents_service_update_document ()

    GDataUploadStream *
    gdata_documents_service_update_document
                                   (GDataDocumentsService *self,
                                    GDataDocumentsDocument *document,
                                    const gchar *slug,
                                    const gchar *content_type,
                                    GCancellable *cancellable,
                                    GError **error);

Update the document using the properties from `document` and the document data written to the resulting GDataUploadStream. 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_documents_service_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_documents_service_update_document_resumable()` be used instead.

The stream returned by this function should be written to using the standard GOutputStream methods, asynchronously or synchronously. Once the stream 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 “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()`.

#### Parameters

self | a GDataDocumentsService |
document | the GDataDocumentsDocument to update |
slug | the filename to give to the uploaded document |
content_type | the content type of the uploaded data |
cancellable | a GCancellable for the entire upload stream, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

a GDataUploadStream to write the document data to; unref with `g_object_unref()`.

[transfer full]

Since: 0.8.0

### gdata_documents_service_update_document_resumable ()

    GDataUploadStream *
    gdata_documents_service_update_document_resumable
                                   (GDataDocumentsService *self,
                                    GDataDocumentsDocument *document,
                                    const gchar *slug,
                                    const gchar *content_type,
                                    goffset content_length,
                                    GCancellable *cancellable,
                                    GError **error);

Update the document using the properties from `document` and the document data written to the resulting GDataUploadStream. If the document data does not need to be changed, just the metadata, use `gdata_service_update_entry()` instead.

Unlike `gdata_documents_service_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_documents_service_update_document()`.

The stream returned by this function should be written to using the standard GOutputStream methods, asynchronously or synchronously. Once the stream 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 “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()`.

#### Parameters

self | a GDataDocumentsService |
document | the GDataDocumentsDocument to update |
slug | the filename to give to the uploaded document |
content_type | the content type of the uploaded data |
content_length | the size (in bytes) of the file being uploaded |
cancellable | a GCancellable for the entire upload stream, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

a GDataUploadStream to write the document data to; unref with `g_object_unref()`.

[transfer full]

Since: 0.13.0

### gdata_documents_service_finish_upload ()

    GDataDocumentsDocument *
    gdata_documents_service_finish_upload (GDataDocumentsService *self,
                                           GDataUploadStream *upload_stream,
                                           GError **error);

Finish off a document upload or update operation started by `gdata_documents_service_upload_document()` or `gdata_documents_service_update_document()`, parsing the result and returning the new or updated GDataDocumentsDocument.

If an error occurred during the upload or update operation, it will have been returned during the operation (e.g. by `g_output_stream_splice()` or one of the other stream methods). In such a case, `NULL` 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 GDataDocumentsDocument was passed (to `gdata_documents_service_upload_document()` or `gdata_documents_service_update_document()`) when starting the operation, `GDATA_DOCUMENTS_SERVICE_ERROR_INVALID_CONTENT_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.

#### Parameters

self | a GDataDocumentsService |
upload_stream | the GDataUploadStream from the operation |
error | a GError, or `NULL` |

#### Returns

the new or updated GDataDocumentsDocument, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.8.0

### gdata_documents_service_copy_document ()

    GDataDocumentsDocument *
    gdata_documents_service_copy_document (GDataDocumentsService *self,
                                           GDataDocumentsDocument *document,
                                           GCancellable *cancellable,
                                           GError **error);

Copy the given `document` , producing a duplicate document in the same folder and returning its GDataDocumentsDocument.

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

#### Parameters

self | an authenticated GDataDocumentsService |
document | the GDataDocumentsDocument to copy |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

the duplicate GDataDocumentsDocument, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.13.1

### gdata_documents_service_copy_document_async ()

    void
    gdata_documents_service_copy_document_async
                                   (GDataDocumentsService *self,
                                    GDataDocumentsDocument *document,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Copy the given `document` , producing a duplicate document in the same folder and returning its GDataDocumentsDocument. `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_documents_service_copy_document()`, which is the synchronous version of this function.

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

#### Parameters

self | a GDataDocumentsService |
document | the GDataDocumentsDocument to copy |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
callback | a GAsyncReadyCallback to call when the operation is finished, or `NULL` |
user_data | data to pass to the `callback` function. | [closure]

Since: 0.13.1

### gdata_documents_service_copy_document_finish ()

    GDataDocumentsDocument *
    gdata_documents_service_copy_document_finish
                                   (GDataDocumentsService *self,
                                    GAsyncResult *async_result,
                                    GError **error);

Finish an asynchronous operation to copy a GDataDocumentsDocument started with `gdata_documents_service_copy_document_async()`.

#### Parameters

self | a GDataDocumentsService |
async_result | a GAsyncResult |
error | a GError, or `NULL` |

#### Returns

the duplicate GDataDocumentsDocument, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.13.1

### gdata_documents_service_add_entry_to_folder ()

    GDataDocumentsEntry *
    gdata_documents_service_add_entry_to_folder
                                   (GDataDocumentsService *self,
                                    GDataDocumentsEntry *entry,
                                    GDataDocumentsFolder *folder,
                                    GCancellable *cancellable,
                                    GError **error);

Add the given `entry` to the specified `folder` , and return an updated GDataDocumentsEntry 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 GDataDocumentsFolder that already exists on the server. It can be a new GDataDocumentsFolder, or a GDataDocumentsDocument that is either new or already present on the server.

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

#### Parameters

self | an authenticated GDataDocumentsService |
entry | the GDataDocumentsEntry to copy |
folder | the GDataDocumentsFolder to copy `entry` into |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.8.0

### gdata_documents_service_add_entry_to_folder_async ()

    void
    gdata_documents_service_add_entry_to_folder_async
                                   (GDataDocumentsService *self,
                                    GDataDocumentsEntry *entry,
                                    GDataDocumentsFolder *folder,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

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_documents_service_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_documents_service_add_entry_to_folder_finish()` to get the results of the operation.

#### Parameters

self | a GDataDocumentsService |
entry | the GDataDocumentsEntry to add to `folder` |
folder | the GDataDocumentsFolder to add `entry` to |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
callback | a GAsyncReadyCallback to call when the operation is finished, or `NULL` |
user_data | data to pass to the `callback` function. | [closure]

Since: 0.8.0

### gdata_documents_service_add_entry_to_folder_finish ()

    GDataDocumentsEntry *
    gdata_documents_service_add_entry_to_folder_finish
                                   (GDataDocumentsService *self,
                                    GAsyncResult *async_result,
                                    GError **error);

Finish an asynchronous operation to add a GDataDocumentsEntry to a folder started with `gdata_documents_service_add_entry_to_folder_async()`.

#### Parameters

self | a GDataDocumentsService |
async_result | a GAsyncResult |
error | a GError, or `NULL` |

#### Returns

an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.8.0

### gdata_documents_service_remove_entry_from_folder ()

    GDataDocumentsEntry *
    gdata_documents_service_remove_entry_from_folder
                                   (GDataDocumentsService *self,
                                    GDataDocumentsEntry *entry,
                                    GDataDocumentsFolder *folder,
                                    GCancellable *cancellable,
                                    GError **error);

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 exceptional conditions, as determined by the server.

#### Parameters

self | a GDataDocumentsService |
entry | the GDataDocumentsEntry to remove |
folder | the GDataDocumentsFolder from which we should remove `entry` |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.8.0

### gdata_documents_service_remove_entry_from_folder_async ()

    void
    gdata_documents_service_remove_entry_from_folder_async
                                   (GDataDocumentsService *self,
                                    GDataDocumentsEntry *entry,
                                    GDataDocumentsFolder *folder,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

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_documents_service_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_documents_service_remove_entry_from_folder_finish()` to get the results of the operation.

#### Parameters

self | a GDataDocumentsService |
entry | the GDataDocumentsEntry to remove from `folder` |
folder | the GDataDocumentsFolder to remove `entry` from |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
callback | a GAsyncReadyCallback to call when the operation is finished, or `NULL` |
user_data | data to pass to the `callback` function. | [closure]

Since: 0.8.0

### gdata_documents_service_remove_entry_from_folder_finish ()

    GDataDocumentsEntry *
    gdata_documents_service_remove_entry_from_folder_finish
                                   (GDataDocumentsService *self,
                                    GAsyncResult *async_result,
                                    GError **error);

Finish an asynchronous operation to remove a GDataDocumentsEntry from a folder started with `gdata_documents_service_remove_entry_from_folder_async()`.

#### Parameters

self | a GDataDocumentsService |
async_result | a GAsyncResult |
error | a GError, or `NULL` |

#### Returns

an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.8.0

### gdata_documents_service_get_upload_uri ()

    gchar *
    gdata_documents_service_get_upload_uri
                                   (GDataDocumentsFolder *folder);

Gets the upload URI for documents for the service.

If `folder` is `NULL`, the URI will be the one to upload documents to the "root" folder.

#### Parameters

folder | the GDataDocumentsFolder into which to upload the document, or `NULL`. | [allow-none]

#### Returns

the URI permitting the upload of documents to `folder` , or `NULL`; free with `g_free()`

Since: 0.5.0

## Types and Values

### GDataDocumentsService

    typedef struct _GDataDocumentsService GDataDocumentsService;

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

Since: 0.4.0

### GDataDocumentsServiceClass

    typedef struct {
    } GDataDocumentsServiceClass;

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

Since: 0.4.0

### enum GDataDocumentsServiceError

Error codes for GDataDocumentsService operations.

#### Members

GDATA_DOCUMENTS_SERVICE_ERROR_INVALID_CONTENT_TYPE | the content type of a provided file was invalid |

Since: 0.4.0