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