GoaOAuthProvider: GNOME Online Accounts Reference Manual

## GoaOAuthProvider GoaOAuthProvider — Abstract base class for OAuth 1.0a providers |

## Functions

const gchar * | goa_oauth_provider_get_authentication_cookie ()
const gchar * | goa_oauth_provider_get_request_uri ()
gchar ** | goa_oauth_provider_get_request_uri_params ()
const gchar * | goa_oauth_provider_get_authorization_uri ()
const gchar * | goa_oauth_provider_get_token_uri ()
const gchar * | goa_oauth_provider_get_callback_uri ()
const gchar * | goa_oauth_provider_get_consumer_key ()
const gchar * | goa_oauth_provider_get_consumer_secret ()
gchar * | goa_oauth_provider_build_authorization_uri ()
gboolean | goa_oauth_provider_get_use_mobile_browser ()
gboolean | goa_oauth_provider_is_deny_node ()
gboolean | goa_oauth_provider_is_identity_node ()
gboolean | goa_oauth_provider_is_password_node ()
void | goa_oauth_provider_add_account_key_values ()
gchar * | goa_oauth_provider_get_identity_sync ()
gchar * | goa_oauth_provider_get_access_token_sync ()
gchar * | goa_oauth_provider_parse_request_token_error ()

## Types and Values

struct | GoaOAuthProvider
struct | GoaOAuthProviderClass

## Object Hierarchy

        GObject
        ╰── GoaProvider
            ╰── GoaOAuthProvider
                ╰── GoaFlickrProvider

## Description

GoaOAuthProvider 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 GoaOAuthProviderClass.get_consumer_key, GoaOAuthProviderClass.get_consumer_secret, GoaOAuthProviderClass.get_request_uri, GoaOAuthProviderClass.get_authorization_uri, GoaOAuthProviderClass.get_token_uri, GoaOAuthProviderClass.get_callback_uri and GoaOAuthProviderClass.get_identity_sync methods.

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

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

## Functions

### goa_oauth_provider_get_authentication_cookie ()

    const gchar *
    goa_oauth_provider_get_authentication_cookie
                                   (GoaOAuthProvider *provider);

Gets the name of a cookie whose presence indicates that the user has been able to log in during the authorization step. This is used to modify the embedded web browser UI that is presented to the user.

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

#### Parameters

provider | A GoaOAuthProvider. |

#### Returns

A string owned by `provider` - do not free.

[transfer none]

### goa_oauth_provider_get_request_uri ()

    const gchar *
    goa_oauth_provider_get_request_uri (GoaOAuthProvider *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.

#### Parameters

provider | A GoaOAuthProvider. |

#### Returns

A string owned by `provider` - do not free.

[transfer none]

### goa_oauth_provider_get_request_uri_params ()

    gchar **
    goa_oauth_provider_get_request_uri_params
                                   (GoaOAuthProvider *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`.

#### Parameters

provider | A GoaOAuthProvider. |

#### 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_oauth_provider_get_authorization_uri ()

    const gchar *
    goa_oauth_provider_get_authorization_uri
                                   (GoaOAuthProvider *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.

#### Parameters

provider | A GoaOAuthProvider. |

#### Returns

A string owned by `provider` - do not free.

[transfer none]

### goa_oauth_provider_get_token_uri ()

    const gchar *
    goa_oauth_provider_get_token_uri (GoaOAuthProvider *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.

#### Parameters

provider | A GoaOAuthProvider. |

#### Returns

A string owned by `provider` - do not free.

[transfer none]

### goa_oauth_provider_get_callback_uri ()

    const gchar *
    goa_oauth_provider_get_callback_uri (GoaOAuthProvider *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.

#### Parameters

provider | A GoaOAuthProvider. |

#### Returns

A string owned by `provider` - do not free.

[transfer none]

### goa_oauth_provider_get_consumer_key ()

    const gchar *
    goa_oauth_provider_get_consumer_key (GoaOAuthProvider *provider);

Gets the consumer key identifying the client.

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

#### Parameters

provider | A GoaOAuthProvider. |

#### Returns

A string owned by `provider` - do not free.

[transfer none]

### goa_oauth_provider_get_consumer_secret ()

    const gchar *
    goa_oauth_provider_get_consumer_secret
                                   (GoaOAuthProvider *provider);

Gets the consumer secret identifying the client.

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

#### Parameters

provider | A GoaOAuthProvider. |

#### Returns

A string owned by `provider` - do not free.

[transfer none]

### goa_oauth_provider_build_authorization_uri ()

    gchar *
    goa_oauth_provider_build_authorization_uri
                                   (GoaOAuthProvider *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_oauth_provider_get_authorization_uri()` method. The `escaped_oauth_token` parameter is the temporary credentials identifier escaped using `g_uri_escape_string()`.

#### Parameters

provider | A GoaOAuthProvider. |
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_oauth_provider_get_use_mobile_browser ()

    gboolean
    goa_oauth_provider_get_use_mobile_browser
                                   (GoaOAuthProvider *provider);

Returns whether there is a need for the embedded browser to identify itself as running on a mobile phone in order to get a more compact version of the approval page.

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

#### Parameters

provider | A GoaOAuthProvider. |

#### Returns

`TRUE` if the embedded browser should identify itself as running on a mobile platform, `FALSE` otherwise.

### goa_oauth_provider_is_deny_node ()

    gboolean
    goa_oauth_provider_is_deny_node (GoaOAuthProvider *provider,
                                     WebKitDOMNode *node);

Checks whether `node` is the HTML UI element that the user can use to deny permission to access his account. Usually they are either a WebKitDOMHTMLButtonElement or a WebKitDOMHTMLInputElement.

Please note that providers may have multiple such elements in their UI and this method should catch all of them.

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

#### Parameters

provider | A GoaOAuthProvider. |
node | A WebKitDOMNode. |

#### Returns

`TRUE` if the `node` can be used to deny permission.

### goa_oauth_provider_is_identity_node ()

    gboolean
    goa_oauth_provider_is_identity_node (GoaOAuthProvider *provider,
                                         WebKitDOMHTMLInputElement *element);

Checks whether `element` is the HTML UI element that the user can use to identify herself at the provider.

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

#### Parameters

provider | A GoaOAuthProvider. |
element | A WebKitDOMHTMLInputElement. |

#### Returns

`TRUE` if the `element` can be used to deny permission.

### goa_oauth_provider_is_password_node ()

    gboolean
    goa_oauth_provider_is_password_node (GoaOAuthProvider *provider,
                                         WebKitDOMHTMLInputElement *element);

Checks whether `element` is the HTML UI element that the user can use to enter her password. This can be used to offer a GoaPasswordBased interface by saving the user's password. Providers usually frown upon doing this, so this is not recommended.

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

#### Parameters

provider | A GoaOAuthProvider. |
element | A WebKitDOMHTMLInputElement |

#### Returns

`TRUE` if `element` can be used to enter the password.

### goa_oauth_provider_add_account_key_values ()

    void
    goa_oauth_provider_add_account_key_values
                                   (GoaOAuthProvider *provider,
                                    GVariantBuilder *builder);

Hook for implementations to add key/value pairs to the key-file when creating an account.

This is a virtual method where the default implementation does nothing.

#### Parameters

provider | A GoaProvider. |
builder | A GVariantBuilder for a `a{ss}` variant. |

### goa_oauth_provider_get_identity_sync ()

    gchar *
    goa_oauth_provider_get_identity_sync (GoaOAuthProvider *provider,
                                          const gchar *access_token,
                                          const gchar *access_token_secret,
                                          gchar **out_presentation_identity,
                                          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. In addition to the identity, an implementation also returns a presentation identity that is more suitable for presentation (the identity could be a GUID for example).

The calling thread is blocked while the identity is obtained.

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

#### Parameters

provider | A GoaOAuthProvider. |
access_token | A valid OAuth 1.0 access token. |
access_token_secret | The valid secret for `access_token` . |
out_presentation_identity | Return location for presentation identity 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_oauth_provider_get_access_token_sync ()

    gchar *
    goa_oauth_provider_get_access_token_sync
                                   (GoaOAuthProvider *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_provider_ensure_credentials_sync()` if you need stronger guarantees.

#### Parameters

provider | A GoaOAuthProvider. |
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()`.

### goa_oauth_provider_parse_request_token_error ()

    gchar *
    goa_oauth_provider_parse_request_token_error
                                   (GoaOAuthProvider *provider,
                                    RestProxyCall *call);

Tries to parse the headers and payload within `call` to provide a human readable error message in case the request token could not be fetched.

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

#### Parameters

provider | A GoaOAuthProvider. |
call | The RestProxyCall that was used to fetch the request token. |

#### Returns

A human readable error message or `NULL` if the cause of the error could not be determined. The returned string must be freed with `g_free()`.

## Types and Values

### struct GoaOAuthProvider

    struct GoaOAuthProvider;

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

### struct GoaOAuthProviderClass

    struct GoaOAuthProviderClass {
      GoaProviderClass parent_class;

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

      gchar       *(*get_identity_sync)            (GoaOAuthProvider             *provider,
                                                    const gchar                  *access_token,
                                                    const gchar                  *access_token_secret,
                                                    gchar                       **out_presentation_identity,
                                                    GCancellable                 *cancellable,
                                                    GError                      **error);

      gchar       *(*parse_request_token_error)    (GoaOAuthProvider             *provider,
                                                    RestProxyCall                *call);

      /* virtual but with default implementation */
      gchar       *(*build_authorization_uri)      (GoaOAuthProvider             *provider,
                                                    const gchar                  *authorization_uri,
                                                    const gchar                  *escaped_oauth_token);
      gboolean     (*get_use_mobile_browser)       (GoaOAuthProvider             *provider);
      gchar      **(*get_request_uri_params)       (GoaOAuthProvider             *provider);
      void         (*add_account_key_values)       (GoaOAuthProvider             *provider,
                                                    GVariantBuilder              *builder);

      /* pure virtual */
      gboolean     (*is_identity_node)             (GoaOAuthProvider             *provider,
                                                    WebKitDOMHTMLInputElement    *element);

      /* virtual but with default implementation */
      gboolean     (*is_deny_node)                 (GoaOAuthProvider             *provider,
                                                    WebKitDOMNode                *node);
      gboolean     (*is_password_node)             (GoaOAuthProvider             *provider,
                                                    WebKitDOMHTMLInputElement    *element);
    };

Class structure for GoaOAuthProvider.

#### Members

`get_consumer_key` () | Virtual function for `goa_oauth_provider_get_consumer_key()`. |
`get_consumer_secret` () | Virtual function for `goa_oauth_provider_get_consumer_secret()`. |
`get_request_uri` () | Virtual function for `goa_oauth_provider_get_request_uri()`. |
`get_authorization_uri` () | Virtual function for `goa_oauth_provider_get_authorization_uri()`. |
`get_token_uri` () | Virtual function for `goa_oauth_provider_get_token_uri()`. |
`get_callback_uri` () | Virtual function for `goa_oauth_provider_get_callback_uri()`. |
`get_authentication_cookie` () | Virtual function for `goa_oauth_provider_get_authentication_cookie()`. |
`get_identity_sync` () | Virtual function for `goa_oauth_provider_get_identity_sync()`. |
`parse_request_token_error` () | Virtual function for `goa_oauth_provider_parse_request_token_error()`. |
`build_authorization_uri` () | Virtual function for `goa_oauth_provider_build_authorization_uri()`. |
`get_use_mobile_browser` () | Virtual function for `goa_oauth_provider_get_use_mobile_browser()`. |
`get_request_uri_params` () | Virtual function for `goa_oauth_provider_get_request_uri_params()`. |
`add_account_key_values` () | Virtual function for `goa_oauth_provider_add_account_key_values()`. |
`is_identity_node` () | Virtual function for `goa_oauth_provider_is_identity_node()`. |
`is_deny_node` () | Virtual function for `goa_oauth_provider_is_deny_node()`. |
`is_password_node` () | Virtual function for `goa_oauth_provider_is_password_node()`. |