GDataDocumentsService

## GDataDocumentsService GDataDocumentsService — GData Documents service object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        GDataDocumentsService;
                        GDataDocumentsServiceClass;
    enum                GDataDocumentsServiceError;
    GDataDocumentsService * gdata_documents_service_new     (const gchar *client_id);
    GDataDocumentsFeed * gdata_documents_service_query_documents
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_documents_service_query_documents_async
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataDocumentsEntry * gdata_documents_service_upload_document
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsEntry *document,
                                                             GFile *document_file,
                                                             GDataDocumentsFolder *folder,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GDataDocumentsEntry * gdata_documents_service_update_document
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsEntry *document,
                                                             GFile *document_file,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GDataDocumentsEntry * gdata_documents_service_move_document_to_folder
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsEntry *document,
                                                             GDataDocumentsFolder *folder,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GDataDocumentsEntry * gdata_documents_service_remove_document_from_folder
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsEntry *document,
                                                             GDataDocumentsFolder *folder,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GDataService
             +----GDataDocumentsService

## Properties

      "spreadsheet-service"      GDataService*         : Read

## Description

GDataDocumentsService is a subclass of GDataService for communicating with the GData API of Google Documents. It supports querying for, inserting, editing and deleting documents, as well as a folder hierarchy.

For more details of Google Documents' GData API, see the online documentation.

Fore more details about the spreadsheet downloads handling, see the online explanation about the problem.

## Details

### 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

    typedef enum {
    	GDATA_DOCUMENTS_SERVICE_ERROR_INVALID_CONTENT_TYPE
    } GDataDocumentsServiceError;

Error codes for GDataDocumentsService operations.

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

Since 0.4.0

### gdata_documents_service_new ()

    GDataDocumentsService * gdata_documents_service_new     (const gchar *client_id);

Creates a new GDataDocumentsService. The `client_id` must be unique for your application, and as registered with Google.

`client_id` : | your application's client ID
Returns : | a new GDataDocumentsService, or `NULL`; unref with `g_object_unref()`

Since 0.4.0

### 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`.

For more details, see `gdata_service_query()`.

`self` : | a GDataDocumentsService
`query` : | a GDataQuery with the query parameters, or `NULL`
`cancellable` : | optional GCancellable object, or `NULL`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`
`progress_user_data` : | data to pass to the `progress_callback` function
`error` : | a GError, or `NULL`
Returns : | a GDataDocumentsFeed of query results; unref with `g_object_unref()`

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,
                                                             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.

`self` : | a GDataDocumentsService
`query` : | a GDataQuery with the query parameters, or `NULL`
`cancellable` : | optional GCancellable object, or `NULL`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`
`progress_user_data` : | data to pass to the `progress_callback` function
`callback` : | a GAsyncReadyCallback to call when authentication is finished
`user_data` : | data to pass to the `callback` function

Since 0.4.0

### gdata_documents_service_upload_document ()

    GDataDocumentsEntry * gdata_documents_service_upload_document
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsEntry *document,
                                                             GFile *document_file,
                                                             GDataDocumentsFolder *folder,
                                                             GCancellable *cancellable,
                                                             GError **error);

Uploads a document to Google Documents, using the properties from `document` and the document file pointed to by `document_file`.

If `document` is `NULL`, only the document file will be uploaded. The new document entry will be named after the document file's name, and will have default metadata.

If `document_file` is `NULL`, only the document metadata will be uploaded. A blank document file will be created with the name `new document` and the specified metadata. `document` and `document_file` cannot both be `NULL`, but can both have values.

The updated `document_entry` will be returned on success, containing updated metadata.

If there is a problem reading `document_file`, an error from `g_file_load_contents()` or `g_file_query_info()` will be returned. Other errors from GDataServiceError can be returned for other exceptional conditions, as determined by the server.

`self` : | an authenticated GDataDocumentsService
`document` : | the GDataDocumentsEntry to insert, or `NULL`
`document_file` : | the document to upload, or `NULL`
`folder` : | the folder to which the document should be uploaded, or `NULL`
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`

Since 0.4.0

### gdata_documents_service_update_document ()

    GDataDocumentsEntry * gdata_documents_service_update_document
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsEntry *document,
                                                             GFile *document_file,
                                                             GCancellable *cancellable,
                                                             GError **error);

Update the document using the properties from `document` and the document file pointed to by `document_file`.

If there is a problem reading `document_file`, an error from `g_file_load_contents()` or `g_file_query_info()` will be returned. Other errors from GDataServiceError can be returned for other exceptional conditions, as determined by the server.

For more details, see `gdata_service_insert_entry()`.

`self` : | a GDataDocumentsService
`document` : | the GDataDocumentsEntry to update
`document_file` : | the local document file containing the new data, or `NULL`
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`

Since 0.4.0

### gdata_documents_service_move_document_to_folder ()

    GDataDocumentsEntry * gdata_documents_service_move_document_to_folder
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsEntry *document,
                                                             GDataDocumentsFolder *folder,
                                                             GCancellable *cancellable,
                                                             GError **error);

Move the given `document` to the specified `folder`. If the document is already in another folder, it will be added to the new folder, but will also remain in any previous folders.

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

`self` : | an authenticated GDataDocumentsService
`document` : | the GDataDocumentsEntry to move
`folder` : | the GDataDocumentsFolder to move `document` into
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`

Since 0.4.0

### gdata_documents_service_remove_document_from_folder ()

    GDataDocumentsEntry * gdata_documents_service_remove_document_from_folder
                                                            (GDataDocumentsService *self,
                                                             GDataDocumentsEntry *document,
                                                             GDataDocumentsFolder *folder,
                                                             GCancellable *cancellable,
                                                             GError **error);

Remove the GDataDocumentsEntry `document` from the GDataDocumentsFolder `folder`, and updates the document entry `document`.

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

`self` : | a GDataDocumentsService
`document` : | the GDataDocumentsEntry to remove
`folder` : | the GDataDocumentsFolder from wich we should remove `document`
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`

Since 0.4.0

## Property Details

### The `"spreadsheet-service"` property

      "spreadsheet-service"      GDataService*         : Read

Another service for spreadsheets.