GDataService: GData Reference Manual

## GDataService GDataService — GData service object |

## Stability Level

Stable, unless otherwise indicated

## Functions

void | (*GDataQueryProgressCallback) ()
gboolean | gdata_service_is_authorized ()
GDataAuthorizer * | gdata_service_get_authorizer ()
void | gdata_service_set_authorizer ()
GList * | gdata_service_get_authorization_domains ()
GDataFeed * | gdata_service_query ()
void | gdata_service_query_async ()
GDataFeed * | gdata_service_query_finish ()
GDataEntry * | gdata_service_query_single_entry ()
void | gdata_service_query_single_entry_async ()
GDataEntry * | gdata_service_query_single_entry_finish ()
GDataEntry * | gdata_service_insert_entry ()
void | gdata_service_insert_entry_async ()
GDataEntry * | gdata_service_insert_entry_finish ()
GDataEntry * | gdata_service_update_entry ()
void | gdata_service_update_entry_async ()
GDataEntry * | gdata_service_update_entry_finish ()
gboolean | gdata_service_delete_entry ()
void | gdata_service_delete_entry_async ()
gboolean | gdata_service_delete_entry_finish ()
SoupURI * | gdata_service_get_proxy_uri ()
void | gdata_service_set_proxy_uri ()
GProxyResolver * | gdata_service_get_proxy_resolver ()
void | gdata_service_set_proxy_resolver ()
guint | gdata_service_get_timeout ()
void | gdata_service_set_timeout ()
const gchar * | gdata_service_get_locale ()
void | gdata_service_set_locale ()

## Properties

GDataAuthorizer * | authorizer | Read / Write
char * | locale | Read / Write
GProxyResolver * | proxy-resolver | Read / Write
SoupURI * | proxy-uri | Read / Write
guint | timeout | Read / Write

## Types and Values

| GDataService
| GDataServiceClass
enum | GDataServiceError
enum | GDataParserError
enum | GDataOperationType

## Object Hierarchy

        GObject
        ╰── GDataService
            ├── GDataCalendarService
            ├── GDataContactsService
            ├── GDataDocumentsService
            ├── GDataFreebaseService
            ├── GDataPicasaWebService
            ├── GDataTasksService
            ╰── GDataYouTubeService

## Known Derived Interfaces

GDataService is required by GDataBatchable.

## Includes

    #include <gdata/gdata-service.h>

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

If operations performed on a GDataService need authorization (such as uploading a video to YouTube or querying the user's personal calendar on Google Calendar), the service needs a GDataAuthorizer instance set as “authorizer”. Once the user is appropriately authenticated and authorized by the GDataAuthorizer implementation (see the documentation for GDataAuthorizer for details on how this is achieved for specific implementations), all operations will be automatically authorized.

Note that it's not always necessary to supply a GDataAuthorizer instance to a GDataService. If the only operations to be performed on the GDataService don't need authorization (e.g. they only query public information), setting up a GDataAuthorizer is just extra overhead. See the documentation for the operations on individual GDataService subclasses to see which need authorization and which don't.

## Functions

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

#### Parameters

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_is_authorized ()

    gboolean
    gdata_service_is_authorized (GDataService *self);

Determines whether the service is authorized for all the GDataAuthorizationDomains it belongs to (as returned by `gdata_service_get_authorization_domains()`). If the service's “authorizer” is `NULL`, `FALSE` is always returned.

This is basically a convenience method for checking that the service's GDataAuthorizer is authorized for all the service's GDataAuthorizationDomains.

#### Parameters

self | a GDataService |

#### Returns

`TRUE` if the service is authorized for all its domains, `FALSE` otherwise

Since: 0.9.0

### gdata_service_get_authorizer ()

    GDataAuthorizer *
    gdata_service_get_authorizer (GDataService *self);

Gets the GDataAuthorizer object currently in use by the service. See the documentation for “authorizer” for more details.

#### Parameters

self | a GDataService |

#### Returns

the authorizer object for this service, or `NULL`.

[transfer none]

Since: 0.9.0

### gdata_service_set_authorizer ()

    void
    gdata_service_set_authorizer (GDataService *self,
                                  GDataAuthorizer *authorizer);

Sets “authorizer” to `authorizer` . This may be `NULL` if the service will only make requests in future which don't require authorization. See the documentation for “authorizer” for more information.

#### Parameters

self | a GDataService |
authorizer | a new authorizer object for the service, or `NULL` |

Since: 0.9.0

### gdata_service_get_authorization_domains ()

    GList *
    gdata_service_get_authorization_domains
                                   (GType service_type);

Retrieves the full list of GDataAuthorizationDomains which relate to the specified `service_type` . All the GDataAuthorizationDomains are unique and interned, so can be compared with other domains by simple pointer comparison.

Note that in addition to this method, GDataService subclasses may expose some or all of their authorization domains individually by means of individual accessor functions.

#### Parameters

service_type | the GType of the GDataService subclass to retrieve the authorization domains for |

#### Returns

an unordered list of GDataAuthorizationDomains; free with `g_list_free()`.

[transfer container][element-type GDataAuthorizationDomain]

Since: 0.9.0

### gdata_service_query ()

    GDataFeed *
    gdata_service_query (GDataService *self,
                         GDataAuthorizationDomain *domain,
                         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.

#### Parameters

self | a GDataService |
domain | the GDataAuthorizationDomain the query falls under, or `NULL`. | [allow-none]
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`. | [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 GDataFeed of query results, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.9.0

### gdata_service_query_async ()

    void
    gdata_service_query_async (GDataService *self,
                               GDataAuthorizationDomain *domain,
                               const gchar *feed_uri,
                               GDataQuery *query,
                               GType entry_type,
                               GCancellable *cancellable,
                               GDataQueryProgressCallback progress_callback,
                               gpointer progress_user_data,
                               GDestroyNotify destroy_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.

#### Parameters

self | a GDataService |
domain | the GDataAuthorizationDomain the query falls under, or `NULL`. | [allow-none]
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`. | [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 the query is finished |
user_data | data to pass to the `callback` function. | [closure]

Since: 0.9.1

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

#### Parameters

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,
                                      GDataAuthorizationDomain *domain,
                                      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` .

#### Parameters

self | a GDataService |
domain | the GDataAuthorizationDomain the query falls under, or `NULL`. | [allow-none]
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`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

a GDataEntry, or `NULL`; unref with `g_object_unref()`.

[transfer full]

Since: 0.9.0

### gdata_service_query_single_entry_async ()

    void
    gdata_service_query_single_entry_async
                                   (GDataService *self,
                                    GDataAuthorizationDomain *domain,
                                    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.

#### Parameters

self | a GDataService |
domain | the GDataAuthorizationDomain the query falls under, or `NULL`. | [allow-none]
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`. | [allow-none]
callback | a GAsyncReadyCallback to call when the query is finished |
user_data | data to pass to the `callback` function. | [closure]

Since: 0.9.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()`.

#### Parameters

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,
                                GDataAuthorizationDomain *domain,
                                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.

#### Parameters

self | a GDataService |
domain | the GDataAuthorizationDomain the insertion operation falls under, or `NULL`. | [allow-none]
upload_uri | the URI to which the upload should be sent |
entry | the GDataEntry to insert |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

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

[transfer full]

Since: 0.9.0

### gdata_service_insert_entry_async ()

    void
    gdata_service_insert_entry_async (GDataService *self,
                                      GDataAuthorizationDomain *domain,
                                      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.

#### Parameters

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

Since: 0.9.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()`.

#### Parameters

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,
                                GDataAuthorizationDomain *domain,
                                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.

#### Parameters

self | a GDataService |
domain | the GDataAuthorizationDomain the update operation falls under, or `NULL`. | [allow-none]
entry | the GDataEntry to update |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

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

[transfer full]

Since: 0.9.0

### gdata_service_update_entry_async ()

    void
    gdata_service_update_entry_async (GDataService *self,
                                      GDataAuthorizationDomain *domain,
                                      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.

#### Parameters

self | a GDataService |
domain | the GDataAuthorizationDomain the update operation falls under, or `NULL`. | [allow-none]
entry | the GDataEntry to update |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
callback | a GAsyncReadyCallback to call when the update is finished, or `NULL` |
user_data | data to pass to the `callback` function. | [closure]

Since: 0.9.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()`.

#### Parameters

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,
                                GDataAuthorizationDomain *domain,
                                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.

#### Parameters

self | a GDataService |
domain | the GDataAuthorizationDomain the deletion falls under, or `NULL`. | [allow-none]
entry | the GDataEntry to delete |
cancellable | optional GCancellable object, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` otherwise

Since: 0.9.0

### gdata_service_delete_entry_async ()

    void
    gdata_service_delete_entry_async (GDataService *self,
                                      GDataAuthorizationDomain *domain,
                                      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.

#### Parameters

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

Since: 0.9.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()`.

#### Parameters

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_proxy_uri ()

    SoupURI *
    gdata_service_get_proxy_uri (GDataService *self);

`gdata_service_get_proxy_uri` has been deprecated since version 0.15.0 and should not be used in newly-written code.

Use `gdata_service_get_proxy_resolver()` instead, which gives more flexibility over the proxy used.

Gets the proxy URI on the GDataService's SoupSession.

#### Parameters

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);

`gdata_service_set_proxy_uri` has been deprecated since version 0.15.0 and should not be used in newly-written code.

Use `gdata_service_set_proxy_resolver()` instead, which gives more flexibility over the proxy used.

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.

Note that if a GDataAuthorizer is being used with this GDataService, the authorizer might also need its proxy URI setting.

#### Parameters

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

Since: 0.2.0

### gdata_service_get_proxy_resolver ()

    GProxyResolver *
    gdata_service_get_proxy_resolver (GDataService *self);

Gets the GProxyResolver on the GDataService's SoupSession.

#### Parameters

self | a GDataService |

#### Returns

a GProxyResolver, or `NULL`.

[transfer none][allow-none]

Since: 0.15.0

### gdata_service_set_proxy_resolver ()

    void
    gdata_service_set_proxy_resolver (GDataService *self,
                                      GProxyResolver *proxy_resolver);

Sets the GProxyResolver on the SoupSession used internally by the given GDataService.

Setting this will clear the “proxy-uri” property.

#### Parameters

self | a GDataService |
proxy_resolver | a GProxyResolver, or `NULL`. | [allow-none]

Since: 0.15.0

### gdata_service_get_timeout ()

    guint
    gdata_service_get_timeout (GDataService *self);

Gets the “timeout” property; the network timeout, in seconds.

#### Parameters

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.

Note that if a GDataAuthorizer is being used with this GDataService, the authorizer might also need its timeout setting.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

Since: 0.7.0

## Types and Values

### 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 *api_version;
    	GType feed_type;

    	void (*append_query_headers) (GDataService *self, GDataAuthorizationDomain *domain, 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);
    	GList *(*get_authorization_domains) (void);
    	GDataFeed *(*parse_feed) (GDataService *self,
    	                          GDataAuthorizationDomain *domain,
    	                          GDataQuery *query,
    	                          GType entry_type,
    	                          SoupMessage *message,
    	                          GCancellable *cancellable,
    	                          GDataQueryProgressCallback progress_callback,
    	                          gpointer progress_user_data,
    	                          GError **error);
    } GDataServiceClass;

The class structure for the GDataService type.

#### Members

GObjectClass `parent`; | the parent class |
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 |
`append_query_headers` () | a function to allow subclasses to append their own headers to queries before they are submitted to the online service, using the given authorization domain; new in version 0.9.0 |
`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. |
`get_authorization_domains` () | a function to return a newly-allocated list of all the GDataAuthorizationDomains the service makes use of; while the list should be newly-allocated, the individual domains should not be; not implementing this function is equivalent to returning an empty list; new in version 0.9.0 |
`parse_feed` () | a function to parse feed responses to queries from the online service; new in version 0.17.0 |

Since: 0.9.0

### enum GDataServiceError

Error codes for GDataService operations.

#### Members

GDATA_SERVICE_ERROR_UNAVAILABLE | The service is unavailable due to maintenance 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 or didn't have authorization for the operation |
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 between 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 |
GDATA_SERVICE_ERROR_API_QUOTA_EXCEEDED | The API request quota for this developer account has been exceeded for the current time period (e.g. day). Try again later. (Since: 0.16.0.) |

### enum GDataParserError

Error codes for XML or JSON parsing operations.

#### Members

GDATA_PARSER_ERROR_PARSING_STRING | Error parsing the XML or JSON syntax itself |
GDATA_PARSER_ERROR_EMPTY_DOCUMENT | Empty document |

### enum GDataOperationType

Representations of the different operations performed by the library.

#### Members

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

## Property Details

### The `“authorizer”` property

      “authorizer”               GDataAuthorizer *

An object which implements GDataAuthorizer. This should have previously been authenticated authorized against this service type (and potentially other service types). The service will use the authorizer to add an authorization token to each request it performs.

Your application should call methods on the GDataAuthorizer object itself in order to authenticate with the Google accounts service and authorize against this service type. See the documentation for the particular GDataAuthorizer implementation being used for more details.

The authorizer for a service can be changed at runtime for a different GDataAuthorizer object or `NULL` without affecting ongoing requests and operations.

Note that it's only necessary to set an authorizer on the service if your application is going to make requests of the service which require authorization. For example, listing the current most popular videos on YouTube does not require authorization, but uploading a video to YouTube does. It's an unnecessary overhead to require the user to authorize against a service when not strictly required.

Owner: GDataService

Flags: Read / Write

Since: 0.9.0

### The `“locale”` property

      “locale”                   char *

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.

Owner: GDataService

Flags: Read / Write

Default value: NULL

Since: 0.7.0

### The `“proxy-resolver”` property

      “proxy-resolver”           GProxyResolver *

The GProxyResolver used to determine a proxy URI. Setting this will clear the “proxy-uri” property.

Owner: GDataService

Flags: Read / Write

Since: 0.15.0

### The `“proxy-uri”` property

      “proxy-uri”                SoupURI *

The proxy URI used internally for all network requests.

Note that if a GDataAuthorizer is being used with this GDataService, the authorizer might also need its proxy URI setting.

`GDataService:proxy-uri` has been deprecated since version 0.15.0 and should not be used in newly-written code.

Use “proxy-resolver” instead, which gives more flexibility over the proxy used.

Owner: GDataService

Flags: Read / Write

Since: 0.2.0

### The `“timeout”` property

      “timeout”                  guint

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.

Note that if a GDataAuthorizer is being used with this GDataService, the authorizer might also need its timeout setting.

Owner: GDataService

Flags: Read / Write

Default value: 0

Since: 0.7.0