OAuthProxy: librest Reference Manual

## OAuthProxy OAuthProxy |

## Functions

RestProxy * | oauth_proxy_new ()
RestProxy * | oauth_proxy_new_echo_proxy ()
RestProxy * | oauth_proxy_new_with_token ()
void | (*OAuthProxyAuthCallback) ()
gboolean | oauth_proxy_auth_step ()
gboolean | oauth_proxy_auth_step_async ()
gboolean | oauth_proxy_request_token ()
gboolean | oauth_proxy_request_token_async ()
gboolean | oauth_proxy_is_oauth10a ()
gboolean | oauth_proxy_access_token ()
gboolean | oauth_proxy_access_token_async ()
const char * | oauth_proxy_get_token ()
void | oauth_proxy_set_token ()
const char * | oauth_proxy_get_token_secret ()
void | oauth_proxy_set_token_secret ()
const char * | oauth_proxy_get_signature_host ()
void | oauth_proxy_set_signature_host ()

## Properties

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

## Types and Values

| OAuthProxy
enum | OAuthSignatureMethod

## Object Hierarchy

        GObject
        ╰── RestProxy
            ╰── OAuthProxy

## Description

## Functions

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

#### Parameters

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);

Create a new OAuth Echo proxy.

#### Parameters

proxy | an OAuthProxy |
service_url | the service URL |
url_format | the URL format |
binding_required | whether a binding is required |

#### Returns

a new OAuth Echo proxy.

[transfer full]

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

#### Parameters

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

#### Parameters

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);

`oauth_proxy_auth_step` is deprecated and should not be used in newly-written code.

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

#### Parameters

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);

`oauth_proxy_auth_step_async` is deprecated and should not be used in newly-written code.

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

#### Parameters

proxy | an OAuthProxy |
function | the function to invoke on the proxy |
callback | the callback to invoke when authorisation is complete. | [scope async]
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).

#### Parameters

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.

#### Parameters

proxy | an OAuthProxy |
function | the function name to invoke |
callback_uri | the callback URI |
callback | a OAuthProxyAuthCallback to invoke on completion. | [scope async]
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.

#### Parameters

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

#### Parameters

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.

#### Parameters

proxy | an OAuthProxy |
function | the function name to invoke |
verifier | the verifier |
callback | a OAuthProxyAuthCallback to invoke on completion. | [scope async]
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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

proxy | an OAuthProxy |
signature_host | the signature host |

## Types and Values

### OAuthProxy

    typedef struct _OAuthProxy OAuthProxy;

OAuthProxy has no publicly available members.

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

#### Members

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

## Property Details

### The `“consumer-key”` property

      “consumer-key”             gchar *

The consumer key.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“consumer-secret”` property

      “consumer-secret”          gchar *

The consumer secret.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“signature-host”` property

      “signature-host”           gchar *

The base URL used in the signature string.

Flags: Read / Write

Default value: NULL

### The `“signature-method”` property

      “signature-method”         OAuthSignatureMethod

Signature method used.

Flags: Read / Write

Default value: HMAC_SHA1

### The `“token”` property

      “token”                    gchar *

The request or access token.

Flags: Read / Write

Default value: NULL

### The `“token-secret”` property

      “token-secret”             gchar *

The request or access token secret.

Flags: Read / Write

Default value: NULL