![]() |
![]() |
![]() |
GData Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#include <gdata/gdata-service.h> GDataService; GDataServiceClass; enum GDataServiceError; enum GDataAuthenticationError; enum GDataParserError; void (*GDataQueryProgressCallback) (GDataEntry *entry, guint entry_key, guint entry_count, gpointer user_data); gboolean gdata_service_authenticate (GDataService *self, const gchar *username, const gchar *password, GCancellable *cancellable, GError **error); void gdata_service_authenticate_async (GDataService *self, const gchar *username, const gchar *password, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean gdata_service_authenticate_finish (GDataService *self, GAsyncResult *async_result, GError **error); gboolean gdata_service_is_authenticated (GDataService *self); GDataFeed * gdata_service_query (GDataService *self, const gchar *feed_uri, GDataQuery *query, GType entry_type, GCancellable *cancellable, GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GError **error); void gdata_service_query_async (GDataService *self, const gchar *feed_uri, GDataQuery *query, GType entry_type, GCancellable *cancellable, GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GAsyncReadyCallback callback, gpointer user_data); GDataFeed * gdata_service_query_finish (GDataService *self, GAsyncResult *async_result, GError **error); GDataEntry * gdata_service_insert_entry (GDataService *self, const gchar *upload_uri, GDataEntry *entry, GCancellable *cancellable, GError **error); void gdata_service_insert_entry_async (GDataService *self, const gchar *upload_uri, GDataEntry *entry, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); GDataEntry * gdata_service_insert_entry_finish (GDataService *self, GAsyncResult *async_result, GError **error); GDataEntry * gdata_service_update_entry (GDataService *self, GDataEntry *entry, GCancellable *cancellable, GError **error); void gdata_service_update_entry_async (GDataService *self, GDataEntry *entry, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); GDataEntry * gdata_service_update_entry_finish (GDataService *self, GAsyncResult *async_result, GError **error); gboolean gdata_service_delete_entry (GDataService *self, GDataEntry *entry, GCancellable *cancellable, GError **error); void gdata_service_delete_entry_async (GDataService *self, GDataEntry *entry, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean gdata_service_delete_entry_finish (GDataService *self, GAsyncResult *async_result, GError **error); const gchar * gdata_service_get_client_id (GDataService *self); const gchar * gdata_service_get_username (GDataService *self); const gchar * gdata_service_get_password (GDataService *self); SoupURI * gdata_service_get_proxy_uri (GDataService *self); void gdata_service_set_proxy_uri (GDataService *self, SoupURI *proxy_uri);
GObject +----GDataService +----GDataYouTubeService +----GDataPicasaWebService +----GDataDocumentsService +----GDataContactsService +----GDataCalendarService
"authenticated" gboolean : Read "client-id" gchar* : Read / Write / Construct Only "password" gchar* : Read "proxy-uri" SoupURI* : Read / Write "username" gchar* : Read
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.
typedef struct _GDataService GDataService;
All the fields in the GDataService structure are private and should never be accessed directly.
typedef struct { GObjectClass parent; const gchar *service_name; const gchar *authentication_uri; const gchar *api_version; GType feed_type; gboolean (*parse_authentication_response) (GDataService *self, guint status, const gchar *response_body, gint length, GError **error); void (*append_query_headers) (GDataService *self, SoupMessage *message); void (*parse_error_response) (GDataService *self, GDataServiceError error_type, guint status, const gchar *reason_phrase, const gchar *response_body, gint length, GError **error); } GDataServiceClass;
The class structure for the GDataService type.
GObjectClass |
the parent class |
const gchar * |
the name of the service (for subclasses) as given in the service's GData API documentation |
const gchar * |
the authentication URI (for subclasses) if different from the Google ClientLogin default |
const gchar * |
the version of the GData API used by the service (typically 2 )
|
GType |
the GType of the feed class (subclass of GDataFeed) to use for query results from this service |
|
a function to parse the response from the online service to an authentication request as
issued by gdata_service_authenticate() . It should return TRUE if authentication was successful, and FALSE if there was
an error.
|
|
a function to allow subclasses to append their own headers to queries before they are submitted to the online service |
|
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. |
typedef enum { GDATA_SERVICE_ERROR_UNAVAILABLE = 1, GDATA_SERVICE_ERROR_PROTOCOL_ERROR, GDATA_SERVICE_ERROR_WITH_QUERY, GDATA_SERVICE_ERROR_ENTRY_ALREADY_INSERTED, GDATA_SERVICE_ERROR_WITH_INSERTION, GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED, GDATA_SERVICE_ERROR_WITH_UPDATE, GDATA_SERVICE_ERROR_WITH_DELETION, GDATA_SERVICE_ERROR_NOT_FOUND, GDATA_SERVICE_ERROR_CONFLICT, GDATA_SERVICE_ERROR_FORBIDDEN, GDATA_SERVICE_ERROR_WITH_DOWNLOAD, GDATA_SERVICE_ERROR_WITH_UPLOAD, GDATA_SERVICE_ERROR_BAD_QUERY_PARAMETER } GDataServiceError;
Error codes for GDataService operations.
The service is unavailable due to maintainence or other reasons | |
The client or server unexpectedly strayed from the protocol (fatal error) | |
Generic error when querying for entries | |
An entry has already been inserted, and cannot be re-inserted | |
Generic error when inserting an entry | |
The user attempted to do something which required authentication, and they weren't authenticated | |
Generic error when updating an entry | |
Generic error when deleting an entry | |
A requested resource (feed or entry) was not found on the server | |
There was a conflict when updating an entry on the server; the server-side copy was modified inbetween downloading and uploading the modified entry | |
Generic error for a forbidden action (not due to having insufficient permissions) | |
Generic error when downloading a file (rather than querying for an entry) | |
Generic error when uploading a file (either inserting or updating an entry) | |
A given query parameter was invalid for the query type |
typedef enum { GDATA_AUTHENTICATION_ERROR_BAD_AUTHENTICATION = 1, GDATA_AUTHENTICATION_ERROR_NOT_VERIFIED, GDATA_AUTHENTICATION_ERROR_TERMS_NOT_AGREED, GDATA_AUTHENTICATION_ERROR_CAPTCHA_REQUIRED, GDATA_AUTHENTICATION_ERROR_ACCOUNT_DELETED, GDATA_AUTHENTICATION_ERROR_ACCOUNT_DISABLED, GDATA_AUTHENTICATION_ERROR_SERVICE_DISABLED } GDataAuthenticationError;
Error codes for GDataDataService authentication operations. See http://code.google.com/apis/accounts/docs/AuthForInstalledApps.htmlErrors for the official reference.
The login request used a username or password that is not recognized. | |
The account email address has not been verified. The user will need to access their Google account directly to resolve the issue before logging in using a non-Google application. | |
The user has not agreed to terms. The user will need to access their Google account directly to resolve the issue before logging in using a non-Google application. | |
A CAPTCHA is required. (A response with this error code will also contain an image URL and a CAPTCHA token.) | |
The user account has been deleted. | |
The user account has been disabled. | |
The user's access to the specified service has been disabled. (The user account may still be valid.) |
typedef enum { GDATA_PARSER_ERROR_PARSING_STRING = 1, GDATA_PARSER_ERROR_EMPTY_DOCUMENT } GDataParserError;
Error codes for XML parsing operations.
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.
|
a new GDataEntry |
|
the key of the entry (zero-based index of its position in the feed) |
|
the total number of entries in the feed |
|
user data passed to the callback |
gboolean gdata_service_authenticate (GDataService *self, const gchar *username, const gchar *password, GCancellable *cancellable, GError **error);
Authenticates the GDataService with the online service using username
and password
; i.e. logs into the service with the given
user account. username
should be a full e-mail address (e.g. john.smith
). If a full e-mail address is
not given, gmail.com
username
will have
appended to create an e-mail address
gmail.com
If cancellable
is not NULL
, then the operation can be cancelled by triggering the cancellable
object from another thread.
If the operation was cancelled, the error G_IO_ERROR_CANCELLED
will be returned.
A GDATA_AUTHENTICATION_ERROR_BAD_AUTHENTICATION
will be returned if authentication failed due to an incorrect username or password.
Other GDataAuthenticationError errors can be returned for other conditions.
If the service requires a CAPTCHA to be completed, the "captcha-challenge" signal will be emitted. The return value from
a signal handler for the signal should be the text from the image. If the text is NULL
or empty, authentication will fail with a
GDATA_AUTHENTICATION_ERROR_CAPTCHA_REQUIRED
error. Otherwise, authentication will be automatically and transparently restarted with
the new CAPTCHA details.
A GDATA_SERVICE_ERROR_PROTOCOL_ERROR
will be returned if the server's responses were invalid. Subclasses of GDataService can override
parsing the authentication response, and may return their own error codes. See their documentation for more details.
|
a GDataService |
|
the user's username |
|
the user's password |
|
optional GCancellable object, or NULL
|
|
a GError, or NULL
|
Returns : |
TRUE if authentication was successful, FALSE otherwise
|
void gdata_service_authenticate_async (GDataService *self, const gchar *username, const gchar *password, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data);
Authenticates the GDataService with the online service using the given username
and password
. self
, username
and
password
are all reffed/copied when this function is called, so can safely be freed after this function returns.
For more details, see gdata_service_authenticate()
, which is the synchronous version of this function.
When the operation is finished, callback
will be called. You can then call gdata_service_authenticate_finish()
to get the results of the operation.
|
a GDataService |
|
the user's username |
|
the user's password |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when authentication is finished |
|
data to pass to the callback function
|
gboolean gdata_service_authenticate_finish (GDataService *self, GAsyncResult *async_result, GError **error);
Finishes an asynchronous authentication operation started with gdata_service_authenticate_async()
.
|
a GDataService |
|
a GAsyncResult |
|
a GError, or NULL
|
Returns : |
TRUE if authentication was successful, FALSE otherwise
|
gboolean gdata_service_is_authenticated (GDataService *self);
Returns whether a user is authenticated with the online service through self
.
Authentication is performed by calling gdata_service_authenticate()
or gdata_service_authenticate_async()
.
|
a GDataService |
Returns : |
TRUE if a user is authenticated, FALSE otherwise
|
GDataFeed * gdata_service_query (GDataService *self, const gchar *feed_uri, GDataQuery *query, GType entry_type, GCancellable *cancellable, GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GError **error);
Queries the service's feed_uri
feed to build a GDataFeed.
If cancellable
is not NULL
, then the operation can be cancelled by triggering the cancellable
object from another thread.
If the operation was cancelled, the error G_IO_ERROR_CANCELLED
will be returned.
A GDATA_SERVICE_ERROR_WITH_QUERY
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, FALSE
will be returned, but error
will remain unset. Otherwise,
query
's ETag will be updated with the ETag from the returned feed, if available.
|
a GDataService |
|
the feed URI to query, including the host name and protocol |
|
a GDataQuery with the query parameters, or NULL
|
|
a GType for the GDataEntrys to build from the XML |
|
optional GCancellable object, or NULL
|
|
a GDataQueryProgressCallback to call when an entry is loaded, or NULL
|
|
data to pass to the progress_callback function
|
|
a GError, or NULL
|
Returns : |
a GDataFeed of query results, or NULL ; unref with g_object_unref()
|
void gdata_service_query_async (GDataService *self, const gchar *feed_uri, GDataQuery *query, GType entry_type, GCancellable *cancellable, GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GAsyncReadyCallback callback, gpointer user_data);
Queries the service's feed_uri
feed to build a GDataFeed. self
, feed_uri
and
query
are all reffed/copied when this function is called, so can safely be freed after this function returns.
For more details, see gdata_service_query()
, which is the synchronous version of this function.
When the operation is finished, callback
will be called. You can then call gdata_service_query_finish()
to get the results of the operation.
|
a GDataService |
|
the feed URI to query, including the host name and protocol |
|
a GDataQuery with the query parameters, or NULL
|
|
a GType for the GDataEntrys to build from the XML |
|
optional GCancellable object, or NULL
|
|
a GDataQueryProgressCallback to call when an entry is loaded, or NULL
|
|
data to pass to the progress_callback function
|
|
a GAsyncReadyCallback to call when the query is finished |
|
data to pass to the callback function
|
GDataFeed * gdata_service_query_finish (GDataService *self, GAsyncResult *async_result, GError **error);
Finishes an asynchronous query operation started with gdata_service_query_async()
.
|
a GDataService |
|
a GAsyncResult |
|
a GError, or NULL
|
Returns : |
a GDataFeed of query results, or NULL ; unref with g_object_unref()
|
GDataEntry * gdata_service_insert_entry (GDataService *self, const gchar *upload_uri, GDataEntry *entry, GCancellable *cancellable, GError **error);
Inserts entry
by uploading it to the online service at upload_uri
. For more information about the concept of inserting entries, see
the online documentation for the GData
protocol.
The service will return an updated version of the entry, which is the return value of this function on success.
If cancellable
is not NULL
, then the operation can be cancelled by triggering the cancellable
object from another thread.
If the operation was cancelled, the error G_IO_ERROR_CANCELLED
will be returned.
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_WITH_INSERTION
error will be returned. Currently, subclasses
cannot cannot override this or provide more specific errors.
|
a GDataService |
|
the URI to which the upload should be sent |
|
the GDataEntry to insert |
|
optional GCancellable object, or NULL
|
|
a GError, or NULL
|
Returns : |
an updated GDataEntry, or NULL
|
void gdata_service_insert_entry_async (GDataService *self, const gchar *upload_uri, GDataEntry *entry, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data);
Inserts entry
by uploading it to the online service at upload_uri
. self
, upload_uri
and
entry
are all reffed/copied when this function is called, so can safely be freed after this function returns.
For more details, see gdata_service_insert_entry()
, which is the synchronous version of this function.
When the operation is finished, callback
will be called. You can then call gdata_service_insert_entry_finish()
to get the results of the operation.
|
a GDataService |
|
the URI to which the upload should be sent |
|
the GDataEntry to insert |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when insertion is finished |
|
data to pass to the callback function
|
Since 0.3.0
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()
.
|
a GDataService |
|
a GAsyncResult |
|
a GError, or NULL
|
Returns : |
an updated GDataEntry, or NULL ; unref with g_object_unref()
|
Since 0.3.0
GDataEntry * gdata_service_update_entry (GDataService *self, GDataEntry *entry, GCancellable *cancellable, GError **error);
Updates entry
by PUTting it to its edit
link's URI. For more information about the concept of updating entries, see
the online documentation for the GData
protocol.
The service will return an updated version of the entry, which is the return value of this function on success.
If cancellable
is not NULL
, then the operation can be cancelled by triggering the cancellable
object from another thread.
If the operation was cancelled, the error G_IO_ERROR_CANCELLED
will be returned.
If there is an error updating the entry, a GDATA_SERVICE_ERROR_WITH_UPDATE
error will be returned. Currently, subclasses
cannot cannot override this or provide more specific errors.
|
a GDataService |
|
the GDataEntry to update |
|
optional GCancellable object, or NULL
|
|
a GError, or NULL
|
Returns : |
an updated GDataEntry, or NULL
|
Since 0.2.0
void gdata_service_update_entry_async (GDataService *self, GDataEntry *entry, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data);
Updates entry
by PUTting it to its edit
link's URI. self
and
entry
are both reffed when this function is called, so can safely be unreffed after this function returns.
For more details, see gdata_service_update_entry()
, which is the synchronous version of this function.
When the operation is finished, callback
will be called. You can then call gdata_service_update_entry_finish()
to get the results of the operation.
|
a GDataService |
|
the GDataEntry to update |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the update is finished |
|
data to pass to the callback function
|
Since 0.3.0
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()
.
|
a GDataService |
|
a GAsyncResult |
|
a GError, or NULL
|
Returns : |
an updated GDataEntry, or NULL ; unref with g_object_unref()
|
Since 0.3.0
gboolean gdata_service_delete_entry (GDataService *self, GDataEntry *entry, GCancellable *cancellable, GError **error);
Deletes entry
from the server. For more information about the concept of deleting entries, see the
online documentation for the GData
protocol.
If cancellable
is not NULL
, then the operation can be cancelled by triggering the cancellable
object from another thread.
If the operation was cancelled, the error G_IO_ERROR_CANCELLED
will be returned.
If there is an error deleting the entry, a GDATA_SERVICE_ERROR_WITH_DELETION
error will be returned. Currently, subclasses
cannot cannot override this or provide more specific errors.
|
a GDataService |
|
the GDataEntry to delete |
|
optional GCancellable object, or NULL
|
|
a GError, or NULL
|
Returns : |
TRUE on success, FALSE otherwise
|
Since 0.2.0
void gdata_service_delete_entry_async (GDataService *self, GDataEntry *entry, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data);
Deletes entry
from the server. self
and entry
are both reffed when this function is called,
so can safely be unreffed after this function returns.
For more details, see gdata_service_delete_entry()
, which is the synchronous version of this function.
When the operation is finished, callback
will be called. You can then call gdata_service_delete_entry_finish()
to get the results of the operation.
|
a GDataService |
|
the GDataEntry to delete |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when deletion is finished |
|
data to pass to the callback function
|
Since 0.3.0
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()
.
|
a GDataService |
|
a GAsyncResult |
|
a GError, or NULL
|
Returns : |
TRUE on success, FALSE otherwise
|
Since 0.3.0
const gchar * gdata_service_get_client_id (GDataService *self);
Returns the service's client ID, as specified on constructing the GDataService.
|
a GDataService |
Returns : |
the service's client ID |
const gchar * gdata_service_get_username (GDataService *self);
Returns the username of the currently-authenticated user, or NULL
if nobody is authenticated.
|
a GDataService |
Returns : |
the username of the currently-authenticated user, or NULL
|
const gchar * gdata_service_get_password (GDataService *self);
Returns the password of the currently-authenticated user, or NULL
if nobody is authenticated.
|
a GDataService |
Returns : |
the password of the currently-authenticated user, or NULL
|
SoupURI * gdata_service_get_proxy_uri (GDataService *self);
Gets the proxy URI on the GDataService's SoupSession.
|
a GDataService |
Returns : |
the proxy URI, or NULL
|
Since 0.2.0
"authenticated"
property"authenticated" gboolean : Read
Whether the user is authenticated (logged in) with the service.
Default value: FALSE
"client-id"
property"client-id" gchar* : Read / Write / Construct Only
A client ID for your application (see the YouTube reference documentation).
Default value: NULL
"password"
property"password" gchar* : Read
The user's account password for authentication.
Default value: NULL
"proxy-uri"
property"proxy-uri" SoupURI* : Read / Write
The proxy URI used internally for all Internet requests.
Since 0.2.0
"captcha-challenge"
signalgchar* user_function (GDataService *service, gchar *uri, gpointer user_data) : Run Last
The "captcha-challenge" signal is emitted during the authentication process if the service requires a CAPTCHA to be completed. The URI of a CAPTCHA image is given, and the program should display this to the user, and return their response (the text displayed in the image). There is no timeout imposed by the library for the response.
|
the GDataService which received the challenge |
|
the URI of the CAPTCHA image to be used |
|
user data set when the signal handler was connected. |
Returns : |
the text in the CAPTCHA image |