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

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`

Since 3.12