GDataAuthorizer

GDataAuthorizer — GData authorization interface

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Object Hierarchy

    GInterface
    ╰── GDataAuthorizer

Prerequisites

GDataAuthorizer requires GObject.

Known Implementations

GDataAuthorizer is implemented by GDataClientLoginAuthorizer, GDataGoaAuthorizer, GDataOAuth1Authorizer and GDataOAuth2Authorizer.

Includes

#include <gdata/gdata-authorizer.h>

Description

The GDataAuthorizer interface provides a uniform way to implement authentication and authorization processes for use by GDataServices. Client code will construct a new GDataAuthorizer instance of their choosing, such as GDataClientLoginAuthorizer or GDataOAuth2Authorizer, for the GDataServices which will be used by the client, then authenticates and authorizes with the GDataAuthorizer instead of the GDataService. The GDataService then uses the GDataAuthorizer to authorize individual network requests using whatever authorization token was returned to the GDataAuthorizer by the Google Accounts service.

All GDataAuthorizer implementations are expected to operate against a set of GDataAuthorizationDomains which are provided to the authorizer at construction time. These domains specify which data domains the client expects to access using the GDataServices they have using the GDataAuthorizer instance. Following the principle of least privilege, the set of domains should be the minimum such set of domains which still allows the client to operate normally. Note that implementations of GDataAuthorizationDomain may display the list of requested authorization domains to the user for verification before authorization is granted.

GDataAuthorizer implementations are provided for some of the standard authorization processes supported by Google for installed applications, as listed in their online documentation:

It is quite possible for clients to write their own GDataAuthorizer implementation. For example, if a client already uses OAuth 2.0 and handles authentication itself, it may want to use its own GDataAuthorizer implementation which simply exposes the client's existing access token to libgdata and does nothing more.

It must be noted that all GDataAuthorizer implementations must be thread safe, as methods such as gdata_authorizer_refresh_authorization() may be called from any thread (such as the thread performing an asynchronous query operation) at any time.

Examples of code using GDataAuthorizer can be found in the documentation for the various implementations of the GDataAuthorizer interface.

Functions

gdata_authorizer_process_request ()

void
gdata_authorizer_process_request (GDataAuthorizer *self,
                                  GDataAuthorizationDomain *domain,
                                  SoupMessage *message);

Processes message , adding all the necessary extra headers and parameters to ensure that it's correctly authenticated and authorized under the given domain for the online service. Basically, if a query is not processed by calling this method on it, it will be sent to the online service as if it's a query from a non-logged-in user. Similarly, if the GDataAuthorizer isn't authenticated or authorized (for domain ), no changes will be made to the message .

domain may be NULL if the request doesn't require authorization.

This modifies message in place.

This method is thread safe.

Parameters

self

a GDataAuthorizer

 

domain

the GDataAuthorizationDomain the query falls under, or NULL.

[allow-none]

message

the query to process

 

Since: 0.9.0


gdata_authorizer_is_authorized_for_domain ()

gboolean
gdata_authorizer_is_authorized_for_domain
                               (GDataAuthorizer *self,
                                GDataAuthorizationDomain *domain);

Returns whether the GDataAuthorizer instance believes it's currently authorized to access the given domain . Note that this will not perform any network requests, and will just look up the result in the GDataAuthorizer's local cache of authorizations. This means that the result may be out of date, as the server may have since invalidated the authorization. If the GDataAuthorizer class supports timeouts and TTLs on authorizations, they will not be taken into account; this method effectively returns whether the last successful authorization operation performed on the GDataAuthorizer included domain in the list of requested authorization domains.

Note that NULL may be passed as the GDataAuthorizer, in which case FALSE will always be returned, regardless of the domain . This is for convenience of checking whether a domain is authorized by the GDataAuthorizer returned by gdata_service_get_authorizer(), which may be NULL. For example:

1
2
3
if (gdata_authorizer_is_authorized_for_domain (gdata_service_get_authorizer (my_service), my_domain) == TRUE) {
    /<!-- -->* Code to execute only if we're authorized for the given domain *<!-- -->/
}

This method is thread safe.

Parameters

self

a GDataAuthorizer, or NULL.

[allow-none]

domain

the GDataAuthorizationDomain to check against

 

Returns

TRUE if the GDataAuthorizer has been authorized to access domain , FALSE otherwise

Since: 0.9.0


gdata_authorizer_refresh_authorization ()

gboolean
gdata_authorizer_refresh_authorization
                               (GDataAuthorizer *self,
                                GCancellable *cancellable,
                                GError **error);

Forces the GDataAuthorizer to refresh any authorization tokens it holds with the online service. This should typically be called when a GDataService query returns GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED, and is already called transparently by methods such as gdata_service_query() and gdata_service_insert_entry() (see their documentation for more details).

If re-authorization is successful, it's guaranteed that by the time this method returns, the properties containing the relevant authorization tokens on the GDataAuthorizer instance will have been updated.

If FALSE is returned, error will be set if (and only if) it's due to a refresh being attempted and failing. If a refresh is not attempted, FALSE will be returned but error will not be set.

If the GDataAuthorizer has not been previously authenticated or authorized (using the class' specific methods), no authorization will be attempted, FALSE will be returned immediately and error will not be set.

Some GDataAuthorizer implementations may not support refreshing authorization tokens at all; for example if doing so requires user interaction. FALSE will be returned immediately in that case and error will not be set.

This method is thread safe.

Parameters

self

a GDataAuthorizer

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

error

a GError, or NULL

 

Returns

TRUE if an authorization refresh was attempted and was successful, FALSE if a refresh wasn't attempted or was unsuccessful

Since: 0.9.0


gdata_authorizer_refresh_authorization_async ()

void
gdata_authorizer_refresh_authorization_async
                               (GDataAuthorizer *self,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Forces the GDataAuthorizer to refresh any authorization tokens it holds with the online service. self and cancellable are reffed when this method is called, so can safely be freed after this method returns.

For more details, see gdata_authorizer_refresh_authorization(), which is the synchronous version of this method. If the GDataAuthorizer class doesn't implement GDataAuthorizerInterface.refresh_authorization_async but does implement GDataAuthorizerInterface.refresh_authorization, the latter will be called from a new thread to make it asynchronous.

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

This method is thread safe.

Parameters

self

a GDataAuthorizer

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

callback

a GAsyncReadyCallback to call when the authorization refresh operation is finished, or NULL.

[allow-none][scope async]

user_data

data to pass to the callback function.

[closure]

Since: 0.9.0


gdata_authorizer_refresh_authorization_finish ()

gboolean
gdata_authorizer_refresh_authorization_finish
                               (GDataAuthorizer *self,
                                GAsyncResult *async_result,
                                GError **error);

Finishes an asynchronous authorization refresh operation for the GDataAuthorizer, as started with gdata_authorizer_refresh_authorization_async().

This method is thread safe.

Parameters

self

a GDataAuthorizer

 

async_result

a GAsyncResult

 

error

a GError, or NULL

 

Returns

TRUE if an authorization refresh was attempted and was successful, FALSE if a refresh wasn't attempted or was unsuccessful

Since: 0.9.0

Types and Values

GDataAuthorizer

typedef struct _GDataAuthorizer GDataAuthorizer;

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

Since: 0.9.0


GDataAuthorizerInterface

typedef struct {
	GTypeInterface parent;

	void (*process_request) (GDataAuthorizer *self, GDataAuthorizationDomain *domain, SoupMessage *message);
	gboolean (*is_authorized_for_domain) (GDataAuthorizer *self, GDataAuthorizationDomain *domain);
	gboolean (*refresh_authorization) (GDataAuthorizer *self, GCancellable *cancellable, GError **error);
	void (*refresh_authorization_async) (GDataAuthorizer *self, GCancellable *cancellable,
	                                     GAsyncReadyCallback callback, gpointer user_data);
	gboolean (*refresh_authorization_finish) (GDataAuthorizer *self, GAsyncResult *async_result, GError **error);
} GDataAuthorizerInterface;

The class structure for the GDataAuthorizer interface.

Members

GTypeInterface parent;

the parent type

 

process_request ()

a function to append authorization headers to queries before they are submitted to the online service under the given authorization domain (which may be NULL); this must be implemented and must be thread safe, and must also handle being called multiple times on the same SoupMessage instance (so must be careful to replace headers rather than append them, for example)

 

is_authorized_for_domain ()

a function to check whether the authorizer is authorized against the given domain; this must be implemented and must be thread safe

 

refresh_authorization ()

a function to force a refresh of any authorization tokens the authorizer holds, returning TRUE if a refresh was attempted and was successful, or FALSE if a refresh wasn't attempted or was unsuccessful; if this isn't implemented it's assumed FALSE would've been returned, if it is implemented it must be thread safe.

[allow-none]

refresh_authorization_async ()

an asynchronous version of refresh_authorization ; if this isn't implemented and refresh_authorization is, refresh_authorization will be called in a thread to simulate this function, whereas if this is implemented refresh_authorization_finish must also be implemented and both functions must be thread safe.

[allow-none]

refresh_authorization_finish ()

a finish function for the asynchronous version of refresh_authorization ; this must be implemented exactly if refresh_authorization_async is implemented, and must be thread safe if it is implemented.

[allow-none]

Since: 0.9.0