GDataService

GDataService — GData service object

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <gdata/gdata-service.h>

                    GDataService;
                    GDataServiceClass;
enum                GDataServiceError;
enum                GDataParserError;
enum                GDataOperationType;
void                (*GDataQueryProgressCallback)       (GDataEntry *entry,
                                                         guint entry_key,
                                                         guint entry_count,
                                                         gpointer user_data);
gboolean            gdata_service_is_authorized         (GDataService *self);
GDataAuthorizer *   gdata_service_get_authorizer        (GDataService *self);
void                gdata_service_set_authorizer        (GDataService *self,
                                                         GDataAuthorizer *authorizer);
GList *             gdata_service_get_authorization_domains
                                                        (GType service_type);
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);
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,
                                                         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,
                                                         GDataAuthorizationDomain *domain,
                                                         const gchar *entry_id,
                                                         GDataQuery *query,
                                                         GType entry_type,
                                                         GCancellable *cancellable,
                                                         GError **error);
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);
GDataEntry *        gdata_service_query_single_entry_finish
                                                        (GDataService *self,
                                                         GAsyncResult *async_result,
                                                         GError **error);
GDataEntry *        gdata_service_insert_entry          (GDataService *self,
                                                         GDataAuthorizationDomain *domain,
                                                         const gchar *upload_uri,
                                                         GDataEntry *entry,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                gdata_service_insert_entry_async    (GDataService *self,
                                                         GDataAuthorizationDomain *domain,
                                                         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,
                                                         GDataAuthorizationDomain *domain,
                                                         GDataEntry *entry,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                gdata_service_update_entry_async    (GDataService *self,
                                                         GDataAuthorizationDomain *domain,
                                                         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,
                                                         GDataAuthorizationDomain *domain,
                                                         GDataEntry *entry,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                gdata_service_delete_entry_async    (GDataService *self,
                                                         GDataAuthorizationDomain *domain,
                                                         GDataEntry *entry,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            gdata_service_delete_entry_finish   (GDataService *self,
                                                         GAsyncResult *async_result,
                                                         GError **error);
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

  "authorizer"               GDataAuthorizer*      : Read / Write
  "locale"                   gchar*                : Read / Write
  "proxy-uri"                SoupURI*              : Read / Write
  "timeout"                  guint                 : Read / Write

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.

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 *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);
} GDataServiceClass;

The class structure for the GDataService type.

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

Since 0.9.0


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

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.

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.

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.

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.

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

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]

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

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.

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

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.

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.

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

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.

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.

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

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.

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.

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

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

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.

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

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.

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

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 "authorizer" property

  "authorizer"               GDataAuthorizer*      : Read / Write

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.

Since 0.9.0


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 "proxy-uri" property

  "proxy-uri"                SoupURI*              : Read / Write

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.

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.

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

Default value: 0

Since 0.7.0