gdata_oauth1_authorizer_new ()

GDataOAuth1Authorizer *
gdata_oauth1_authorizer_new (const gchar *application_name,
                             GType service_type);

Creates a new GDataOAuth1Authorizer.

The GDataAuthorizationDomains for the given service_type (i.e. as returned by gdata_service_get_authorization_domains()) are the ones the user will be requested to authorize access to on the page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri().

The given application_name will set the value of “application-name” and will be displayed to the user on authentication pages returned by Google. If NULL is provided, the value of g_get_application_name() will be used as a fallback.

Since: 0.9.0

gdata_oauth1_authorizer_new_for_authorization_domains ()

GDataOAuth1Authorizer *
gdata_oauth1_authorizer_new_for_authorization_domains
                               (const gchar *application_name,
                                GList *authorization_domains);

Creates a new GDataOAuth1Authorizer. This function is intended to be used only when the default authorization domain list for a single GDataService, as used by gdata_oauth1_authorizer_new(), isn't suitable. For example, this could be because the GDataOAuth1Authorizer 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 requested to authorize access to on the page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri().

The given application_name will set the value of “application-name” and will be displayed to the user on authentication pages returned by Google. If NULL is provided, the value of g_get_application_name() will be used as a fallback.

Since: 0.9.0

gdata_oauth1_authorizer_request_authentication_uri ()

gchar *
gdata_oauth1_authorizer_request_authentication_uri
                               (GDataOAuth1Authorizer *self,
                                gchar **token,
                                gchar **token_secret,
                                GCancellable *cancellable,
                                GError **error);

Requests a fresh unauthenticated token from the Google accounts service and builds and returns the URI of an authentication page for that token. This should then be presented to the user (e.g. in an embedded or stand alone web browser). The authentication page will ask the user to log in using their Google account, then ask them to grant access to the GDataAuthorizationDomains passed to the constructor of the GDataOAuth1Authorizer. If the user grants access, they will be given a verifier, which can then be passed to gdata_oauth1_authorizer_request_authorization() (along with the token and token_secret values returned by this method) to authorize the token.

This method can fail if the server returns an error, but this is unlikely. If it does happen, a GDATA_SERVICE_ERROR_PROTOCOL_ERROR will be raised, token and token_secret will be set to NULL and NULL will be returned.

This method implements Section 2.1 and

When freeing token_secret , it's advisable to set it to all zeros first, to reduce the chance of the sensitive token being recoverable from the free memory pool and (accidentally) leaked by a different part of the process. This can be achieved with the following code:

1
2
3
4

if (token_secret != NULL) {
    memset (token_secret, 0, strlen (token_secret));
    g_free (token_secret);
}

Since: 0.9.0

gdata_oauth1_authorizer_request_authentication_uri_async ()

void
gdata_oauth1_authorizer_request_authentication_uri_async
                               (GDataOAuth1Authorizer *self,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Requests a fresh unauthenticated token from the Google accounts service and builds and returns the URI of an authentication page for that token. self is reffed when this method is called, so can safely be unreffed after this method returns.

For more details, see gdata_oauth1_authorizer_request_authentication_uri(), which is the synchronous version of this method.

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

Since: 0.9.0

gdata_oauth1_authorizer_request_authentication_uri_finish ()

gchar *
gdata_oauth1_authorizer_request_authentication_uri_finish
                               (GDataOAuth1Authorizer *self,
                                GAsyncResult *async_result,
                                gchar **token,
                                gchar **token_secret,
                                GError **error);

Finishes an asynchronous authentication URI building operation started with gdata_oauth1_authorizer_request_authentication_uri_async().

This method can fail if the server has returned an error, but this is unlikely. If it does happen, a GDATA_SERVICE_ERROR_PROTOCOL_ERROR will be raised, token and token_secret will be set to NULL and NULL will be returned.

When freeing token_secret , it's advisable to set it to all zeros first, to reduce the chance of the sensitive token being recoverable from the free memory pool and (accidentally) leaked by a different part of the process. This can be achieved with the following code:

1
2
3
4

if (token_secret != NULL) {
    memset (token_secret, 0, strlen (token_secret));
    g_free (token_secret);
}

Since: 0.9.0

gdata_oauth1_authorizer_request_authorization ()

gboolean
gdata_oauth1_authorizer_request_authorization
                               (GDataOAuth1Authorizer *self,
                                const gchar *token,
                                const gchar *token_secret,
                                const gchar *verifier,
                                GCancellable *cancellable,
                                GError **error);

Requests authorization of the given request token from the Google accounts service using the given verifier as entered by the user from the authentication page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri(). token and token_secret must be the same values as were returned by gdata_oauth1_authorizer_request_authentication_uri() if it was successful.

If the verifier is valid (i.e. the user granted access to the application and the Google accounts service has no reason to distrust the client), TRUE will be returned and any operations performed from that point onwards on GDataServices using this GDataAuthorizer will be authorized.

If the user denies access to the application or the Google accounts service distrusts it, a bogus verifier could be returned. In this case, FALSE will be returned and a GDATA_SERVICE_ERROR_FORBIDDEN error will be raised.

Note that if the user denies access to the application, it may be the case that they have no verifier to enter. In this case, the client can simply not call this method. The GDataOAuth1Authorizer stores no state for authentication operations which have succeeded in calling gdata_oauth1_authorizer_request_authentication_uri() but not yet successfully called gdata_oauth1_authorizer_request_authorization().

This method implements Section 2.3 of the

Since: 0.9.0

gdata_oauth1_authorizer_request_authorization_async ()

void
gdata_oauth1_authorizer_request_authorization_async
                               (GDataOAuth1Authorizer *self,
                                const gchar *token,
                                const gchar *token_secret,
                                const gchar *verifier,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Requests authorization of the given request token from the Google accounts service using the given verifier as entered by the user. self , token , token_secret and verifier are reffed/copied when this method is called, so can safely be freed after this method returns.

For more details, see gdata_oauth1_authorizer_request_authorization(), which is the synchronous version of this method.

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

Since: 0.9.0

gdata_oauth1_authorizer_request_authorization_finish ()

gboolean
gdata_oauth1_authorizer_request_authorization_finish
                               (GDataOAuth1Authorizer *self,
                                GAsyncResult *async_result,
                                GError **error);

Finishes an asynchronous authorization operation started with gdata_oauth1_authorizer_request_authorization_async().

Since: 0.9.0

gdata_oauth1_authorizer_get_application_name ()

const gchar *
gdata_oauth1_authorizer_get_application_name
                               (GDataOAuth1Authorizer *self);

Returns the application name being used on the authentication page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri(); i.e. the value of “application-name”.

Since: 0.9.0

gdata_oauth1_authorizer_get_locale ()

const gchar *
gdata_oauth1_authorizer_get_locale (GDataOAuth1Authorizer *self);

Returns the locale currently being used for network requests, or NULL if the locale is the default.

Since: 0.9.0

gdata_oauth1_authorizer_set_locale ()

void
gdata_oauth1_authorizer_set_locale (GDataOAuth1Authorizer *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 (i.e. calling gdata_oauth1_authorizer_request_authentication_uri() for the first time), it is unsupported, as the server-side software may behave unexpectedly. The only supported use of this method is after creation of the authorizer, but before any network requests are made.

Since: 0.9.0

gdata_oauth1_authorizer_get_proxy_uri ()

SoupURI *
gdata_oauth1_authorizer_get_proxy_uri (GDataOAuth1Authorizer *self);

Gets the proxy URI on the GDataOAuth1Authorizer's SoupSession.

Since: 0.9.0

gdata_oauth1_authorizer_set_proxy_uri ()

void
gdata_oauth1_authorizer_set_proxy_uri (GDataOAuth1Authorizer *self,
                                       SoupURI *proxy_uri);

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

If proxy_uri is NULL, no proxy will be used.

Since: 0.9.0

gdata_oauth1_authorizer_get_proxy_resolver ()

GProxyResolver *
gdata_oauth1_authorizer_get_proxy_resolver
                               (GDataOAuth1Authorizer *self);

Gets the GProxyResolver on the GDataOAuth1Authorizer's SoupSession.

Since: 0.15.0

gdata_oauth1_authorizer_set_proxy_resolver ()

void
gdata_oauth1_authorizer_set_proxy_resolver
                               (GDataOAuth1Authorizer *self,
                                GProxyResolver *proxy_resolver);

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

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

Since: 0.15.0

gdata_oauth1_authorizer_get_timeout ()

guint
gdata_oauth1_authorizer_get_timeout (GDataOAuth1Authorizer *self);

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

Since: 0.9.0

gdata_oauth1_authorizer_set_timeout ()

void
gdata_oauth1_authorizer_set_timeout (GDataOAuth1Authorizer *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

GDataOAuth1Authorizer

typedef struct _GDataOAuth1Authorizer GDataOAuth1Authorizer;

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

Since: 0.9.0

GDataOAuth1AuthorizerClass

typedef struct {
} GDataOAuth1AuthorizerClass;

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

Since: 0.9.0

The “application-name” property

  “application-name”         gchar *

The human-readable, translated application name for the client, to be presented to the user on the authentication page at the URI returned by gdata_oauth1_authorizer_request_authentication_uri().

If NULL is provided in the constructor to GDataOAuth1Authorizer, the value returned by g_get_application_name() will be used as a fallback. Note that this may also be NULL: in this case, the authentication page will use the application name “anonymous”.

Flags: Read / Write / Construct Only

Default value: NULL

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

This locale will be used by the server-side software to localise the authentication and authorization pages at the URI returned by gdata_oauth1_authorizer_request_authentication_uri().

The server-side behaviour is undefined if it doesn't support a given locale.

Flags: Read / Write

Default value: NULL

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

Flags: Read / Write

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

Flags: Read / Write

Default value: 0

Since: 0.9.0