GProxy: GIO Reference Manual

## GProxy GProxy — Interface for proxy handling |

## Functions

GIOStream * | g_proxy_connect ()
void | g_proxy_connect_async ()
GIOStream * | g_proxy_connect_finish ()
GProxy * | g_proxy_get_default_for_protocol ()
gboolean | g_proxy_supports_hostname ()

## Types and Values

| GProxy
struct | GProxyInterface
#define | G_PROXY_EXTENSION_POINT_NAME

## Object Hierarchy

        GInterface
        ╰── GProxy

## Prerequisites

GProxy requires GObject.

## Includes

    #include <gio/gio.h>

## 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()`.

## Functions

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

#### Parameters

proxy | a GProxy |
connection | a GIOStream |
proxy_address | a GProxyAddress |
cancellable | a GCancellable. | [nullable]
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()`.

#### Parameters

proxy | a GProxy |
connection | a GIOStream |
proxy_address | a GProxyAddress |
cancellable | a GCancellable. | [nullable]
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()`.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

proxy | a GProxy |

#### Returns

`TRUE` if hostname resolution is supported.

Since: 2.26

## Types and Values

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

#### Members

`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