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_query_single_document
                                                            (GDataDocumentsService *self,
                                                             GType document_type,
                                                             const gchar *document_id,
                                                             GCancellable *cancellable,
                                                             GError **error);
    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);
    gchar *             gdata_documents_service_get_upload_uri
                                                            (GDataDocumentsFolder *folder);

## 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 GDataDocumentsQuery with the query parameters, or `NULL`. [allow-none]
`cancellable` : | optional GCancellable object, or `NULL`
`progress_callback` : | a GDataQueryProgressCallback to call when an entry is loaded, or `NULL`. [scope call]
`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,
                                                             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 GDataDocumentsQuery with the query parameters, or `NULL`. [allow-none]
`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. [closure]

Since 0.4.0

### gdata_documents_service_query_single_document ()

    GDataDocumentsEntry * gdata_documents_service_query_single_document
                                                            (GDataDocumentsService *self,
                                                             GType document_type,
                                                             const gchar *document_id,
                                                             GCancellable *cancellable,
                                                             GError **error);

Retrieves information about a single document with the given document ID.

`document_type` should be the expected type of the document to be returned. e.g. `GDATA_TYPE_DOCUMENTS_SPREADSHEET` if you're querying for a spreadsheet.

`document_id` should be the ID of the document as returned by `gdata_documents_entry_get_document_id()`.

Parameters and errors are as for `gdata_service_query()`.

`self` : | a GDataDocumentsService
`document_type` : | the expected GType of the queried entry
`document_id` : | the document ID of the queried document
`cancellable` : | a GCancellable, or `NULL`
`error` : | a GError, or `NULL`
Returns : | a GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.5.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`. [allow-none]
`document_file` : | the document to upload, or `NULL`. [allow-none]
`folder` : | the folder to which the document should be uploaded, or `NULL`. [allow-none]
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`. [transfer full]

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 the document file does not need to be changed, `document_file` can be `NULL`.

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`. [allow-none]
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataDocumentsEntry, or `NULL`; unref with `g_object_unref()`. [transfer full]

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()`. [transfer full]

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 which 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()`. [transfer full]

Since 0.4.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.

`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

## Property Details

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

      "spreadsheet-service"      GDataService*         : Read

Another service for spreadsheets.