## GDataAuthorizer GDataAuthorizer — GData authorization interface |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <gdata/gdata-authorizer.h>

                        GDataAuthorizer;
                        GDataAuthorizerInterface;
    void                gdata_authorizer_process_request    (GDataAuthorizer *self,
                                                             GDataAuthorizationDomain *domain,
                                                             SoupMessage *message);
    gboolean            gdata_authorizer_is_authorized_for_domain
                                                            (GDataAuthorizer *self,
                                                             GDataAuthorizationDomain *domain);
    gboolean            gdata_authorizer_refresh_authorization
                                                            (GDataAuthorizer *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_authorizer_refresh_authorization_async
                                                            (GDataAuthorizer *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gdata_authorizer_refresh_authorization_finish
                                                            (GDataAuthorizer *self,
                                                             GAsyncResult *async_result,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----GDataAuthorizer

## Prerequisites

GDataAuthorizer requires GObject.

## Known Implementations

GDataAuthorizer is implemented by GDataClientLoginAuthorizer and GDataOAuth1Authorizer.

## 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 GDataOAuth1Authorizer, 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:

- GDataClientLoginAuthorizer for ClientLogin (deprecated)
- GDataOAuth1Authorizer for OAuth 1.0 (preferred)

It is quite possible for clients to write their own GDataAuthorizer implementation. For example, if a client 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.

## Details

### 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.

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

### 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.

`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.

`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.

`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.

`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.

`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