GDataService

## GDataService GDataService — GData service object |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <gdata/gdata-service.h>

                        GDataService;
                        GDataServiceClass;
    enum                GDataServiceError;
    enum                GDataAuthenticationError;
    enum                GDataParserError;
    enum                GDataOperationType;
    void                (*GDataQueryProgressCallback)       (GDataEntry *entry,
                                                             guint entry_key,
                                                             guint entry_count,
                                                             gpointer user_data);
    gboolean            gdata_service_authenticate          (GDataService *self,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_service_authenticate_async    (GDataService *self,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gdata_service_authenticate_finish   (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);
    gboolean            gdata_service_is_authenticated      (GDataService *self);
    GDataFeed *         gdata_service_query                 (GDataService *self,
                                                             const gchar *feed_uri,
                                                             GDataQuery *query,
                                                             GType entry_type,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_service_query_async           (GDataService *self,
                                                             const gchar *feed_uri,
                                                             GDataQuery *query,
                                                             GType entry_type,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataFeed *         gdata_service_query_finish          (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);
    GDataEntry *        gdata_service_query_single_entry    (GDataService *self,
                                                             const gchar *entry_id,
                                                             GDataQuery *query,
                                                             GType entry_type,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_service_query_single_entry_async
                                                            (GDataService *self,
                                                             const gchar *entry_id,
                                                             GDataQuery *query,
                                                             GType entry_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataEntry *        gdata_service_query_single_entry_finish
                                                            (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);
    GDataEntry *        gdata_service_insert_entry          (GDataService *self,
                                                             const gchar *upload_uri,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_service_insert_entry_async    (GDataService *self,
                                                             const gchar *upload_uri,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataEntry *        gdata_service_insert_entry_finish   (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);
    GDataEntry *        gdata_service_update_entry          (GDataService *self,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_service_update_entry_async    (GDataService *self,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataEntry *        gdata_service_update_entry_finish   (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);
    gboolean            gdata_service_delete_entry          (GDataService *self,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_service_delete_entry_async    (GDataService *self,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gdata_service_delete_entry_finish   (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);
    const gchar *       gdata_service_get_client_id         (GDataService *self);
    const gchar *       gdata_service_get_username          (GDataService *self);
    const gchar *       gdata_service_get_password          (GDataService *self);
    SoupURI *           gdata_service_get_proxy_uri         (GDataService *self);
    void                gdata_service_set_proxy_uri         (GDataService *self,
                                                             SoupURI *proxy_uri);
    guint               gdata_service_get_timeout           (GDataService *self);
    void                gdata_service_set_timeout           (GDataService *self,
                                                             guint timeout);
    const gchar *       gdata_service_get_locale            (GDataService *self);
    void                gdata_service_set_locale            (GDataService *self,
                                                             const gchar *locale);

## Object Hierarchy

      GObject
       +----GDataService
             +----GDataCalendarService
             +----GDataContactsService
             +----GDataDocumentsService
             +----GDataPicasaWebService
             +----GDataYouTubeService

## Known Derived Interfaces

GDataService is required by GDataBatchable.

## Properties

      "authenticated"            gboolean              : Read
      "client-id"                gchar*                : Read / Write / Construct Only
      "locale"                   gchar*                : Read / Write
      "password"                 gchar*                : Read
      "proxy-uri"                SoupURI*              : Read / Write
      "timeout"                  guint                 : Read / Write
      "username"                 gchar*                : Read

## Signals

      "captcha-challenge"                              : Run Last

## Description

GDataService represents a GData API service, typically a website using the GData API, such as YouTube or Google Calendar. One GDataService instance is required to issue queries to the service, handle insertions, updates and deletions, and generally communicate with the online service.

Example 1. Authenticating Asynchronously

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    GDataSomeService *service;

    /* Create a service object and authenticate with the service's server asynchronously */
    service = gdata_some_service_new ("companyName-applicationName-versionID");
    gdata_service_authenticate_async (GDATA_SERVICE (service), username, password, cancellable, (GAsyncReadyCallback) authenticate_cb, user_data);

    static void
    authenticate_cb (GDataSomeService *service, GAsyncResult *async_result, gpointer user_data)
    {
        GError *error = NULL;

        if (gdata_service_authenticate_finish (GDATA_SERVICE (service), async_result, &error) == FALSE) {
            /* Notify the user of all errors except cancellation errors */
            if (!g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
                g_error ("Authentication failed: %s", error->message);
            g_error_free (error);
            return;
        }

        /* (The client is now authenticated. It can now proceed to execute queries on the service object which require the user
         * to be authenticated. */
    }

    g_object_unref (service);

## Details

### GDataService

    typedef struct _GDataService GDataService;

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

### GDataServiceClass

    typedef struct {
    	GObjectClass parent;

    	const gchar *service_name;
    	const gchar *authentication_uri;
    	const gchar *api_version;
    	GType feed_type;

    	gboolean (*parse_authentication_response) (GDataService *self, guint status, const gchar *response_body, gint length, GError **error);
    	void (*append_query_headers) (GDataService *self, SoupMessage *message);
    	void (*parse_error_response) (GDataService *self, GDataOperationType operation_type, guint status, const gchar *reason_phrase,
    	                              const gchar *response_body, gint length, GError **error);
    } GDataServiceClass;

The class structure for the GDataService type.

GObjectClass `parent`; | the parent class
const gchar *`service_name`; | the name of the service (for subclasses) as given in the service's GData API documentation
const gchar *`authentication_uri`; | the authentication URI (for subclasses) if different from the Google ClientLogin default
const gchar *`api_version`; | the version of the GData API used by the service (typically `2`)
GType `feed_type`; | the GType of the feed class (subclass of GDataFeed) to use for query results from this service
`parse_authentication_response` () | a function to parse the response from the online service to an authentication request as issued by `gdata_service_authenticate()`. It should return `TRUE` if authentication was successful, and `FALSE` if there was an error.
`append_query_headers` () | a function to allow subclasses to append their own headers to queries before they are submitted to the online service
`parse_error_response` () | a function to parse error responses to queries from the online service. It should set the error from the status, reason phrase and response body it is passed.

### enum GDataServiceError

    typedef enum {
    	GDATA_SERVICE_ERROR_UNAVAILABLE = 1,
    	GDATA_SERVICE_ERROR_PROTOCOL_ERROR,
    	GDATA_SERVICE_ERROR_ENTRY_ALREADY_INSERTED,
    	GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED,
    	GDATA_SERVICE_ERROR_NOT_FOUND,
    	GDATA_SERVICE_ERROR_CONFLICT,
    	GDATA_SERVICE_ERROR_FORBIDDEN,
    	GDATA_SERVICE_ERROR_BAD_QUERY_PARAMETER,
    	GDATA_SERVICE_ERROR_NETWORK_ERROR,
    	GDATA_SERVICE_ERROR_PROXY_ERROR,
    	GDATA_SERVICE_ERROR_WITH_BATCH_OPERATION
    } GDataServiceError;

Error codes for GDataService operations.

`GDATA_SERVICE_ERROR_UNAVAILABLE` | The service is unavailable due to maintainence or other reasons (e.g. network errors at the server end)
`GDATA_SERVICE_ERROR_PROTOCOL_ERROR` | The client or server unexpectedly strayed from the protocol (fatal error)
`GDATA_SERVICE_ERROR_ENTRY_ALREADY_INSERTED` | An entry has already been inserted, and cannot be re-inserted
`GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED` | The user attempted to do something which required authentication, and they weren't authenticated
`GDATA_SERVICE_ERROR_NOT_FOUND` | A requested resource (feed or entry) was not found on the server
`GDATA_SERVICE_ERROR_CONFLICT` | There was a conflict when updating an entry on the server; the server-side copy was modified inbetween downloading and uploading the modified entry
`GDATA_SERVICE_ERROR_FORBIDDEN` | Generic error for a forbidden action (not due to having insufficient permissions)
`GDATA_SERVICE_ERROR_BAD_QUERY_PARAMETER` | A given query parameter was invalid for the query type
`GDATA_SERVICE_ERROR_NETWORK_ERROR` | The service is unavailable due to local network errors (e.g. no Internet connection)
`GDATA_SERVICE_ERROR_PROXY_ERROR` | The service is unavailable due to proxy network errors (e.g. proxy unreachable)
`GDATA_SERVICE_ERROR_WITH_BATCH_OPERATION` | Generic error when running a batch operation and the whole operation fails

### enum GDataAuthenticationError

    typedef enum {
    	GDATA_AUTHENTICATION_ERROR_BAD_AUTHENTICATION = 1,
    	GDATA_AUTHENTICATION_ERROR_NOT_VERIFIED,
    	GDATA_AUTHENTICATION_ERROR_TERMS_NOT_AGREED,
    	GDATA_AUTHENTICATION_ERROR_CAPTCHA_REQUIRED,
    	GDATA_AUTHENTICATION_ERROR_ACCOUNT_DELETED,
    	GDATA_AUTHENTICATION_ERROR_ACCOUNT_DISABLED,
    	GDATA_AUTHENTICATION_ERROR_SERVICE_DISABLED,
    	GDATA_AUTHENTICATION_ERROR_ACCOUNT_MIGRATED
    } GDataAuthenticationError;

Error codes for GDataService authentication operations. See the Google accounts documentation for more information.

`GDATA_AUTHENTICATION_ERROR_BAD_AUTHENTICATION` | The login request used a username or password that is not recognized.
`GDATA_AUTHENTICATION_ERROR_NOT_VERIFIED` | The account email address has not been verified. The user will need to access their Google account directly to resolve the issue before logging in using a non-Google application.
`GDATA_AUTHENTICATION_ERROR_TERMS_NOT_AGREED` | The user has not agreed to terms. The user will need to access their Google account directly to resolve the issue before logging in using a non-Google application.
`GDATA_AUTHENTICATION_ERROR_CAPTCHA_REQUIRED` | A CAPTCHA is required. (A response with this error code will also contain an image URI and a CAPTCHA token.)
`GDATA_AUTHENTICATION_ERROR_ACCOUNT_DELETED` | The user account has been deleted.
`GDATA_AUTHENTICATION_ERROR_ACCOUNT_DISABLED` | The user account has been disabled.
`GDATA_AUTHENTICATION_ERROR_SERVICE_DISABLED` | The user's access to the specified service has been disabled. (The user account may still be valid.)
`GDATA_AUTHENTICATION_ERROR_ACCOUNT_MIGRATED` | The user's account login details have been migrated to a new system. (This is used for the transition from the old YouTube login details to the new ones.)

### enum GDataParserError

    typedef enum {
    	GDATA_PARSER_ERROR_PARSING_STRING = 1,
    	GDATA_PARSER_ERROR_EMPTY_DOCUMENT
    } GDataParserError;

Error codes for XML parsing operations.

`GDATA_PARSER_ERROR_PARSING_STRING` | Error parsing the XML syntax itself
`GDATA_PARSER_ERROR_EMPTY_DOCUMENT` | Empty document

### enum GDataOperationType

    typedef enum {
    	GDATA_OPERATION_QUERY = 1,
    	GDATA_OPERATION_INSERTION,
    	GDATA_OPERATION_UPDATE,
    	GDATA_OPERATION_DELETION,
    	GDATA_OPERATION_DOWNLOAD,
    	GDATA_OPERATION_UPLOAD,
    	GDATA_OPERATION_AUTHENTICATION,
    	GDATA_OPERATION_BATCH
    } GDataOperationType;

Representations of the different operations performed by the library.

`GDATA_OPERATION_QUERY` | a query
`GDATA_OPERATION_INSERTION` | an insertion of a GDataEntry
`GDATA_OPERATION_UPDATE` | an update of a GDataEntry
`GDATA_OPERATION_DELETION` | a deletion of a GDataEntry
`GDATA_OPERATION_DOWNLOAD` | a download of a file
`GDATA_OPERATION_UPLOAD` | an upload of a file
`GDATA_OPERATION_AUTHENTICATION` | authentication with the service
`GDATA_OPERATION_BATCH` | a batch operation with GDataBatchOperation

Since 0.6.0

### GDataQueryProgressCallback ()

    void                (*GDataQueryProgressCallback)       (GDataEntry *entry,
                                                             guint entry_key,
                                                             guint entry_count,
                                                             gpointer user_data);

Callback function called for each GDataEntry parsed in a GDataFeed when loading the results of a query.

It is called in the main thread, so there is no guarantee on the order in which the callbacks are executed, or whether they will be called in a timely manner. It is, however, guaranteed that they will all be called before the GAsyncReadyCallback which signals the completion of the query is called.

`entry` : | a new GDataEntry
`entry_key` : | the key of the entry (zero-based index of its position in the feed)
`entry_count` : | the total number of entries in the feed
`user_data` : | user data passed to the callback

### gdata_service_authenticate ()

    gboolean            gdata_service_authenticate          (GDataService *self,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GError **error);

Authenticates the GDataService with the online service using `username` and `password`; i.e. logs into the service with the given user account. `username` should be a full e-mail address (e.g. `john.smith@gmail.com`). If a full e-mail address is not given, `username` will have `@gmail.com` appended to create an e-mail address

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned.

A `GDATA_AUTHENTICATION_ERROR_BAD_AUTHENTICATION` will be returned if authentication failed due to an incorrect username or password. Other GDataAuthenticationError errors can be returned for other conditions.

If the service requires a CAPTCHA to be completed, the "captcha-challenge" signal will be emitted. The return value from a signal handler for the signal should be a newly allocated string containing the text from the image. If the text is `NULL` or empty, authentication will fail with a `GDATA_AUTHENTICATION_ERROR_CAPTCHA_REQUIRED` error. Otherwise, authentication will be automatically and transparently restarted with the new CAPTCHA details.

A `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` will be returned if the server's responses were invalid. Subclasses of GDataService can override parsing the authentication response, and may return their own error codes. See their documentation for more details.

`self` : | a GDataService
`username` : | the user's username
`password` : | the user's password
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | `TRUE` if authentication was successful, `FALSE` otherwise

### gdata_service_authenticate_async ()

    void                gdata_service_authenticate_async    (GDataService *self,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Authenticates the GDataService with the online service using the given `username` and `password`. `self`, `username` and `password` are all reffed/copied when this function is called, so can safely be freed after this function returns.

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

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

`self` : | a GDataService
`username` : | the user's username
`password` : | the user's password
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when authentication is finished
`user_data` : | data to pass to the `callback` function. [closure]

### gdata_service_authenticate_finish ()

    gboolean            gdata_service_authenticate_finish   (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);

Finishes an asynchronous authentication operation started with `gdata_service_authenticate_async()`.

`self` : | a GDataService
`async_result` : | a GAsyncResult
`error` : | a GError, or `NULL`
Returns : | `TRUE` if authentication was successful, `FALSE` otherwise

### gdata_service_is_authenticated ()

    gboolean            gdata_service_is_authenticated      (GDataService *self);

Returns whether a user is authenticated with the online service through `self`. Authentication is performed by calling `gdata_service_authenticate()` or `gdata_service_authenticate_async()`.

`self` : | a GDataService
Returns : | `TRUE` if a user is authenticated, `FALSE` otherwise

### gdata_service_query ()

    GDataFeed *         gdata_service_query                 (GDataService *self,
                                                             const gchar *feed_uri,
                                                             GDataQuery *query,
                                                             GType entry_type,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);

Queries the service's `feed_uri` feed to build a GDataFeed.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled before or during network activity, the error `G_IO_ERROR_CANCELLED` will be returned. Cancellation has no effect after network activity has finished, however, and the query will return successfully (or return an error sent by the server) if it is first cancelled after network activity has finished. See the overview of cancellation for more details.

A `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` will be returned if the server indicates there is a problem with the query, but subclasses may override this and return their own errors. See their documentation for more details.

For each entry in the response feed, `progress_callback` will be called in the main thread. If there was an error parsing the XML response, a GDataParserError will be returned.

If the query is successful and the feed supports pagination, `query` will be updated with the pagination URIs, and the next or previous page can then be loaded by calling `gdata_query_next_page()` or `gdata_query_previous_page()` before running the query again.

If the GDataQuery's ETag is set and it finds a match on the server, `NULL` will be returned, but `error` will remain unset. Otherwise, `query`'s ETag will be updated with the ETag from the returned feed, if available.

`self` : | a GDataService
`feed_uri` : | the feed URI to query, including the host name and protocol
`query` : | a GDataQuery with the query parameters, or `NULL`. [allow-none]
`entry_type` : | a GType for the GDataEntrys to build from the XML
`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 GDataFeed of query results, or `NULL`; unref with `g_object_unref()`. [transfer full]

### gdata_service_query_async ()

    void                gdata_service_query_async           (GDataService *self,
                                                             const gchar *feed_uri,
                                                             GDataQuery *query,
                                                             GType entry_type,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Queries the service's `feed_uri` feed to build a GDataFeed. `self`, `feed_uri` and `query` are all reffed/copied when this function is called, so can safely be freed after this function returns.

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

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

`self` : | a GDataService
`feed_uri` : | the feed URI to query, including the host name and protocol
`query` : | a GDataQuery with the query parameters, or `NULL`. [allow-none]
`entry_type` : | a GType for the GDataEntrys to build from the XML
`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. [closure]
`callback` : | a GAsyncReadyCallback to call when the query is finished
`user_data` : | data to pass to the `callback` function. [closure]

### gdata_service_query_finish ()

    GDataFeed *         gdata_service_query_finish          (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);

Finishes an asynchronous query operation started with `gdata_service_query_async()`.

`self` : | a GDataService
`async_result` : | a GAsyncResult
`error` : | a GError, or `NULL`
Returns : | a GDataFeed of query results, or `NULL`; unref with `g_object_unref()`. [transfer full]

### gdata_service_query_single_entry ()

    GDataEntry *        gdata_service_query_single_entry    (GDataService *self,
                                                             const gchar *entry_id,
                                                             GDataQuery *query,
                                                             GType entry_type,
                                                             GCancellable *cancellable,
                                                             GError **error);

Retrieves information about the single entry with the given `entry_id`. `entry_id` should be as returned by `gdata_entry_get_id()`.

Parameters and errors are as for `gdata_service_query()`. Most of the properties of `query` aren't relevant, and will cause a server-side error if used. The most useful property to use is "etag", which will cause the server to not return anything if the entry hasn't been modified since it was given the specified ETag; thus saving bandwidth. If the server does not return anything for this reason, `gdata_service_query_single_entry()` will return `NULL`, but will not set an error in `error`.

`self` : | a GDataService
`entry_id` : | the entry ID of the desired entry
`query` : | a GDataQuery with the query parameters, or `NULL`. [allow-none]
`entry_type` : | a GType for the GDataEntry to build from the XML
`cancellable` : | a GCancellable, or `NULL`
`error` : | a GError, or `NULL`
Returns : | a GDataEntry, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.7.0

### gdata_service_query_single_entry_async ()

    void                gdata_service_query_single_entry_async
                                                            (GDataService *self,
                                                             const gchar *entry_id,
                                                             GDataQuery *query,
                                                             GType entry_type,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Retrieves information about the single entry with the given `entry_id`. `entry_id` should be as returned by `gdata_entry_get_id()`. `self`, `query` and `entry_id` are reffed/copied when this function is called, so can safely be freed after this function returns.

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

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

`self` : | a GDataService
`entry_id` : | the entry ID of the desired entry
`query` : | a GDataQuery with the query parameters, or `NULL`. [allow-none]
`entry_type` : | a GType for the GDataEntry to build from the XML
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the query is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.7.0

### gdata_service_query_single_entry_finish ()

    GDataEntry *        gdata_service_query_single_entry_finish
                                                            (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);

Finishes an asynchronous query operation for a single entry, as started with `gdata_service_query_single_entry_async()`.

`self` : | a GDataService
`async_result` : | a GAsyncResult
`error` : | a GError, or `NULL`
Returns : | a GDataEntry, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.7.0

### gdata_service_insert_entry ()

    GDataEntry *        gdata_service_insert_entry          (GDataService *self,
                                                             const gchar *upload_uri,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GError **error);

Inserts `entry` by uploading it to the online service at `upload_uri`. For more information about the concept of inserting entries, see the online documentation for the GData protocol.

The service will return an updated version of the entry, which is the return value of this function on success.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled before or during network activity, the error `G_IO_ERROR_CANCELLED` will be returned. Cancellation has no effect after network activity has finished, however, and the insertion will return successfully (or return an error sent by the server) if it is first cancelled after network activity has finished. See the overview of cancellation for more details.

If the entry is marked as already having been inserted a `GDATA_SERVICE_ERROR_ENTRY_ALREADY_INSERTED` error will be returned immediately (there will be no network requests).

If there is an error inserting the entry, a `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` error will be returned. Currently, subclasses cannot cannot override this or provide more specific errors.

`self` : | a GDataService
`upload_uri` : | the URI to which the upload should be sent
`entry` : | the GDataEntry to insert
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataEntry, or `NULL`; unref with `g_object_unref()`. [transfer full]

### gdata_service_insert_entry_async ()

    void                gdata_service_insert_entry_async    (GDataService *self,
                                                             const gchar *upload_uri,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Inserts `entry` by uploading it to the online service at `upload_uri`. `self`, `upload_uri` and `entry` are all reffed/copied when this function is called, so can safely be freed after this function returns.

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

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

`self` : | a GDataService
`upload_uri` : | the URI to which the upload should be sent
`entry` : | the GDataEntry to insert
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when insertion is finished, or `NULL`
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.3.0

### gdata_service_insert_entry_finish ()

    GDataEntry *        gdata_service_insert_entry_finish   (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);

Finishes an asynchronous entry insertion operation started with `gdata_service_insert_entry_async()`.

`self` : | a GDataService
`async_result` : | a GAsyncResult
`error` : | a GError, or `NULL`
Returns : | an updated GDataEntry, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.3.0

### gdata_service_update_entry ()

    GDataEntry *        gdata_service_update_entry          (GDataService *self,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GError **error);

Updates `entry` by PUTting it to its `edit` link's URI. For more information about the concept of updating entries, see the online documentation for the GData protocol.

The service will return an updated version of the entry, which is the return value of this function on success.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled before or during network activity, the error `G_IO_ERROR_CANCELLED` will be returned. Cancellation has no effect after network activity has finished, however, and the update will return successfully (or return an error sent by the server) if it is first cancelled after network activity has finished. See the overview of cancellation for more details.

If there is an error updating the entry, a `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` error will be returned. Currently, subclasses cannot cannot override this or provide more specific errors.

`self` : | a GDataService
`entry` : | the GDataEntry to update
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | an updated GDataEntry, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.2.0

### gdata_service_update_entry_async ()

    void                gdata_service_update_entry_async    (GDataService *self,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Updates `entry` by PUTting it to its `edit` link's URI. `self` and `entry` are both reffed when this function is called, so can safely be unreffed after this function returns.

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

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

`self` : | a GDataService
`entry` : | the GDataEntry to update
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the update is finished, or `NULL`
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.3.0

### gdata_service_update_entry_finish ()

    GDataEntry *        gdata_service_update_entry_finish   (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);

Finishes an asynchronous entry update operation started with `gdata_service_update_entry_async()`.

`self` : | a GDataService
`async_result` : | a GAsyncResult
`error` : | a GError, or `NULL`
Returns : | an updated GDataEntry, or `NULL`; unref with `g_object_unref()`. [transfer full]

Since 0.3.0

### gdata_service_delete_entry ()

    gboolean            gdata_service_delete_entry          (GDataService *self,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GError **error);

Deletes `entry` from the server. For more information about the concept of deleting entries, see the online documentation for the GData protocol.

If `cancellable` is not `NULL`, then the operation can be cancelled by triggering the `cancellable` object from another thread. If the operation was cancelled before or during network activity, the error `G_IO_ERROR_CANCELLED` will be returned. Cancellation has no effect after network activity has finished, however, and the deletion will return successfully (or return an error sent by the server) if it is first cancelled after network activity has finished. See the overview of cancellation for more details.

If there is an error deleting the entry, a `GDATA_SERVICE_ERROR_PROTOCOL_ERROR` error will be returned. Currently, subclasses cannot cannot override this or provide more specific errors.

`self` : | a GDataService
`entry` : | the GDataEntry to delete
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

Since 0.2.0

### gdata_service_delete_entry_async ()

    void                gdata_service_delete_entry_async    (GDataService *self,
                                                             GDataEntry *entry,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Deletes `entry` from the server. `self` and `entry` are both reffed when this function is called, so can safely be unreffed after this function returns.

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

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

`self` : | a GDataService
`entry` : | the GDataEntry to delete
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when deletion is finished, or `NULL`
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.3.0

### gdata_service_delete_entry_finish ()

    gboolean            gdata_service_delete_entry_finish   (GDataService *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);

Finishes an asynchronous entry deletion operation started with `gdata_service_delete_entry_async()`.

`self` : | a GDataService
`async_result` : | a GAsyncResult
`error` : | a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

Since 0.3.0

### gdata_service_get_client_id ()

    const gchar *       gdata_service_get_client_id         (GDataService *self);

Returns the service's client ID, as specified on constructing the GDataService.

`self` : | a GDataService
Returns : | the service's client ID

### gdata_service_get_username ()

    const gchar *       gdata_service_get_username          (GDataService *self);

Returns the username of the currently-authenticated user, or `NULL` if nobody is authenticated.

It is not safe to call this while an authentication operation is ongoing.

`self` : | a GDataService
Returns : | the username of the currently-authenticated user, or `NULL`

### gdata_service_get_password ()

    const gchar *       gdata_service_get_password          (GDataService *self);

Returns the password of the currently-authenticated user, or `NULL` if nobody is authenticated.

It is not safe to call this while an authentication operation is ongoing.

`self` : | a GDataService
Returns : | the password of the currently-authenticated user, or `NULL`

### gdata_service_get_proxy_uri ()

    SoupURI *           gdata_service_get_proxy_uri         (GDataService *self);

Gets the proxy URI on the GDataService's SoupSession.

`self` : | a GDataService
Returns : | the proxy URI, or `NULL`. [transfer none]

Since 0.2.0

### gdata_service_set_proxy_uri ()

    void                gdata_service_set_proxy_uri         (GDataService *self,
                                                             SoupURI *proxy_uri);

Sets the proxy URI on the SoupSession used internally by the given GDataService. This forces all requests through the given proxy.

If `proxy_uri` is `NULL`, no proxy will be used.

`self` : | a GDataService
`proxy_uri` : | the proxy URI, or `NULL`. [allow-none]

Since 0.2.0

### gdata_service_get_timeout ()

    guint               gdata_service_get_timeout           (GDataService *self);

Gets the "timeout" property; the network timeout, in seconds.

`self` : | a GDataService
Returns : | the timeout, or `0`

Since 0.7.0

### gdata_service_set_timeout ()

    void                gdata_service_set_timeout           (GDataService *self,
                                                             guint timeout);

Sets the "timeout" property; the network timeout, in seconds.

If `timeout` is `0`, network operations will never time out.

`self` : | a GDataService
`timeout` : | the timeout, or `0`

Since 0.7.0

### gdata_service_get_locale ()

    const gchar *       gdata_service_get_locale            (GDataService *self);

Returns the locale currently being used for network requests, or `NULL` if the locale is the default.

`self` : | a GDataService
Returns : | the current locale

Since 0.7.0

### gdata_service_set_locale ()

    void                gdata_service_set_locale            (GDataService *self,
                                                             const gchar *locale);

Set the locale used for network requests to `locale`, given in standard Unix locale format. See "locale" for more details.

Note that while it's possible to change the locale after sending network requests, it is unsupported, as the server-side software may behave unexpectedly. The only supported use of this function is after creation of a service, but before any network requests are made.

`self` : | a GDataService
`locale` : | the new locale in Unix locale format, or `NULL` for the default locale. [allow-none]

Since 0.7.0

## Property Details

### The `"authenticated"` property

      "authenticated"            gboolean              : Read

Whether the user is authenticated (logged in) with the service.

Default value: FALSE

### The `"client-id"` property

      "client-id"                gchar*                : Read / Write / Construct Only

A client ID for your application (see the reference documentation).

It is recommended that the ID is of the form ``company name`-`application name`- `version ID``.

Default value: NULL

### The `"locale"` property

      "locale"                   gchar*                : Read / Write

The locale to use for network requests, in Unix locale format. (e.g. "en_GB", "cs", "de_DE".) Use `NULL` for the default "C" locale (typically "en_US").

Typically, this locale will be used by the server-side software to localise results, such as by translating category names, or by choosing geographically relevant search results. This will vary from service to service.

The server-side behaviour is undefined if it doesn't support a given locale.

Default value: NULL

Since 0.7.0

### The `"password"` property

      "password"                 gchar*                : Read

The user's account password for authentication.

Default value: NULL

### The `"proxy-uri"` property

      "proxy-uri"                SoupURI*              : Read / Write

The proxy URI used internally for all network requests.

Since 0.2.0

### The `"timeout"` property

      "timeout"                  guint                 : Read / Write

A timeout, in seconds, for network operations. If the timeout is exceeded, the operation will be cancelled and `GDATA_SERVICE_ERROR_NETWORK_ERROR` will be returned.

If the timeout is `0`, operations will never time out.

Default value: 0

Since 0.7.0

### The `"username"` property

      "username"                 gchar*                : Read

The user's Google username for authentication. This will always be a full e-mail address.

Default value: NULL

## Signal Details

### The `"captcha-challenge"` signal

    gchar*              user_function                      (GDataService *service,
                                                            gchar        *uri,
                                                            gpointer      user_data)      : Run Last

The "captcha-challenge" signal is emitted during the authentication process if the service requires a CAPTCHA to be completed. The URI of a CAPTCHA image is given, and the program should display this to the user, and return their response (the text displayed in the image). There is no timeout imposed by the library for the response.

`service` : | the GDataService which received the challenge
`uri` : | the URI of the CAPTCHA image to be used
`user_data` : | user data set when the signal handler was connected.
Returns : | a newly allocated string containing the text in the CAPTCHA image