RestProxy: librest Reference Manual

## RestProxy RestProxy |

## Functions

RestProxy * | rest_proxy_new ()
gboolean | rest_proxy_bind ()
gboolean | rest_proxy_bind_valist ()
void | rest_proxy_set_user_agent ()
const gchar * | rest_proxy_get_user_agent ()
void | rest_proxy_add_soup_feature ()
RestProxyCall * | rest_proxy_new_call ()
gboolean | rest_proxy_simple_run ()
gboolean | rest_proxy_simple_run_valist ()

## Properties

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

## Signals

gboolean | authenticate | Run Last

## Types and Values

struct | RestProxy
struct | RestProxyClass
#define | REST_PROXY_ERROR
enum | RestProxyError

## Object Hierarchy

        GObject
        ╰── RestProxy
            ├── FlickrProxy
            ├── LastfmProxy
            ├── OAuth2Proxy
            ╰── OAuthProxy

## Description

## Functions

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

#### Parameters

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_add_soup_feature ()

    void
    rest_proxy_add_soup_feature (RestProxy *proxy,
                                 SoupSessionFeature *feature);

This method can be used to add specific features to the SoupSession objects that are used by librest for its HTTP connections. For example, if one needs extensive control over the cookies which are used for the REST HTTP communication, it's possible to get full access to libsoup cookie API by using

      RestProxy *proxy = g_object_new(REST_TYPE_PROXY,
                                      "url-format", url,
                                      "disable-cookies", TRUE,
                                      NULL);
      SoupSessionFeature *cookie_jar = SOUP_SESSION_FEATURE(soup_cookie_jar_new ());
      rest_proxy_add_soup_feature(proxy, cookie_jar);

#### Parameters

proxy | The RestProxy |
feature | A SoupSessionFeature |

Since: 0.7.92

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

#### Parameters

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

## Types and Values

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

#### Members

`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` () | class handler for the “authenticate” signal |

### REST_PROXY_ERROR

    #define REST_PROXY_ERROR rest_proxy_error_quark ()

### enum RestProxyError

Error domain used when returning errors from a RestProxy.

#### Members

REST_PROXY_ERROR_CANCELLED | Cancelled |
REST_PROXY_ERROR_RESOLUTION | Resolution |
REST_PROXY_ERROR_CONNECTION | Connection |
REST_PROXY_ERROR_SSL | SSL |
REST_PROXY_ERROR_IO | Input/Output |
REST_PROXY_ERROR_FAILED | Failure |
REST_PROXY_ERROR_HTTP_MULTIPLE_CHOICES | HTTP/Multiple choices |
REST_PROXY_ERROR_HTTP_MOVED_PERMANENTLY | HTTP/Moved permanently |
REST_PROXY_ERROR_HTTP_FOUND | HTTP/Found |
REST_PROXY_ERROR_HTTP_SEE_OTHER | HTTP/See other |
REST_PROXY_ERROR_HTTP_NOT_MODIFIED | HTTP/Not modified |
REST_PROXY_ERROR_HTTP_USE_PROXY | HTTP/Use proxy |
REST_PROXY_ERROR_HTTP_THREEOHSIX | HTTP/306 |
REST_PROXY_ERROR_HTTP_TEMPORARY_REDIRECT | HTTP/Temporary redirect |
REST_PROXY_ERROR_HTTP_BAD_REQUEST | HTTP/Bad request |
REST_PROXY_ERROR_HTTP_UNAUTHORIZED | HTTP/Unauthorized |
REST_PROXY_ERROR_HTTP_FOUROHTWO | HTTP/402 |
REST_PROXY_ERROR_HTTP_FORBIDDEN | HTTP/Forbidden |
REST_PROXY_ERROR_HTTP_NOT_FOUND | HTTP/Not found |
REST_PROXY_ERROR_HTTP_METHOD_NOT_ALLOWED | HTTP/Method not allowed |
REST_PROXY_ERROR_HTTP_NOT_ACCEPTABLE | HTTP/Not acceptable |
REST_PROXY_ERROR_HTTP_PROXY_AUTHENTICATION_REQUIRED | HTTP/Proxy authentication required |
REST_PROXY_ERROR_HTTP_REQUEST_TIMEOUT | HTTP/Request timeout |
REST_PROXY_ERROR_HTTP_CONFLICT | HTTP/Conflict |
REST_PROXY_ERROR_HTTP_GONE | HTTP/Gone |
REST_PROXY_ERROR_HTTP_LENGTH_REQUIRED | HTTP/Length required |
REST_PROXY_ERROR_HTTP_PRECONDITION_FAILED | HTTP/Precondition failed |
REST_PROXY_ERROR_HTTP_REQUEST_ENTITY_TOO_LARGE | HTTP/Request entity too large |
REST_PROXY_ERROR_HTTP_REQUEST_URI_TOO_LONG | HTTP/Request URI too long |
REST_PROXY_ERROR_HTTP_UNSUPPORTED_MEDIA_TYPE | HTTP/Unsupported media type |
REST_PROXY_ERROR_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE | HTTP/Requested range not satisfiable |
REST_PROXY_ERROR_HTTP_EXPECTATION_FAILED | HTTP/Expectation failed |
REST_PROXY_ERROR_HTTP_INTERNAL_SERVER_ERROR | HTTP/Internal server error |
REST_PROXY_ERROR_HTTP_NOT_IMPLEMENTED | HTTP/Not implemented |
REST_PROXY_ERROR_HTTP_BAD_GATEWAY | HTTP/Bad gateway |
REST_PROXY_ERROR_HTTP_SERVICE_UNAVAILABLE | HTTP/Service unavailable |
REST_PROXY_ERROR_HTTP_GATEWAY_TIMEOUT | HTTP/Gateway timeout |
REST_PROXY_ERROR_HTTP_HTTP_VERSION_NOT_SUPPORTED | HTTP/Version not supported |

## Property Details

### The `“binding-required”` property

      “binding-required”         gboolean

Whether the URL format requires binding.

Flags: Read / Write

Default value: FALSE

### The `“disable-cookies”` property

      “disable-cookies”          gboolean

Whether to disable cookie support.

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“password”` property

      “password”                 gchar *

The password for authentication.

Flags: Read / Write

Default value: NULL

### The `“ssl-ca-file”` property

      “ssl-ca-file”              gchar *

File containing SSL CA certificates.

Flags: Read / Write

Default value: NULL

### The `“ssl-strict”` property

      “ssl-strict”               gboolean

Whether certificate errors should be considered a connection error.

Flags: Read / Write

Default value: TRUE

### The `“url-format”` property

      “url-format”               gchar *

Format string for the RESTful url.

Flags: Read / Write

Default value: NULL

### The `“user-agent”` property

      “user-agent”               gchar *

The User-Agent of the client.

Flags: Read / Write

Default value: NULL

### The `“username”` property

      “username”                 gchar *

The username for authentication.

Flags: Read / Write

Default value: NULL

## Signal Details

### The `“authenticate”` signal

    gboolean
    user_function (RestProxy     *proxy,
                   RestProxyAuth *auth,
                   gboolean       retrying,
                   gpointer       user_data)

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.

#### Parameters

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

Flags: Run Last