OAuthProxy

## OAuthProxy OAuthProxy |

## Synopsis

                        OAuthProxy;
    enum                OAuthSignatureMethod;
    RestProxy *         oauth_proxy_new                     (const char *consumer_key,
                                                             const char *consumer_secret,
                                                             const gchar *url_format,
                                                             gboolean binding_required);
    RestProxy *         oauth_proxy_new_echo_proxy          (OAuthProxy *proxy,
                                                             const char *service_url,
                                                             const gchar *url_format,
                                                             gboolean binding_required);
    RestProxy *         oauth_proxy_new_with_token          (const char *consumer_key,
                                                             const char *consumer_secret,
                                                             const char *token,
                                                             const char *token_secret,
                                                             const gchar *url_format,
                                                             gboolean binding_required);
    void                (*OAuthProxyAuthCallback)           (OAuthProxy *proxy,
                                                             const GError *error,
                                                             GObject *weak_object,
                                                             gpointer userdata);
    gboolean            oauth_proxy_auth_step               (OAuthProxy *proxy,
                                                             const char *function,
                                                             GError **error);
    gboolean            oauth_proxy_auth_step_async         (OAuthProxy *proxy,
                                                             const char *function,
                                                             OAuthProxyAuthCallback callback,
                                                             GObject *weak_object,
                                                             gpointer user_data,
                                                             GError **error_out);
    gboolean            oauth_proxy_request_token           (OAuthProxy *proxy,
                                                             const char *function,
                                                             const char *callback_uri,
                                                             GError **error);
    gboolean            oauth_proxy_request_token_async     (OAuthProxy *proxy,
                                                             const char *function,
                                                             const char *callback_uri,
                                                             OAuthProxyAuthCallback callback,
                                                             GObject *weak_object,
                                                             gpointer user_data,
                                                             GError **error);
    gboolean            oauth_proxy_is_oauth10a             (OAuthProxy *proxy);
    gboolean            oauth_proxy_access_token            (OAuthProxy *proxy,
                                                             const char *function,
                                                             const char *verifier,
                                                             GError **error);
    gboolean            oauth_proxy_access_token_async      (OAuthProxy *proxy,
                                                             const char *function,
                                                             const char *verifier,
                                                             OAuthProxyAuthCallback callback,
                                                             GObject *weak_object,
                                                             gpointer user_data,
                                                             GError **error);
    const char *        oauth_proxy_get_token               (OAuthProxy *proxy);
    void                oauth_proxy_set_token               (OAuthProxy *proxy,
                                                             const char *token);
    const char *        oauth_proxy_get_token_secret        (OAuthProxy *proxy);
    void                oauth_proxy_set_token_secret        (OAuthProxy *proxy,
                                                             const char *token_secret);
    const char *        oauth_proxy_get_signature_host      (OAuthProxy *proxy);
    void                oauth_proxy_set_signature_host      (OAuthProxy *proxy,
                                                             const char *signature_host);

## Object Hierarchy

      GObject
       +----RestProxy
             +----OAuthProxy

## Properties

      "consumer-key"             gchar*                : Read / Write / Construct Only
      "consumer-secret"          gchar*                : Read / Write / Construct Only
      "signature-host"           gchar*                : Read / Write
      "signature-method"         OAuthSignatureMethod  : Read / Write
      "token"                    gchar*                : Read / Write
      "token-secret"             gchar*                : Read / Write

## Description

## Details

### OAuthProxy

    typedef struct _OAuthProxy OAuthProxy;

OAuthProxy has no publicly available members.

### enum OAuthSignatureMethod

    typedef enum {
      PLAINTEXT,
      HMAC_SHA1
    } OAuthSignatureMethod;

The signature method to use when signing method calls. `PLAINTEXT` is only recommended for testing, in general `HMAC_SHA1` is well supported and more secure.

`PLAINTEXT` | plain text signatures (not recommended)
`HMAC_SHA1` | HMAC-SHA1 signatures (recommended)

### oauth_proxy_new ()

    RestProxy *         oauth_proxy_new                     (const char *consumer_key,
                                                             const char *consumer_secret,
                                                             const gchar *url_format,
                                                             gboolean binding_required);

Create a new OAuthProxy for the specified endpoint `url_format`, using the specified API key and secret.

This proxy won't have the Token or Token Secret set so as such will be unauthorised. If the tokens are unknown then `oauth_proxy_request_token()` and `oauth_proxy_access_token()` should be called to do the OAuth authorisation, or the tokens should be set using `oauth_proxy_set_token()` and `oauth_proxy_set_token_secret()`.

Set `binding_required` to `TRUE` if the URL contains string formatting operations (for example "http://foo.com/%s". These must be expanded using `rest_proxy_bind()` before invoking the proxy.

`consumer_key` : | the Consumer Key
`consumer_secret` : | the Consumer Secret
`url_format` : | the endpoint URL
`binding_required` : | whether the URL needs to be bound before calling
Returns : | A new OAuthProxy.

### oauth_proxy_new_echo_proxy ()

    RestProxy *         oauth_proxy_new_echo_proxy          (OAuthProxy *proxy,
                                                             const char *service_url,
                                                             const gchar *url_format,
                                                             gboolean binding_required);

### oauth_proxy_new_with_token ()

    RestProxy *         oauth_proxy_new_with_token          (const char *consumer_key,
                                                             const char *consumer_secret,
                                                             const char *token,
                                                             const char *token_secret,
                                                             const gchar *url_format,
                                                             gboolean binding_required);

Create a new OAuthProxy for the specified endpoint `url_format`, using the specified API key and secret.

`token` and `token_secret` are used for the Access Token and Token Secret, so if they are still valid then this proxy is authorised.

Set `binding_required` to `TRUE` if the URL contains string formatting operations (for example "http://foo.com/%s". These must be expanded using `rest_proxy_bind()` before invoking the proxy.

`consumer_key` : | the Consumer Key
`consumer_secret` : | the Consumer Secret
`token` : | the Access Token
`token_secret` : | the Token Secret
`url_format` : | the endpoint URL
`binding_required` : | whether the URL needs to be bound before calling
Returns : | A new OAuthProxy.

### OAuthProxyAuthCallback ()

    void                (*OAuthProxyAuthCallback)           (OAuthProxy *proxy,
                                                             const GError *error,
                                                             GObject *weak_object,
                                                             gpointer userdata);

Callback from `oauth_proxy_request_token_async()` and `oauth_proxy_access_token_async()`.

`proxy` : | the OAuthProxy
`error` : | a GError if the authentication failed, otherwise `NULL`
`weak_object` : | the weak object passed to the caller
`userdata` : | the user data passed to the caller

### oauth_proxy_auth_step ()

    gboolean            oauth_proxy_auth_step               (OAuthProxy *proxy,
                                                             const char *function,
                                                             GError **error);

Perform an OAuth authorisation step. This calls `function` and then updates the token and token secret in the proxy.

`proxy` must not require binding, the function will be invoked using `rest_proxy_call_set_function()`.

`proxy` : | an OAuthProxy
`function` : | the function to invoke on the proxy
`error` : | return location for a GError

### oauth_proxy_auth_step_async ()

    gboolean            oauth_proxy_auth_step_async         (OAuthProxy *proxy,
                                                             const char *function,
                                                             OAuthProxyAuthCallback callback,
                                                             GObject *weak_object,
                                                             gpointer user_data,
                                                             GError **error_out);

Perform an OAuth authorisation step. This calls `function` and then updates the token and token secret in the proxy.

`proxy` must not require binding, the function will be invoked using `rest_proxy_call_set_function()`.

`proxy` : | an OAuthProxy
`function` : | the function to invoke on the proxy
`callback` : | the callback to invoke when authorisation is complete
`weak_object` : | the GObject to weakly reference and tie the lifecycle too
`user_data` : | data to pass to `callback`
`error_out` : | a GError, or `NULL`

### oauth_proxy_request_token ()

    gboolean            oauth_proxy_request_token           (OAuthProxy *proxy,
                                                             const char *function,
                                                             const char *callback_uri,
                                                             GError **error);

Perform the Request Token phase of OAuth, invoking `function` (defaulting to "request_token" if `function` is NULL).

The value of `callback` depends on whether you wish to use OAuth 1.0 or 1.0a. If you wish to use 1.0 then callback must be NULL. To use 1.0a then `callback` should either be your callback URI, or "oob" (out-of-band).

`proxy` : | an OAuthProxy
`function` : | the function name to invoke
`callback_uri` : | the callback URI
`error` : | a GError, or `NULL`
Returns : | `TRUE` on success, or `FALSE` on failure. On failure `error` is set.

### oauth_proxy_request_token_async ()

    gboolean            oauth_proxy_request_token_async     (OAuthProxy *proxy,
                                                             const char *function,
                                                             const char *callback_uri,
                                                             OAuthProxyAuthCallback callback,
                                                             GObject *weak_object,
                                                             gpointer user_data,
                                                             GError **error);

Perform the Request Token phase of OAuth, invoking `function` (defaulting to "request_token" if `function` is NULL).

The value of `callback` depends on whether you wish to use OAuth 1.0 or 1.0a. If you wish to use 1.0 then callback must be NULL. To use 1.0a then `callback` should either be your callback URI, or "oob" (out-of-band).

This method will return once the method has been queued, `callback` will be invoked when it has completed.

`proxy` : | an OAuthProxy
`function` : | the function name to invoke
`callback_uri` : | the callback URI
`callback` : | a OAuthProxyAuthCallback to invoke on completion
`weak_object` : | GObject to weakly reference and tie the lifecycle of the method call too
`user_data` : | user data to pass to `callback`
`error` : | a GError, or `NULL`
Returns : | `TRUE` if the method was successfully queued, or `FALSE` on failure. On failure `error` is set.

### oauth_proxy_is_oauth10a ()

    gboolean            oauth_proxy_is_oauth10a             (OAuthProxy *proxy);

Determines if the server supports OAuth 1.0a with this proxy. This is only valid after `oauth_proxy_request_token()` or `oauth_proxy_request_token_async()` has been called.

`proxy` : | a valid OAuthProxy
Returns : | `TRUE` if the server supports OAuth 1.0a, `FALSE` otherwise.

### oauth_proxy_access_token ()

    gboolean            oauth_proxy_access_token            (OAuthProxy *proxy,
                                                             const char *function,
                                                             const char *verifier,
                                                             GError **error);

Perform the Access Token phase of OAuth, invoking `function` (defaulting to "access_token" if `function` is NULL).

`verifier` is only used if you are using OAuth 1.0a. This is either the "oauth_verifier" parameter that was passed to your callback URI, or a string that the user enters in some other manner (for example in a popup dialog) if "oob" was passed to `oauth_proxy_request_token()`. For OAuth 1.0, pass `NULL`.

`proxy` : | an OAuthProxy
`function` : | the function name to invoke
`verifier` : | the verifier
`error` : | a GError, or `NULL`
Returns : | `TRUE` on success, or `FALSE` on failure. On failure `error` is set.

### oauth_proxy_access_token_async ()

    gboolean            oauth_proxy_access_token_async      (OAuthProxy *proxy,
                                                             const char *function,
                                                             const char *verifier,
                                                             OAuthProxyAuthCallback callback,
                                                             GObject *weak_object,
                                                             gpointer user_data,
                                                             GError **error);

Perform the Access Token phase of OAuth, invoking `function` (defaulting to "access_token" if `function` is NULL).

`verifier` is only used if you are using OAuth 1.0a. This is either the "oauth_verifier" parameter that was passed to your callback URI, or a string that the user enters in some other manner (for example in a popup dialog) if "oob" was passed to `oauth_proxy_request_token()`. For OAuth 1.0, pass `NULL`.

This method will return once the method has been queued, `callback` will be invoked when it has completed.

`proxy` : | an OAuthProxy
`function` : | the function name to invoke
`verifier` : | the verifier
`callback` : | a OAuthProxyAuthCallback to invoke on completion
`weak_object` : | GObject to weakly reference and tie the lifecycle of the method call too
`user_data` : | user data to pass to `callback`
`error` : | a GError, or `NULL`
Returns : | `TRUE` if the method was successfully queued, or `FALSE` on failure. On failure `error` is set.

### oauth_proxy_get_token ()

    const char *        oauth_proxy_get_token               (OAuthProxy *proxy);

Get the current request or access token.

`proxy` : | an OAuthProxy
Returns : | the token, or `NULL` if there is no token yet. This string is owned by OAuthProxy and should not be freed.

### oauth_proxy_set_token ()

    void                oauth_proxy_set_token               (OAuthProxy *proxy,
                                                             const char *token);

Set the access token.

`proxy` : | an OAuthProxy
`token` : | the access token

### oauth_proxy_get_token_secret ()

    const char *        oauth_proxy_get_token_secret        (OAuthProxy *proxy);

Get the current request or access token secret.

`proxy` : | an OAuthProxy
Returns : | the token secret, or `NULL` if there is no token secret yet. This string is owned by OAuthProxy and should not be freed.

### oauth_proxy_set_token_secret ()

    void                oauth_proxy_set_token_secret        (OAuthProxy *proxy,
                                                             const char *token_secret);

Set the access token secret.

`proxy` : | an OAuthProxy
`token_secret` : | the access token secret

### oauth_proxy_get_signature_host ()

    const char *        oauth_proxy_get_signature_host      (OAuthProxy *proxy);

Get the signature hostname used when creating a signature base string.

`proxy` : | an OAuthProxy
Returns : | the signature hostname, or `NULL` if there is none set. This string is owned by OAuthProxy and should not be freed.

### oauth_proxy_set_signature_host ()

    void                oauth_proxy_set_signature_host      (OAuthProxy *proxy,
                                                             const char *signature_host);

Set the signature hostname used when creating a signature base string.

`proxy` : | an OAuthProxy
`signature_host` : | the signature host

## Property Details

### The `"consumer-key"` property

      "consumer-key"             gchar*                : Read / Write / Construct Only

The consumer key.

Default value: NULL

### The `"consumer-secret"` property

      "consumer-secret"          gchar*                : Read / Write / Construct Only

The consumer secret.

Default value: NULL

### The `"signature-host"` property

      "signature-host"           gchar*                : Read / Write

The base URL used in the signature string.

Default value: NULL

### The `"signature-method"` property

      "signature-method"         OAuthSignatureMethod  : Read / Write

Signature method used.

Default value: HMAC_SHA1

### The `"token"` property

      "token"                    gchar*                : Read / Write

The request or access token.

Default value: NULL

### The `"token-secret"` property

      "token-secret"             gchar*                : Read / Write

The request or access token secret.

Default value: NULL