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.

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.

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.

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.

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.

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.

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.

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

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 .

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.

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

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.

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.

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

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.

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.

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

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

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.

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.

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

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.

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.

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.

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.

Since: 0.15.0

gdata_service_get_timeout ()

guint
gdata_service_get_timeout (GDataService *self);

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

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.

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.

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.

Since: 0.7.0

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.

Since: 0.9.0

enum GDataServiceError

Error codes for GDataService operations.

enum GDataParserError

Error codes for XML or JSON parsing operations.

enum GDataOperationType

Representations of the different operations performed by the library.

Since: 0.6.0

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.

Flags: Read / Write

Since: 0.9.0

The “locale” property

  “locale”                   gchar *

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.

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.

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.

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.

Flags: Read / Write

Default value: 0

Since: 0.7.0