GDataClientLoginAuthorizer

typedef struct _GDataClientLoginAuthorizer GDataClientLoginAuthorizer;

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

Since 0.9.0

GDataClientLoginAuthorizerClass

typedef struct {
} GDataClientLoginAuthorizerClass;

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

Since 0.9.0

enum GDataClientLoginAuthorizerError

typedef enum {
	GDATA_CLIENT_LOGIN_AUTHORIZER_ERROR_BAD_AUTHENTICATION = 1,
	GDATA_CLIENT_LOGIN_AUTHORIZER_ERROR_NOT_VERIFIED,
	GDATA_CLIENT_LOGIN_AUTHORIZER_ERROR_TERMS_NOT_AGREED,
	GDATA_CLIENT_LOGIN_AUTHORIZER_ERROR_CAPTCHA_REQUIRED,
	GDATA_CLIENT_LOGIN_AUTHORIZER_ERROR_ACCOUNT_DELETED,
	GDATA_CLIENT_LOGIN_AUTHORIZER_ERROR_ACCOUNT_DISABLED,
	GDATA_CLIENT_LOGIN_AUTHORIZER_ERROR_SERVICE_DISABLED,
	GDATA_CLIENT_LOGIN_AUTHORIZER_ERROR_ACCOUNT_MIGRATED,
	GDATA_CLIENT_LOGIN_AUTHORIZER_ERROR_INVALID_SECOND_FACTOR
} GDataClientLoginAuthorizerError;

Error codes for authentication and authorization operations on GDataClientLoginAuthorizer. See the online ClientLogin documentation for more information.

Since 0.9.0

gdata_client_login_authorizer_new ()

GDataClientLoginAuthorizer * gdata_client_login_authorizer_new
                                                        (const gchar *client_id,
                                                         GType service_type);

Creates a new GDataClientLoginAuthorizer. The client_id must be unique for your application, and as registered with Google.

The GDataAuthorizationDomains for the given service_type (i.e. as returned by gdata_service_get_authorization_domains()) are the ones the user will be logged in to using the provided username and password when gdata_client_login_authorizer_authenticate() is called. Note that the same username and password will be used for all domains.

Since 0.9.0

gdata_client_login_authorizer_new_for_authorization_domains ()

GDataClientLoginAuthorizer * gdata_client_login_authorizer_new_for_authorization_domains
                                                        (const gchar *client_id,
                                                         GList *authorization_domains);

Creates a new GDataClientLoginAuthorizer. The client_id must be unique for your application, and as registered with Google. This function is intended to be used only when the default authorization domain list for a single GDataService, as used by gdata_client_login_authorizer_new(), isn't suitable. For example, this could be because the GDataClientLoginAuthorizer will be used with multiple GDataService subclasses, or because the client requires a specific set of authorization domains.

The specified GDataAuthorizationDomains are the ones the user will be logged in to using the provided username and password when gdata_client_login_authorizer_authenticate() is called. Note that the same username and password will be used for all domains.

Since 0.9.0

gdata_client_login_authorizer_authenticate ()

gboolean            gdata_client_login_authorizer_authenticate
                                                        (GDataClientLoginAuthorizer *self,
                                                         const gchar *username,
                                                         const gchar *password,
                                                         GCancellable *cancellable,
                                                         GError **error);

Authenticates the GDataClientLoginAuthorizer with the Google Accounts service using username and password and authorizes it against all the service types passed to gdata_client_login_authorizer_new(); i.e. logs into the service with the given user account. username should be a full e-mail address (e.g. john.smith@gmail.com). If a full e-mail address is not given, username will have @gmail.com appended to create an e-mail address

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

If the operation errors or is cancelled part-way through, gdata_authorizer_is_authorized_for_domain() is guaranteed to return FALSE for all GDataAuthorizationDomains, even if authentication has succeeded for some of them already.

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

If the service requires a CAPTCHA to be completed, the "captcha-challenge" signal will be emitted. The return value from a signal handler for the signal should be a newly allocated string containing the text from the image. If the text is NULL or empty, authentication will fail with a GDATA_CLIENT_LOGIN_AUTHORIZER_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.

Since 0.9.0

gdata_client_login_authorizer_authenticate_async ()

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

Authenticates the GDataClientLoginAuthorizer with the Google accounts 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_client_login_authorizer_authenticate(), which is the synchronous version of this function.

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

Since 0.9.0

gdata_client_login_authorizer_authenticate_finish ()

gboolean            gdata_client_login_authorizer_authenticate_finish
                                                        (GDataClientLoginAuthorizer *self,
                                                         GAsyncResult *async_result,
                                                         GError **error);

Finishes an asynchronous authentication operation started with gdata_client_login_authorizer_authenticate_async().

Since 0.9.0

gdata_client_login_authorizer_get_client_id ()

const gchar *       gdata_client_login_authorizer_get_client_id
                                                        (GDataClientLoginAuthorizer *self);

Returns the authorizer's client ID, as specified on constructing the GDataClientLoginAuthorizer.

Since 0.9.0

gdata_client_login_authorizer_get_username ()

const gchar *       gdata_client_login_authorizer_get_username
                                                        (GDataClientLoginAuthorizer *self);

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

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

Since 0.9.0

gdata_client_login_authorizer_get_password ()

const gchar *       gdata_client_login_authorizer_get_password
                                                        (GDataClientLoginAuthorizer *self);

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

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

If libgdata is compiled with libgcr support, the password will be stored in non-pageable memory. Since this function doesn't return a copy of the password, the returned value is guaranteed to not hit disk. It's advised that any copies of the password made in client programs also use non-pageable memory.

Since 0.9.0

gdata_client_login_authorizer_get_proxy_uri ()

SoupURI *           gdata_client_login_authorizer_get_proxy_uri
                                                        (GDataClientLoginAuthorizer *self);

Gets the proxy URI on the GDataClientLoginAuthorizer's SoupSession.

Since 0.9.0

gdata_client_login_authorizer_set_proxy_uri ()

void                gdata_client_login_authorizer_set_proxy_uri
                                                        (GDataClientLoginAuthorizer *self,
                                                         SoupURI *proxy_uri);

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

If proxy_uri is NULL, no proxy will be used.

Since 0.9.0

gdata_client_login_authorizer_get_timeout ()

guint               gdata_client_login_authorizer_get_timeout
                                                        (GDataClientLoginAuthorizer *self);

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

Since 0.9.0

gdata_client_login_authorizer_set_timeout ()

void                gdata_client_login_authorizer_set_timeout
                                                        (GDataClientLoginAuthorizer *self,
                                                         guint timeout);

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

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

Since 0.9.0

The "client-id" property

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

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

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

Default value: NULL

Since 0.9.0

The "password" property

  "password"                 gchar*                : Read

The user's account password for authentication.

This will only be set after authentication using gdata_client_login_authorizer_authenticate() is completed successfully. It will then be set to the password passed to gdata_client_login_authorizer_authenticate(), and a "notify" signal will be emitted. If authentication fails, it will be set to NULL.

If libgdata is compiled with libgcr support, the password will be stored in non-pageable memory. However, if it is retrieved using g_object_get() (or related functions) it will be copied to non-pageable memory and could end up being written to disk. Accessing the password using gdata_client_login_authorizer_get_password() will not perform any copies, and so maintains privacy.

Default value: NULL

Since 0.9.0

The "proxy-uri" property

  "proxy-uri"                SoupURI*              : Read / Write

The proxy URI used internally for all network requests.

Since 0.9.0

The "timeout" property

  "timeout"                  guint                 : Read / Write

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

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

Default value: 0

Since 0.9.0

The "username" property

  "username"                 gchar*                : Read

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

This will only be set after authentication using gdata_client_login_authorizer_authenticate() is completed successfully. It will then be set to the username passed to gdata_client_login_authorizer_authenticate(), and a "notify" signal will be emitted. If authentication fails, it will be set to NULL.

Default value: NULL

Since 0.9.0

The "captcha-challenge" signal

gchar*              user_function                      (GDataClientLoginAuthorizer *authorizer,
                                                        gchar                      *uri,
                                                        gpointer                    user_data)       : Run Last

The "captcha-challenge" signal is emitted during the authentication process if the authorizer 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.

Since 0.9.0