GIO Reference Manual: GProxy

## GProxy GProxy — Interface for proxy handling |

## Synopsis

                        GProxy;
    struct              GProxyInterface;
    #define             G_PROXY_EXTENSION_POINT_NAME
    GIOStream *         g_proxy_connect                     (GProxy *proxy,
                                                             GIOStream *connection,
                                                             GProxyAddress *proxy_address,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                g_proxy_connect_async               (GProxy *proxy,
                                                             GIOStream *connection,
                                                             GProxyAddress *proxy_address,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GIOStream *         g_proxy_connect_finish              (GProxy *proxy,
                                                             GAsyncResult *result,
                                                             GError **error);
    GProxy *            g_proxy_get_default_for_protocol    (const gchar *protocol);
    gboolean            g_proxy_supports_hostname           (GProxy *proxy);

## Object Hierarchy

      GInterface
       +----GProxy

## Prerequisites

GProxy requires GObject.

## Description

A GProxy handles connecting to a remote host via a given type of proxy server. It is implemented by the 'gio-proxy' extension point. The extensions are named after their proxy protocol name. As an example, a SOCKS5 proxy implementation can be retrieved with the name 'socks5' using the function `g_io_extension_point_get_extension_by_name()`.

## Details

### GProxy

    typedef struct _GProxy GProxy;

Interface that handles proxy connection and payload.

Since 2.26

### struct GProxyInterface

    struct GProxyInterface {
      GTypeInterface g_iface;

      /* Virtual Table */

      GIOStream * (* connect)           (GProxy               *proxy,
    				     GIOStream            *connection,
    				     GProxyAddress        *proxy_address,
    				     GCancellable         *cancellable,
    				     GError              **error);

      void        (* connect_async)     (GProxy               *proxy,
    				     GIOStream            *connection,
    				     GProxyAddress	  *proxy_address,
    				     GCancellable         *cancellable,
    				     GAsyncReadyCallback   callback,
    				     gpointer              user_data);

      GIOStream * (* connect_finish)    (GProxy               *proxy,
    				     GAsyncResult         *result,
    				     GError              **error);

      gboolean    (* supports_hostname) (GProxy             *proxy);
    };

Provides an interface for handling proxy connection and payload.

GTypeInterface `g_iface`; | The parent interface.
`connect` () | Connect to proxy server and wrap (if required) the connection to handle payload.
`connect_async` () | Same as `connect()` but asynchronous.
`connect_finish` () | Returns the result of `connect_async()`
`supports_hostname` () | Returns whether the proxy supports hostname lookups.

Since 2.26

### G_PROXY_EXTENSION_POINT_NAME

    #define G_PROXY_EXTENSION_POINT_NAME "gio-proxy"

Extension point for proxy functionality. See Extending GIO.

Since 2.26

### g_proxy_connect ()

    GIOStream *         g_proxy_connect                     (GProxy *proxy,
                                                             GIOStream *connection,
                                                             GProxyAddress *proxy_address,
                                                             GCancellable *cancellable,
                                                             GError **error);

Given `connection` to communicate with a proxy (eg, a GSocketConnection that is connected to the proxy server), this does the necessary handshake to connect to `proxy_address`, and if required, wraps the GIOStream to handle proxy payload.

`proxy` : | a GProxy
`connection` : | a GIOStream
`proxy_address` : | a GProxyAddress
`cancellable` : | a GCancellable. [allow-none]
`error` : | return GError
Returns : | a GIOStream that will replace `connection`. This might be the same as `connection`, in which case a reference will be added. [transfer full]

Since 2.26

### g_proxy_connect_async ()

    void                g_proxy_connect_async               (GProxy *proxy,
                                                             GIOStream *connection,
                                                             GProxyAddress *proxy_address,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronous version of `g_proxy_connect()`.

`proxy` : | a GProxy
`connection` : | a GIOStream
`proxy_address` : | a GProxyAddress
`cancellable` : | a GCancellable. [allow-none]
`callback` : | a GAsyncReadyCallback. [scope async]
`user_data` : | callback data. [closure]

Since 2.26

### g_proxy_connect_finish ()

    GIOStream *         g_proxy_connect_finish              (GProxy *proxy,
                                                             GAsyncResult *result,
                                                             GError **error);

See `g_proxy_connect()`.

`proxy` : | a GProxy
`result` : | a GAsyncResult
`error` : | return GError
Returns : | a GIOStream. [transfer full]

Since 2.26

### g_proxy_get_default_for_protocol ()

    GProxy *            g_proxy_get_default_for_protocol    (const gchar *protocol);

Lookup "gio-proxy" extension point for a proxy implementation that supports specified protocol.

`protocol` : | the proxy protocol name (e.g. http, socks, etc)
Returns : | return a GProxy or NULL if protocol is not supported. [transfer full]

Since 2.26

### g_proxy_supports_hostname ()

    gboolean            g_proxy_supports_hostname           (GProxy *proxy);

Some proxy protocols expect to be passed a hostname, which they will resolve to an IP address themselves. Others, like SOCKS4, do not allow this. This function will return `FALSE` if `proxy` is implementing such a protocol. When `FALSE` is returned, the caller should resolve the destination hostname first, and then pass a GProxyAddress containing the stringified IP address to `g_proxy_connect()` or `g_proxy_connect_async()`.

`proxy` : | a GProxy
Returns : | `TRUE` if hostname resolution is supported.

Since 2.26