RestProxyCall: librest Reference Manual

## RestProxyCall RestProxyCall |

## Functions

void | rest_proxy_call_set_method ()
const char * | rest_proxy_call_get_method ()
void | rest_proxy_call_set_function ()
const char * | rest_proxy_call_get_function ()
void | rest_proxy_call_add_header ()
void | rest_proxy_call_add_headers ()
void | rest_proxy_call_add_headers_from_valist ()
const gchar * | rest_proxy_call_lookup_header ()
void | rest_proxy_call_remove_header ()
void | rest_proxy_call_add_param ()
void | rest_proxy_call_add_param_full ()
void | rest_proxy_call_add_params ()
void | rest_proxy_call_add_params_from_valist ()
RestParam * | rest_proxy_call_lookup_param ()
void | rest_proxy_call_remove_param ()
RestParams * | rest_proxy_call_get_params ()
gboolean | rest_proxy_call_run ()
void | (*RestProxyCallAsyncCallback) ()
void | (*RestProxyCallUploadCallback) ()
gboolean | rest_proxy_call_async ()
gboolean | rest_proxy_call_cancel ()
gboolean | rest_proxy_call_sync ()
gboolean | rest_proxy_call_upload ()
void | rest_proxy_call_invoke_async ()
const gchar * | rest_proxy_call_lookup_response_header ()
GHashTable * | rest_proxy_call_get_response_headers ()
goffset | rest_proxy_call_get_payload_length ()
const gchar * | rest_proxy_call_get_payload ()
guint | rest_proxy_call_get_status_code ()
const gchar * | rest_proxy_call_get_status_message ()

## Properties

RestProxy * | proxy | Read / Write / Construct Only

## Types and Values

| RestProxyCall
#define | REST_PROXY_CALL_ERROR
enum | RestProxyCallError

## Object Hierarchy

        GObject
        ╰── RestProxyCall
            ├── FlickrProxyCall
            ├── LastfmProxyCall
            ├── OAuth2ProxyCall
            ╰── OAuthProxyCall

## Description

## Functions

### rest_proxy_call_set_method ()

    void
    rest_proxy_call_set_method (RestProxyCall *call,
                                const gchar *method);

Set the HTTP method to use when making the call, for example GET or POST.

#### Parameters

call | The RestProxyCall |
method | The HTTP method to use |

### rest_proxy_call_get_method ()

    const char *
    rest_proxy_call_get_method (RestProxyCall *call);

Get the HTTP method to use when making the call, for example GET or POST.

#### Parameters

call | The RestProxyCall |

### rest_proxy_call_set_function ()

    void
    rest_proxy_call_set_function (RestProxyCall *call,
                                  const gchar *function);

Set the REST "function" to call on the proxy. This is appended to the URL, so that for example a proxy with the URL `http://www.example.com/` and the function `test` would actually access the URL `http://www.example.com/test`

#### Parameters

call | The RestProxyCall |
function | The function to call |

### rest_proxy_call_get_function ()

    const char *
    rest_proxy_call_get_function (RestProxyCall *call);

Get the REST function that is going to be called on the proxy.

#### Parameters

call | The RestProxyCall |

#### Returns

The REST "function" for the current call, see also `rest_proxy_call_set_function()`. This string is owned by the RestProxyCall and should not be freed.

Since: 0.7.92

### rest_proxy_call_add_header ()

    void
    rest_proxy_call_add_header (RestProxyCall *call,
                                const gchar *header,
                                const gchar *value);

Add a header called `header` with the value `value` to the call. If a header with this name already exists, the new value will replace the old.

#### Parameters

call | The RestProxyCall |
header | The name of the header to set |
value | The value of the header |

### rest_proxy_call_add_headers ()

    void
    rest_proxy_call_add_headers (RestProxyCall *call,
                                 ...);

Add the specified header name and value pairs to the call. If a header already exists, the new value will replace the old.

#### Parameters

call | The RestProxyCall |
... | Header name and value pairs, followed by `NULL`. |

### rest_proxy_call_add_headers_from_valist ()

    void
    rest_proxy_call_add_headers_from_valist
                                   (RestProxyCall *call,
                                    va_list headers);

Add the specified header name and value pairs to the call. If a header already exists, the new value will replace the old.

#### Parameters

call | The RestProxyCall |
headers | Header name and value pairs, followed by `NULL`. |

### rest_proxy_call_lookup_header ()

    const gchar *
    rest_proxy_call_lookup_header (RestProxyCall *call,
                                   const gchar *header);

Get the value of the header called `header` .

#### Parameters

call | The RestProxyCall |
header | The header name |

#### Returns

The header value, or `NULL` if it does not exist. This string is owned by the RestProxyCall and should not be freed.

### rest_proxy_call_remove_header ()

    void
    rest_proxy_call_remove_header (RestProxyCall *call,
                                   const gchar *header);

Remove the header named `header` from the call.

#### Parameters

call | The RestProxyCall |
header | The header name |

### rest_proxy_call_add_param ()

    void
    rest_proxy_call_add_param (RestProxyCall *call,
                               const gchar *name,
                               const gchar *value);

Add a query parameter called `param` with the string value `value` to the call. If a parameter with this name already exists, the new value will replace the old.

#### Parameters

call | The RestProxyCall |
name | The name of the parameter to set |
value | The value of the parameter |

### rest_proxy_call_add_param_full ()

    void
    rest_proxy_call_add_param_full (RestProxyCall *call,
                                    RestParam *param);

### rest_proxy_call_add_params ()

    void
    rest_proxy_call_add_params (RestProxyCall *call,
                                ...);

Add the specified parameter name and value pairs to the call. If a parameter already exists, the new value will replace the old.

#### Parameters

call | The RestProxyCall |
... | Parameter name and value pairs, followed by `NULL`. |

### rest_proxy_call_add_params_from_valist ()

    void
    rest_proxy_call_add_params_from_valist
                                   (RestProxyCall *call,
                                    va_list params);

Add the specified parameter name and value pairs to the call. If a parameter already exists, the new value will replace the old.

#### Parameters

call | The RestProxyCall |
params | Parameter name and value pairs, followed by `NULL`. |

### rest_proxy_call_lookup_param ()

    RestParam *
    rest_proxy_call_lookup_param (RestProxyCall *call,
                                  const gchar *name);

Get the value of the parameter called `name` .

#### Parameters

call | The RestProxyCall |
name | The paramter name |

#### Returns

The parameter value, or `NULL` if it does not exist. This string is owned by the RestProxyCall and should not be freed.

### rest_proxy_call_remove_param ()

    void
    rest_proxy_call_remove_param (RestProxyCall *call,
                                  const gchar *name);

Remove the parameter named `name` from the call.

#### Parameters

call | The RestProxyCall |
name | The paramter name |

### rest_proxy_call_get_params ()

    RestParams *
    rest_proxy_call_get_params (RestProxyCall *call);

Get the parameters as a RestParams of parameter names to values. The returned value is owned by the RestProxyCall instance and should not be freed by the caller.

#### Parameters

call | The RestProxyCall |

#### Returns

A RestParams.

[transfer none]

### rest_proxy_call_run ()

    gboolean
    rest_proxy_call_run (RestProxyCall *call,
                         GMainLoop **loop,
                         GError **error);

### RestProxyCallAsyncCallback ()

    void
    (*RestProxyCallAsyncCallback) (RestProxyCall *call,
                                   const GError *error,
                                   GObject *weak_object,
                                   gpointer userdata);

### RestProxyCallUploadCallback ()

    void
    (*RestProxyCallUploadCallback) (RestProxyCall *call,
                                    gsize total,
                                    gsize uploaded,
                                    const GError *error,
                                    GObject *weak_object,
                                    gpointer userdata);

### rest_proxy_call_async ()

    gboolean
    rest_proxy_call_async (RestProxyCall *call,
                           RestProxyCallAsyncCallback callback,
                           GObject *weak_object,
                           gpointer userdata,
                           GError **error);

Asynchronously invoke `call` .

When the call has finished, `callback` will be called. If `weak_object` is disposed during the call then this call will be cancelled. If the call is cancelled then the callback will be invoked with an error state.

You may unref the call after calling this function since there is an internal reference, or you may unref in the callback.

[skip]

#### Parameters

call | The RestProxyCall |
callback | a RestProxyCallAsyncCallback to invoke on completion of the call |
weak_object | The GObject to weakly reference and tie the lifecycle too |
userdata | data to pass to `callback` |
error | a GError, or `NULL` |

### rest_proxy_call_cancel ()

    gboolean
    rest_proxy_call_cancel (RestProxyCall *call);

Cancel this call. It may be too late to not actually send the message, but the callback will not be invoked.

N.B. this method should only be used with `rest_proxy_call_async()` and NOT `rest_proxy_call_invoke_async()`.

[skip]

#### Parameters

call | The RestProxyCall |

### rest_proxy_call_sync ()

    gboolean
    rest_proxy_call_sync (RestProxyCall *call,
                          GError **error_out);

### rest_proxy_call_upload ()

    gboolean
    rest_proxy_call_upload (RestProxyCall *call,
                            RestProxyCallUploadCallback callback,
                            GObject *weak_object,
                            gpointer userdata,
                            GError **error);

Asynchronously invoke `call` but expect to have the callback invoked every time a chunk of our request's body is written.

When the callback is invoked with the uploaded byte count equaling the message byte count, the call has completed.

If `weak_object` is disposed during the call then this call will be cancelled. If the call is cancelled then the callback will be invoked with an error state.

You may unref the call after calling this function since there is an internal reference, or you may unref in the callback.

#### Parameters

call | The RestProxyCall |
callback | a RestProxyCallUploadCallback to invoke when a chunk of data was uploaded. | [scope async]
weak_object | The GObject to weakly reference and tie the lifecycle to |
userdata | data to pass to `callback` |
error | a GError, or `NULL` |

### rest_proxy_call_invoke_async ()

    void
    rest_proxy_call_invoke_async (RestProxyCall *call,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

A GIO-style version of `rest_proxy_call_async()`.

#### Parameters

call | a RestProxyCall |
cancellable | an optional GCancellable that can be used to cancel the call, or `NULL`. | [allow-none]
callback | callback to call when the async call is finished. | [scope async]
user_data | user data for the callback. | [closure]

### rest_proxy_call_lookup_response_header ()

    const gchar *
    rest_proxy_call_lookup_response_header
                                   (RestProxyCall *call,
                                    const gchar *header);

Get the string value of the header `header` or `NULL` if that header is not present or there are no headers.

#### Parameters

call | The RestProxyCall |
header | The name of the header to lookup. |

### rest_proxy_call_get_response_headers ()

    GHashTable *
    rest_proxy_call_get_response_headers (RestProxyCall *call);

#### Parameters

call | The RestProxyCall |

#### Returns

pointer to a hash table of headers. This hash table must not be changed. You should call `g_hash_table_unref()` when you have finished with it.

[transfer container]

### rest_proxy_call_get_payload_length ()

    goffset
    rest_proxy_call_get_payload_length (RestProxyCall *call);

Get the length of the return payload.

#### Parameters

call | The RestProxyCall |

#### Returns

the length of the payload in bytes.

### rest_proxy_call_get_payload ()

    const gchar *
    rest_proxy_call_get_payload (RestProxyCall *call);

Get the return payload.

#### Parameters

call | The RestProxyCall |

#### Returns

A pointer to the payload. This is owned by RestProxyCall and should not be freed.

### rest_proxy_call_get_status_code ()

    guint
    rest_proxy_call_get_status_code (RestProxyCall *call);

Get the HTTP status code for the call.

#### Parameters

call | The RestProxyCall |

### rest_proxy_call_get_status_message ()

    const gchar *
    rest_proxy_call_get_status_message (RestProxyCall *call);

Get the human-readable HTTP status message for the call.

#### Parameters

call | The RestProxyCall |

#### Returns

The status message. This string is owned by RestProxyCall and should not be freed.

## Types and Values

### RestProxyCall

    typedef struct _RestProxyCall RestProxyCall;

RestProxyCall has no publicly available members.

### REST_PROXY_CALL_ERROR

    #define REST_PROXY_CALL_ERROR rest_proxy_call_error_quark ()

### enum RestProxyCallError

Error domain used when returning errors from RestProxyCall.

#### Members

REST_PROXY_CALL_FAILED | the method call failed |

## Property Details

### The `“proxy”` property

      “proxy”                    RestProxy *

Proxy for this call.

Flags: Read / Write / Construct Only