RestProxy

RestProxy

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

Types and Values

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