ESourceProxy

ESourceProxy — ESource extension for network proxy settings

Synopsis

#include <libedataserver/libedataserver.h>

#define             E_SOURCE_EXTENSION_PROXY
struct              ESourceProxy;
struct              ESourceProxyClass;
EProxyMethod        e_source_proxy_get_method           (ESourceProxy *extension);
void                e_source_proxy_set_method           (ESourceProxy *extension,
                                                         EProxyMethod method);
const gchar *       e_source_proxy_get_autoconfig_url   (ESourceProxy *extension);
gchar *             e_source_proxy_dup_autoconfig_url   (ESourceProxy *extension);
void                e_source_proxy_set_autoconfig_url   (ESourceProxy *extension,
                                                         const gchar *autoconfig_url);
const gchar * const * e_source_proxy_get_ignore_hosts   (ESourceProxy *extension);
gchar **            e_source_proxy_dup_ignore_hosts     (ESourceProxy *extension);
void                e_source_proxy_set_ignore_hosts     (ESourceProxy *extension,
                                                         const gchar * const *ignore_hosts);
const gchar *       e_source_proxy_get_ftp_host         (ESourceProxy *extension);
gchar *             e_source_proxy_dup_ftp_host         (ESourceProxy *extension);
void                e_source_proxy_set_ftp_host         (ESourceProxy *extension,
                                                         const gchar *ftp_host);
guint16             e_source_proxy_get_ftp_port         (ESourceProxy *extension);
void                e_source_proxy_set_ftp_port         (ESourceProxy *extension,
                                                         guint16 ftp_port);
const gchar *       e_source_proxy_get_http_host        (ESourceProxy *extension);
gchar *             e_source_proxy_dup_http_host        (ESourceProxy *extension);
void                e_source_proxy_set_http_host        (ESourceProxy *extension,
                                                         const gchar *http_host);
guint16             e_source_proxy_get_http_port        (ESourceProxy *extension);
void                e_source_proxy_set_http_port        (ESourceProxy *extension,
                                                         guint16 http_port);
gboolean            e_source_proxy_get_http_use_auth    (ESourceProxy *extension);
void                e_source_proxy_set_http_use_auth    (ESourceProxy *extension,
                                                         gboolean http_use_auth);
const gchar *       e_source_proxy_get_http_auth_user   (ESourceProxy *extension);
gchar *             e_source_proxy_dup_http_auth_user   (ESourceProxy *extension);
void                e_source_proxy_set_http_auth_user   (ESourceProxy *extension,
                                                         const gchar *http_auth_user);
const gchar *       e_source_proxy_get_http_auth_password
                                                        (ESourceProxy *extension);
gchar *             e_source_proxy_dup_http_auth_password
                                                        (ESourceProxy *extension);
void                e_source_proxy_set_http_auth_password
                                                        (ESourceProxy *extension,
                                                         const gchar *http_auth_password);
const gchar *       e_source_proxy_get_https_host       (ESourceProxy *extension);
gchar *             e_source_proxy_dup_https_host       (ESourceProxy *extension);
void                e_source_proxy_set_https_host       (ESourceProxy *extension,
                                                         const gchar *https_host);
guint16             e_source_proxy_get_https_port       (ESourceProxy *extension);
void                e_source_proxy_set_https_port       (ESourceProxy *extension,
                                                         guint16 https_port);
const gchar *       e_source_proxy_get_socks_host       (ESourceProxy *extension);
gchar *             e_source_proxy_dup_socks_host       (ESourceProxy *extension);
void                e_source_proxy_set_socks_host       (ESourceProxy *extension,
                                                         const gchar *socks_host);
guint16             e_source_proxy_get_socks_port       (ESourceProxy *extension);
void                e_source_proxy_set_socks_port       (ESourceProxy *extension,
                                                         guint16 socks_port);
gchar **            e_source_proxy_lookup_sync          (ESource *source,
                                                         const gchar *uri,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_source_proxy_lookup               (ESource *source,
                                                         const gchar *uri,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gchar **            e_source_proxy_lookup_finish        (ESource *source,
                                                         GAsyncResult *result,
                                                         GError **error);

Description

The ESourceProxy extension defines a network proxy profile.

An ESource instance with this extension can serve as a GProxyResolver.

Access the extension as follows:

1
2
3
4
5
#include <libedataserver/libedataserver.h>

ESourceProxy *extension;

extension = e_source_get_extension (source, E_SOURCE_EXTENSION_PROXY);

Details

E_SOURCE_EXTENSION_PROXY

#define E_SOURCE_EXTENSION_PROXY "Proxy"

Pass this extension name to e_source_get_extension() to access ESourceProxy. This is also used as a group name in key files.

Since 3.12


struct ESourceProxy

struct ESourceProxy {
	ESourceExtension parent;
	ESourceProxyPrivate *priv;
};

Contains only private data that should be read and manipulated using the functions below.

Since 3.12


struct ESourceProxyClass

struct ESourceProxyClass {
	ESourceExtensionClass parent_class;
};

e_source_proxy_get_method ()

EProxyMethod        e_source_proxy_get_method           (ESourceProxy *extension);

Returns the proxy configuration method for extension.

The proxy configuration method determines the behavior of e_source_proxy_lookup().

extension :

an ESourceProxy

Returns :

the proxy configuration method

Since 3.12


e_source_proxy_set_method ()

void                e_source_proxy_set_method           (ESourceProxy *extension,
                                                         EProxyMethod method);

Sets the proxy configuration method for extension.

The proxy configuration method determines the behavior of e_source_proxy_lookup().

extension :

an ESourceProxy

method :

the proxy configuration method

Since 3.12


e_source_proxy_get_autoconfig_url ()

const gchar *       e_source_proxy_get_autoconfig_url   (ESourceProxy *extension);

Returns the URL that provides proxy configuration values. When the extension's "method" is E_PROXY_METHOD_AUTO, this URL is used to look up proxy information for all protocols.

extension :

an ESourceProxy

Returns :

the autoconfiguration URL

Since 3.12


e_source_proxy_dup_autoconfig_url ()

gchar *             e_source_proxy_dup_autoconfig_url   (ESourceProxy *extension);

Thread-safe variation of e_source_proxy_get_autoconfig_url(). Use this function when accessing extension from multiple threads.

The returned string should be freed with g_free() when no longer needed.

extension :

an ESourceProxy

Returns :

a newly-allocated copy of "autoconfig-url"

Since 3.12


e_source_proxy_set_autoconfig_url ()

void                e_source_proxy_set_autoconfig_url   (ESourceProxy *extension,
                                                         const gchar *autoconfig_url);

Sets the URL that provides proxy configuration values. When the extension's "method" is E_PROXY_METHOD_AUTO, this URL is used to look up proxy information for all protocols.

extension :

an ESourceProxy

autoconfig_url :

an autoconfiguration URL

Since 3.12


e_source_proxy_get_ignore_hosts ()

const gchar * const * e_source_proxy_get_ignore_hosts   (ESourceProxy *extension);

Returns a NULL-terminated string array of hosts which are connected to directly, rather than via the proxy (if it is active). The array elements can be hostnames, domains (using an initial wildcard like *.foo.com), IP host addresses (both IPv4 and IPv6) and network addresses with a netmask (something like 192.168.0.0/24).

The returned array is owned by extension and should not be modified or freed.

extension :

an ESourceProxy

Returns :

a NULL-terminated string array of hosts. [transfer none]

Since 3.12


e_source_proxy_dup_ignore_hosts ()

gchar **            e_source_proxy_dup_ignore_hosts     (ESourceProxy *extension);

Thread-safe variation of e_source_proxy_get_ignore_hosts(). Use this function when accessing extension from multiple threads.

The returned string array should be freed with g_strfreev() when no longer needed.

extension :

an ESourceProxy

Returns :

a newly-allocated copy of "ignore-hosts". [transfer full]

Since 3.12


e_source_proxy_set_ignore_hosts ()

void                e_source_proxy_set_ignore_hosts     (ESourceProxy *extension,
                                                         const gchar * const *ignore_hosts);

Sets the hosts which are connected to directly, rather than via the proxy (if it is active). The array elements can be hostnames, domains (using an initial wildcard like *.foo.com), IP host addresses (both IPv4 and IPv6) and network addresses with a netmask (something like 192.168.0.0/24).

extension :

an ESourceProxy

ignore_hosts :

a NULL-terminated string array of hosts

Since 3.12


e_source_proxy_get_ftp_host ()

const gchar *       e_source_proxy_get_ftp_host         (ESourceProxy *extension);

Returns the machine name to proxy FTP through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

Returns :

FTP proxy host name

Since 3.12


e_source_proxy_dup_ftp_host ()

gchar *             e_source_proxy_dup_ftp_host         (ESourceProxy *extension);

Thread-safe variation of e_source_proxy_get_ftp_host(). Use this function when accessing extension from multiple threads.

The returned string should be freed with g_free() when no longer needed.

extension :

an ESourceProxy

Returns :

a newly-allocated copy of "ftp-host"

Since 3.12


e_source_proxy_set_ftp_host ()

void                e_source_proxy_set_ftp_host         (ESourceProxy *extension,
                                                         const gchar *ftp_host);

Sets the machine name to proxy FTP through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

ftp_host :

FTP proxy host name

Since 3.12


e_source_proxy_get_ftp_port ()

guint16             e_source_proxy_get_ftp_port         (ESourceProxy *extension);

Returns the port on the machine defined by "ftp-host" to proxy through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

Returns :

FTP proxy port

Since 3.12


e_source_proxy_set_ftp_port ()

void                e_source_proxy_set_ftp_port         (ESourceProxy *extension,
                                                         guint16 ftp_port);

Sets the port on the machine defined by "ftp-host" to proxy through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

ftp_port :

FTP proxy port

Since 3.12


e_source_proxy_get_http_host ()

const gchar *       e_source_proxy_get_http_host        (ESourceProxy *extension);

Returns the machine name to proxy HTTP through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

Returns :

HTTP proxy host name

Since 3.12


e_source_proxy_dup_http_host ()

gchar *             e_source_proxy_dup_http_host        (ESourceProxy *extension);

Thread-safe variation of e_source_proxy_get_http_host(). Use this function when accessing extension from multiple threads.

The returned string should be freed with g_free() when no longer needed.

extension :

an ESourceProxy

Returns :

a newly-allocated copy of "http-host"

Since 3.12


e_source_proxy_set_http_host ()

void                e_source_proxy_set_http_host        (ESourceProxy *extension,
                                                         const gchar *http_host);

Sets the machine name to proxy HTTP through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

http_host :

HTTP proxy host name

Since 3.12


e_source_proxy_get_http_port ()

guint16             e_source_proxy_get_http_port        (ESourceProxy *extension);

Returns the port on the machine defined by "http-host" to proxy through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

Returns :

HTTP proxy port

Since 3.12


e_source_proxy_set_http_port ()

void                e_source_proxy_set_http_port        (ESourceProxy *extension,
                                                         guint16 http_port);

Sets the port on the machine defined by "http-host" to proxy through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

http_port :

HTTP proxy port

Since 3.12


e_source_proxy_get_http_use_auth ()

gboolean            e_source_proxy_get_http_use_auth    (ESourceProxy *extension);

Returns whether the HTTP proxy server at "http-host" and "http-port" requires authentication.

The username/password combo is defined by "http-auth-user" and "http-auth-password", but only applies when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

Returns :

whether to authenticate HTTP proxy connections

Since 3.12


e_source_proxy_set_http_use_auth ()

void                e_source_proxy_set_http_use_auth    (ESourceProxy *extension,
                                                         gboolean http_use_auth);

Sets whether the HTTP proxy server at "http-host" and "http-port" requires authentication.

The username/password combo is defined by "http-auth-user" and "http-auth-password", but only applies when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

http_use_auth :

whether to authenticate HTTP proxy connections

Since 3.12


e_source_proxy_get_http_auth_user ()

const gchar *       e_source_proxy_get_http_auth_user   (ESourceProxy *extension);

Returns the user name to pass as authentication when doing HTTP proxying and "http-use-auth" is TRUE.

extension :

an ESourceProxy

Returns :

HTTP proxy username

Since 3.12


e_source_proxy_dup_http_auth_user ()

gchar *             e_source_proxy_dup_http_auth_user   (ESourceProxy *extension);

Thread-safe variation of e_source_proxy_get_http_auth_user(). Use this function when accessing extension from multiple threads.

The returned string should be freed with g_free() when no longer needed.

extension :

an ESourceProxy

Returns :

a newly-allocated copy of "http-auth-user"

Since 3.12


e_source_proxy_set_http_auth_user ()

void                e_source_proxy_set_http_auth_user   (ESourceProxy *extension,
                                                         const gchar *http_auth_user);

Sets the user name to pass as authentication when doing HTTP proxying and "http-use-auth" is TRUE.

extension :

an ESourceProxy

http_auth_user :

HTTP proxy username

Since 3.12


e_source_proxy_get_http_auth_password ()

const gchar *       e_source_proxy_get_http_auth_password
                                                        (ESourceProxy *extension);

Returns the password to pass as authentication when doing HTTP proxying and "http-use-auth" is TRUE.

extension :

an ESourceProxy

Returns :

HTTP proxy password

Since 3.12


e_source_proxy_dup_http_auth_password ()

gchar *             e_source_proxy_dup_http_auth_password
                                                        (ESourceProxy *extension);

Thread-safe variation of e_source_proxy_get_http_auth_password(). Use this function when accessing extension from multiple threads.

The returned string should be freed with g_free() when no longer needed.

extension :

an ESourceProxy

Returns :

a newly-allocated copy of "http-auth-password"

Since 3.12


e_source_proxy_set_http_auth_password ()

void                e_source_proxy_set_http_auth_password
                                                        (ESourceProxy *extension,
                                                         const gchar *http_auth_password);

Sets the password to pass as authentication when doing HTTP proxying and "http-use-auth" is TRUE.

extension :

an ESourceProxy

http_auth_password :

HTTP proxy password

Since 3.12


e_source_proxy_get_https_host ()

const gchar *       e_source_proxy_get_https_host       (ESourceProxy *extension);

Returns the machine name to proxy secure HTTP through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

Returns :

secure HTTP proxy host name

Since 3.12


e_source_proxy_dup_https_host ()

gchar *             e_source_proxy_dup_https_host       (ESourceProxy *extension);

Threads-safe variation of e_source_proxy_get_https_host(). Use this function when accessing extension from multiple threads.

The returned string should be freed with g_free() when no longer needed.

extension :

an ESourceProxy

Returns :

a newly-allocated copy of "https-host"

Since 3.12


e_source_proxy_set_https_host ()

void                e_source_proxy_set_https_host       (ESourceProxy *extension,
                                                         const gchar *https_host);

Sets the machine name to proxy secure HTTP through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

https_host :

secure HTTP proxy host name

Since 3.12


e_source_proxy_get_https_port ()

guint16             e_source_proxy_get_https_port       (ESourceProxy *extension);

Returns the port on the machine defined by "https-host" to proxy through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

Returns :

secure HTTP proxy port

Since 3.12


e_source_proxy_set_https_port ()

void                e_source_proxy_set_https_port       (ESourceProxy *extension,
                                                         guint16 https_port);

Sets the port on the machine defined by "https-host" to proxy through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

https_port :

secure HTTP proxy port

Since 3.12


e_source_proxy_get_socks_host ()

const gchar *       e_source_proxy_get_socks_host       (ESourceProxy *extension);

Returns the machine name to use as a SOCKS proxy when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

Returns :

SOCKS proxy host name

Since 3.12


e_source_proxy_dup_socks_host ()

gchar *             e_source_proxy_dup_socks_host       (ESourceProxy *extension);

Thread-safe variation of e_source-proxy_get_socks_host(). Use this function when accessing extension from multiple threads.

The returned string should be freed with g_free() when no longer needed.

extension :

an ESourceProxy

Returns :

a newly-allocated copy of "socks-host"

Since 3.12


e_source_proxy_set_socks_host ()

void                e_source_proxy_set_socks_host       (ESourceProxy *extension,
                                                         const gchar *socks_host);

Sets the machine name to use as a SOCKS proxy when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

socks_host :

SOCKS proxy host name

Since 3.12


e_source_proxy_get_socks_port ()

guint16             e_source_proxy_get_socks_port       (ESourceProxy *extension);

Returns the port on the machine defined by "socks-host" to proxy through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

Returns :

SOCKS proxy port

Since 3.12


e_source_proxy_set_socks_port ()

void                e_source_proxy_set_socks_port       (ESourceProxy *extension,
                                                         guint16 socks_port);

Sets the port on the machine defined by "socks-host" to proxy through when extension's "method" is E_PROXY_METHOD_MANUAL.

extension :

an ESourceProxy

socks_port :

SOCKS proxy port

Since 3.12


e_source_proxy_lookup_sync ()

gchar **            e_source_proxy_lookup_sync          (ESource *source,
                                                         const gchar *uri,
                                                         GCancellable *cancellable,
                                                         GError **error);

Looks into source's ESourceProxy extension to determine what proxy, if any, to use to connect to uri. The returned proxy URIs are of the same form described by g_proxy_resolver_lookup().

The proxy extension's "method" controls how proxy URIs are determined:

When using E_PROXY_METHOD_DEFAULT, the function will defer to the GProxyResolver returned by g_proxy_resolver_get_default().

When using E_PROXY_METHOD_MANUAL, the function will configure a GSimpleProxyResolver from the HTTP, HTTPS, FTP and SOCKS properties, as well as "ignore-hosts".

When using E_PROXY_METHOD_AUTO, the function will execute a proxy auto-config (PAC) file at "autoconfig-url".

When using E_PROXY_METHOD_NONE, the function will only return direct://.

If source does not have an ESourceProxy extension, the function sets error to G_IO_ERROR_NOT_SUPPORTED and returns NULL.

Free the returned proxy URIs with g_strfreev() when finished with them.

source :

an ESource

uri :

a URI representing the destination to connect to

cancellable :

optional GCancellable object, or NULL. [allow-none]

error :

return location for a GError, or NULL

Returns :

a NULL-terminated array of proxy URIs, or NULL. [transfer full]

Since 3.12


e_source_proxy_lookup ()

void                e_source_proxy_lookup               (ESource *source,
                                                         const gchar *uri,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously determines what proxy, if any, to use to connect to uri. See e_source_proxy_lookup_sync() for more details.

When the operation is finished, callback will be called. You can then call e_source_proxy_lookup_finish() to get the result of the operation.

source :

an ESource

uri :

a URI representing the destination to connect to

cancellable :

optional GCancellable object, or NULL. [allow-none]

callback :

a GAsyncReadyCallback to call when the request is satisfied. [scope async]

user_data :

data to pass to the callback function. [closure]

Since 3.12


e_source_proxy_lookup_finish ()

gchar **            e_source_proxy_lookup_finish        (ESource *source,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_source_proxy_lookup().

Free the returned proxy URIs with g_strfreev() when finished with them.

source :

an ESource

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

a NULL-terminated array of proxy URIs, or NULL. [transfer full]

Since 3.12