GoaBackendOAuthProvider

GoaBackendOAuthProvider — Abstract base class for OAuth 1.0a providers

Synopsis

                    GoaBackendOAuthProvider;
struct              GoaBackendOAuthProviderClass;
const gchar *       goa_backend_oauth_provider_get_request_uri
                                                        (GoaBackendOAuthProvider *provider);
gchar **            goa_backend_oauth_provider_get_request_uri_params
                                                        (GoaBackendOAuthProvider *provider);
const gchar *       goa_backend_oauth_provider_get_authorization_uri
                                                        (GoaBackendOAuthProvider *provider);
const gchar *       goa_backend_oauth_provider_get_token_uri
                                                        (GoaBackendOAuthProvider *provider);
const gchar *       goa_backend_oauth_provider_get_callback_uri
                                                        (GoaBackendOAuthProvider *provider);
const gchar *       goa_backend_oauth_provider_get_consumer_key
                                                        (GoaBackendOAuthProvider *provider);
const gchar *       goa_backend_oauth_provider_get_consumer_secret
                                                        (GoaBackendOAuthProvider *provider);
gchar *             goa_backend_oauth_provider_build_authorization_uri
                                                        (GoaBackendOAuthProvider *provider,
                                                         const gchar *authorization_uri,
                                                         const gchar *escaped_oauth_token);
gboolean            goa_backend_oauth_provider_get_use_external_browser
                                                        (GoaBackendOAuthProvider *provider);
gchar *             goa_backend_oauth_provider_get_identity_sync
                                                        (GoaBackendOAuthProvider *provider,
                                                         const gchar *access_token,
                                                         const gchar *access_token_secret,
                                                         gchar **out_name,
                                                         GCancellable *cancellable,
                                                         GError **error);
gchar *             goa_backend_oauth_provider_get_access_token_sync
                                                        (GoaBackendOAuthProvider *provider,
                                                         GoaObject *object,
                                                         gboolean force_refresh,
                                                         gchar **out_access_token_secret,
                                                         gint *out_access_token_expires_in,
                                                         GCancellable *cancellable,
                                                         GError **error);

Object Hierarchy

  GObject
   +----GoaBackendProvider
         +----GoaBackendOAuthProvider
               +----GoaBackendGoogleProvider
               +----GoaBackendYahooProvider
               +----GoaBackendTwitterProvider

Description

GoaBackendOAuthProvider is an abstract base class for OAuth 1.0a compliant implementations as defined by RFC 5849. Additionally, the code works with providers implementing OAuth Session 1.0 Draft 1 for refreshing access tokens.

Subclasses must implement GoaBackendOAuthProviderClass.get_consumer_key, GoaBackendOAuthProviderClass.get_consumer_secret, GoaBackendOAuthProviderClass.get_request_uri, GoaBackendOAuthProviderClass.get_authorization_uri, GoaBackendOAuthProviderClass.get_token_uri, GoaBackendOAuthProviderClass.get_callback_uri and GoaBackendOAuthProviderClass.get_identity_sync methods.

Additionally, the GoaBackendProviderClass.get_provider_type, GoaBackendProviderClass.get_name, GoaBackendProviderClass.build_object (this should chain up to its parent class) methods must be implemented.

Note that the GoaBackendProviderClass.add_account, GoaBackendProviderClass.refresh_account and GoaBackendProviderClass.ensure_credentials_sync methods do not need to be implemented - this type implements these methods.

Details

GoaBackendOAuthProvider

typedef struct _GoaBackendOAuthProvider GoaBackendOAuthProvider;

The GoaBackendOAuthProvider structure contains only private data and should only be accessed using the provided API.


struct GoaBackendOAuthProviderClass

struct GoaBackendOAuthProviderClass {
  GoaBackendProviderClass parent_class;

  /* pure virtual */
  const gchar *(*get_consumer_key)      (GoaBackendOAuthProvider  *provider);
  const gchar *(*get_consumer_secret)   (GoaBackendOAuthProvider  *provider);
  const gchar *(*get_request_uri)       (GoaBackendOAuthProvider  *provider);
  const gchar *(*get_authorization_uri) (GoaBackendOAuthProvider  *provider);
  const gchar *(*get_token_uri)         (GoaBackendOAuthProvider  *provider);
  const gchar *(*get_callback_uri)      (GoaBackendOAuthProvider  *provider);

  gchar       *(*get_identity_sync)      (GoaBackendOAuthProvider  *provider,
                                          const gchar              *access_token,
                                          const gchar              *access_token_secret,
                                          gchar                   **out_name,
                                          GCancellable             *cancellable,
                                          GError                  **error);

  /* virtual but with default implementation */
  gchar     *(*build_authorization_uri)  (GoaBackendOAuthProvider  *provider,
                                         const gchar               *authorization_uri,
                                         const gchar               *escaped_oauth_token);
  gboolean   (*get_use_external_browser) (GoaBackendOAuthProvider  *provider);
  gchar    **(*get_request_uri_params)   (GoaBackendOAuthProvider  *provider);
};

Class structure for GoaBackendOAuthProvider.

GoaBackendProviderClass parent_class;

The parent class.

get_consumer_key ()

Virtual function for goa_backend_oauth_provider_get_consumer_key().

get_consumer_secret ()

Virtual function for goa_backend_oauth_provider_get_consumer_secret().

get_request_uri ()

Virtual function for goa_backend_oauth_provider_get_request_uri().

get_authorization_uri ()

Virtual function for goa_backend_oauth_provider_get_authorization_uri().

get_token_uri ()

Virtual function for goa_backend_oauth_provider_get_token_uri().

get_callback_uri ()

Virtual function for goa_backend_oauth_provider_get_callback_uri().

get_identity_sync ()

Virtual function for goa_backend_oauth_provider_get_identity_sync().

build_authorization_uri ()

Virtual function for goa_backend_oauth_provider_build_authorization_uri().

get_use_external_browser ()

Virtual function for goa_backend_oauth_provider_get_use_external_browser().

get_request_uri_params ()

Virtual function for goa_backend_oauth_provider_get_request_uri_params().

goa_backend_oauth_provider_get_request_uri ()

const gchar *       goa_backend_oauth_provider_get_request_uri
                                                        (GoaBackendOAuthProvider *provider);

Gets the request uri.

http://tools.ietf.org/html/rfc5849section-2.1

This is a pure virtual method - a subclass must provide an implementation.

provider :

A GoaBackendOAuthProvider.

Returns :

A string owned by provider - do not free. [transfer none]

goa_backend_oauth_provider_get_request_uri_params ()

gchar **            goa_backend_oauth_provider_get_request_uri_params
                                                        (GoaBackendOAuthProvider *provider);

Gets additional parameters for the request URI.

http://tools.ietf.org/html/rfc5849section-2.1

This is a virtual method where the default implementation returns NULL.

provider :

A GoaBackendOAuthProvider.

Returns :

NULL (for no parameters) or a NULL-terminated array of (key, value) pairs that will be added to the URI. The caller will free the returned value with g_strfreev(). [transfer full]

goa_backend_oauth_provider_get_authorization_uri ()

const gchar *       goa_backend_oauth_provider_get_authorization_uri
                                                        (GoaBackendOAuthProvider *provider);

Gets the authorization uri.

http://tools.ietf.org/html/rfc5849section-2.2

This is a pure virtual method - a subclass must provide an implementation.

provider :

A GoaBackendOAuthProvider.

Returns :

A string owned by provider - do not free. [transfer none]

goa_backend_oauth_provider_get_token_uri ()

const gchar *       goa_backend_oauth_provider_get_token_uri
                                                        (GoaBackendOAuthProvider *provider);

Gets the token uri.

http://tools.ietf.org/html/rfc5849section-2.3

This is a pure virtual method - a subclass must provide an implementation.

provider :

A GoaBackendOAuthProvider.

Returns :

A string owned by provider - do not free. [transfer none]

goa_backend_oauth_provider_get_callback_uri ()

const gchar *       goa_backend_oauth_provider_get_callback_uri
                                                        (GoaBackendOAuthProvider *provider);

Gets the callback uri.

http://tools.ietf.org/html/rfc5849section-2.1

This is a pure virtual method - a subclass must provide an implementation.

provider :

A GoaBackendOAuthProvider.

Returns :

A string owned by provider - do not free. [transfer none]

goa_backend_oauth_provider_get_consumer_key ()

const gchar *       goa_backend_oauth_provider_get_consumer_key
                                                        (GoaBackendOAuthProvider *provider);

Gets the consumer key identifying the client.

This is a pure virtual method - a subclass must provide an implementation.

provider :

A GoaBackendOAuthProvider.

Returns :

A string owned by provider - do not free. [transfer none]

goa_backend_oauth_provider_get_consumer_secret ()

const gchar *       goa_backend_oauth_provider_get_consumer_secret
                                                        (GoaBackendOAuthProvider *provider);

Gets the consumer secret identifying the client.

This is a pure virtual method - a subclass must provide an implementation.

provider :

A GoaBackendOAuthProvider.

Returns :

A string owned by provider - do not free. [transfer none]

goa_backend_oauth_provider_build_authorization_uri ()

gchar *             goa_backend_oauth_provider_build_authorization_uri
                                                        (GoaBackendOAuthProvider *provider,
                                                         const gchar *authorization_uri,
                                                         const gchar *escaped_oauth_token);

Builds the URI that can be opened in a web browser (or embedded web browser widget) to start authenticating an user.

The default implementation just returns the expected URI (e.g. http://example.com/dialog/oauth?auth_token=1234567890) - override (and chain up) if you e.g. need to to pass additional parameters.

The authorization_uri parameter originate from the result of the the goa_backend_oauth_provider_get_authorization_uri() method. The escaped_oauth_token parameter is the temporary credentials identifier escaped using g_uri_escape_string().

provider :

A GoaBackendOAuthProvider.

authorization_uri :

An authorization URI.

escaped_oauth_token :

An escaped oauth token.

Returns :

An authorization URI that must be freed with g_free(). [transfer full]

goa_backend_oauth_provider_get_use_external_browser ()

gboolean            goa_backend_oauth_provider_get_use_external_browser
                                                        (GoaBackendOAuthProvider *provider);

Returns whether an external browser (the users default browser) should be used for user interaction.

If an external browser is used, then the dialogs presented in goa_backend_provider_add_account() and goa_backend_provider_refresh_account() will show a simple "Paste authorization code here" instructions along with an entry and button.

This is a virtual method where the default implementation returns FALSE.

provider :

A GoaBackendOAuthProvider.

Returns :

TRUE if the user interaction should happen in an external browser, FALSE to use an embedded browser widget.

goa_backend_oauth_provider_get_identity_sync ()

gchar *             goa_backend_oauth_provider_get_identity_sync
                                                        (GoaBackendOAuthProvider *provider,
                                                         const gchar *access_token,
                                                         const gchar *access_token_secret,
                                                         gchar **out_name,
                                                         GCancellable *cancellable,
                                                         GError **error);

Method that returns the identity corresponding to access_token and access_token_secret.

The identity is needed because all authentication happens out of band. The only requirement is that the returned identity is unique - for example, for GoaBackendGoogleProvider the returned identity is the email address, for GoaBackendFacebookProvider it's the user name. In addition to the identity, an implementation also returns a name in out_name that is more suitable for presentation (the identity could be a GUID for example) and doesn't have to be unique.

The calling thread is blocked while the identity is obtained.

This is a pure virtual method - a subclass must provide an implementation.

provider :

A GoaBackendOAuthProvider.

access_token :

A valid OAuth 1.0 access token.

access_token_secret :

The valid secret for access_token.

out_name :

Return location for name or NULL. [out]

cancellable :

A GCancellable or NULL. [allow-none]

error :

Return location for error or NULL.

Returns :

The identity or NULL if error is set. The returned string must be freed with g_free().

goa_backend_oauth_provider_get_access_token_sync ()

gchar *             goa_backend_oauth_provider_get_access_token_sync
                                                        (GoaBackendOAuthProvider *provider,
                                                         GoaObject *object,
                                                         gboolean force_refresh,
                                                         gchar **out_access_token_secret,
                                                         gint *out_access_token_expires_in,
                                                         GCancellable *cancellable,
                                                         GError **error);

Synchronously gets an access token for object. The calling thread is blocked while the operation is pending.

The resulting token is typically read from the local cache so most of the time only a local roundtrip to the storage for the token cache (e.g. gnome-keyring-daemon) is needed. However, the operation may involve refreshing the token with the service provider so a full network round-trip may be needed.

Note that multiple calls are serialized to avoid multiple outstanding requests to the service provider.

This operation may fail if e.g. unable to refresh the credentials or if network connectivity is not available. Note that even if a token is returned, the returned token isn't guaranteed to work - use goa_backend_provider_ensure_credentials_sync() if you need stronger guarantees.

provider :

A GoaBackendOAuthProvider.

object :

A GoaObject.

force_refresh :

If set to TRUE, forces a refresh of the access token, if possible.

out_access_token_secret :

The secret for the return access token. [out]

out_access_token_expires_in :

Return location for how many seconds the returned token is valid for (0 if unknown) or NULL. [out]

cancellable :

A GCancellable or NULL. [allow-none]

error :

Return location for error or NULL.

Returns :

The access token or NULL if error is set. The returned string must be freed with g_free().