RestProxy

## RestProxy RestProxy |

## Synopsis

    struct              RestProxy;
    struct              RestProxyClass;
    #define             REST_PROXY_ERROR
    enum                RestProxyError;
    RestProxy *         rest_proxy_new                      (const gchar *url_format,
                                                             gboolean binding_required);
    gboolean            rest_proxy_bind                     (RestProxy *proxy,
                                                             ...);
    gboolean            rest_proxy_bind_valist              (RestProxy *proxy,
                                                             va_list params);
    void                rest_proxy_set_user_agent           (RestProxy *proxy,
                                                             const char *user_agent);
    const gchar *       rest_proxy_get_user_agent           (RestProxy *proxy);
    RestProxyCall *     rest_proxy_new_call                 (RestProxy *proxy);
    gboolean            rest_proxy_simple_run               (RestProxy *proxy,
                                                             gchar **payload,
                                                             goffset *len,
                                                             GError **error,
                                                             ...);
    gboolean            rest_proxy_simple_run_valist        (RestProxy *proxy,
                                                             gchar **payload,
                                                             goffset *len,
                                                             GError **error,
                                                             va_list params);

## Object Hierarchy

      GObject
       +----RestProxy
             +----FlickrProxy
             +----LastfmProxy
             +----OAuth2Proxy
             +----OAuthProxy

## Properties

      "binding-required"         gboolean              : Read / Write
      "disable-cookies"          gboolean              : Read / Write / Construct Only
      "password"                 gchar*                : Read / Write
      "ssl-strict"               gboolean              : Read / Write
      "url-format"               gchar*                : Read / Write
      "user-agent"               gchar*                : Read / Write
      "username"                 gchar*                : Read / Write

## Signals

      "authenticate"                                   : Run Last

## Description

## Details

### struct RestProxy

    struct RestProxy;

RestProxy has no publicly available members.

### struct RestProxyClass

    struct RestProxyClass {
      gboolean (*bind_valist)(RestProxy *proxy, va_list params);
      RestProxyCall *(*new_call)(RestProxy *proxy);
      gboolean (*simple_run_valist)(RestProxy *proxy, gchar **payload,
          goffset *len, GError **error, va_list params);
      gboolean (*authenticate)(RestProxy *proxy, RestProxyAuth *auth, gboolean retrying);
    };

Class structure for RestProxy for subclasses to implement specialised behaviour.

Typically subclasses will override `new_call` to construct a subclass of RestProxyCall.

`bind_valist` () | Virtual function called to bind parameters.
`new_call` () | Virtual function called to construct a new RestProxyCall.
`simple_run_valist` () | Virtual function called when making a "simple" call.
`authenticate` () |

### REST_PROXY_ERROR

    #define REST_PROXY_ERROR rest_proxy_error_quark ()

### enum RestProxyError

    typedef enum {
      REST_PROXY_ERROR_CANCELLED = 1,
      REST_PROXY_ERROR_RESOLUTION,
      REST_PROXY_ERROR_CONNECTION,
      REST_PROXY_ERROR_SSL,
      REST_PROXY_ERROR_IO,
      REST_PROXY_ERROR_FAILED,

      REST_PROXY_ERROR_HTTP_MULTIPLE_CHOICES                = 300,
      REST_PROXY_ERROR_HTTP_MOVED_PERMANENTLY               = 301,
      REST_PROXY_ERROR_HTTP_FOUND                           = 302,
      REST_PROXY_ERROR_HTTP_SEE_OTHER                       = 303,
      REST_PROXY_ERROR_HTTP_NOT_MODIFIED                    = 304,
      REST_PROXY_ERROR_HTTP_USE_PROXY                       = 305,
      REST_PROXY_ERROR_HTTP_THREEOHSIX                      = 306,
      REST_PROXY_ERROR_HTTP_TEMPORARY_REDIRECT              = 307,
      REST_PROXY_ERROR_HTTP_BAD_REQUEST                     = 400,
      REST_PROXY_ERROR_HTTP_UNAUTHORIZED                    = 401,
      REST_PROXY_ERROR_HTTP_FOUROHTWO                       = 402,
      REST_PROXY_ERROR_HTTP_FORBIDDEN                       = 403,
      REST_PROXY_ERROR_HTTP_NOT_FOUND                       = 404,
      REST_PROXY_ERROR_HTTP_METHOD_NOT_ALLOWED              = 405,
      REST_PROXY_ERROR_HTTP_NOT_ACCEPTABLE                  = 406,
      REST_PROXY_ERROR_HTTP_PROXY_AUTHENTICATION_REQUIRED   = 407,
      REST_PROXY_ERROR_HTTP_REQUEST_TIMEOUT                 = 408,
      REST_PROXY_ERROR_HTTP_CONFLICT                        = 409,
      REST_PROXY_ERROR_HTTP_GONE                            = 410,
      REST_PROXY_ERROR_HTTP_LENGTH_REQUIRED                 = 411,
      REST_PROXY_ERROR_HTTP_PRECONDITION_FAILED             = 412,
      REST_PROXY_ERROR_HTTP_REQUEST_ENTITY_TOO_LARGE        = 413,
      REST_PROXY_ERROR_HTTP_REQUEST_URI_TOO_LONG            = 414,
      REST_PROXY_ERROR_HTTP_UNSUPPORTED_MEDIA_TYPE          = 415,
      REST_PROXY_ERROR_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE = 416,
      REST_PROXY_ERROR_HTTP_EXPECTATION_FAILED              = 417,
      REST_PROXY_ERROR_HTTP_INTERNAL_SERVER_ERROR           = 500,
      REST_PROXY_ERROR_HTTP_NOT_IMPLEMENTED                 = 501,
      REST_PROXY_ERROR_HTTP_BAD_GATEWAY                     = 502,
      REST_PROXY_ERROR_HTTP_SERVICE_UNAVAILABLE             = 503,
      REST_PROXY_ERROR_HTTP_GATEWAY_TIMEOUT                 = 504,
      REST_PROXY_ERROR_HTTP_HTTP_VERSION_NOT_SUPPORTED      = 505,
    } RestProxyError;

Error domain used when returning errors from a RestProxy.

### rest_proxy_new ()

    RestProxy *         rest_proxy_new                      (const gchar *url_format,
                                                             gboolean binding_required);

Create a new RestProxy for the specified endpoint `url_format`, using the "GET" method.

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.

`url_format` : | the endpoint URL
`binding_required` : | whether the URL needs to be bound before calling
Returns : | A new RestProxy.

### rest_proxy_bind ()

    gboolean            rest_proxy_bind                     (RestProxy *proxy,
                                                             ...);

### rest_proxy_bind_valist ()

    gboolean            rest_proxy_bind_valist              (RestProxy *proxy,
                                                             va_list params);

### rest_proxy_set_user_agent ()

    void                rest_proxy_set_user_agent           (RestProxy *proxy,
                                                             const char *user_agent);

### rest_proxy_get_user_agent ()

    const gchar *       rest_proxy_get_user_agent           (RestProxy *proxy);

### rest_proxy_new_call ()

    RestProxyCall *     rest_proxy_new_call                 (RestProxy *proxy);

Create a new RestProxyCall for making a call to the web service. This call is one-shot and should not be re-used for making multiple calls.

`proxy` : | the RestProxy
Returns : | a new RestProxyCall. [transfer full]

### rest_proxy_simple_run ()

    gboolean            rest_proxy_simple_run               (RestProxy *proxy,
                                                             gchar **payload,
                                                             goffset *len,
                                                             GError **error,
                                                             ...);

### rest_proxy_simple_run_valist ()

    gboolean            rest_proxy_simple_run_valist        (RestProxy *proxy,
                                                             gchar **payload,
                                                             goffset *len,
                                                             GError **error,
                                                             va_list params);

## Property Details

### The `"binding-required"` property

      "binding-required"         gboolean              : Read / Write

Whether the URL format requires binding.

Default value: FALSE

### The `"disable-cookies"` property

      "disable-cookies"          gboolean              : Read / Write / Construct Only

Whether to disable cookie support.

Default value: FALSE

### The `"password"` property

      "password"                 gchar*                : Read / Write

The password for authentication.

Default value: NULL

### The `"ssl-strict"` property

      "ssl-strict"               gboolean              : Read / Write

Whether certificate errors should be considered a connection error.

Default value: TRUE

### The `"url-format"` property

      "url-format"               gchar*                : Read / Write

Format string for the RESTful url.

Default value: NULL

### The `"user-agent"` property

      "user-agent"               gchar*                : Read / Write

The User-Agent of the client.

Default value: NULL

### The `"username"` property

      "username"                 gchar*                : Read / Write

The username for authentication.

Default value: NULL

## Signal Details

### The `"authenticate"` signal

    gboolean            user_function                      (RestProxy     *proxy,
                                                            RestProxyAuth *retrying,
                                                            gboolean       arg2,
                                                            gpointer       user_data)      : Run Last

Emitted when the proxy requires authentication. If credentials are available, set the 'username' and 'password' properties on `proxy` and return TRUE from the callback. This will cause the signal emission to stop, and librest will try to connect with these credentials If these credentials fail, the signal will be emitted again, with `retrying` set to `TRUE`, which will continue until FALSE is returned from the callback.

If you call `rest_proxy_auth_pause()` on `auth` before returning, then you can the authentication credentials on the RestProxy object asynchronously. You have to make sure that `auth` does not get destroyed with `g_object_ref()`. You can then unpause the authentication with `rest_proxy_auth_unpause()` when everything is ready for it to continue.

`proxy` : | the proxy
`retrying` : | `TRUE` if this is the second (or later) attempt
`user_data` : | user data set when the signal handler was connected.