ESourceProxy: Evolution-Data-Server Reference Manual

## ESourceProxy ESourceProxy — ESource extension for network proxy settings |

## Functions

EProxyMethod | e_source_proxy_get_method ()
void | e_source_proxy_set_method ()
const gchar * | e_source_proxy_get_autoconfig_url ()
gchar * | e_source_proxy_dup_autoconfig_url ()
void | e_source_proxy_set_autoconfig_url ()
const gchar * const * | e_source_proxy_get_ignore_hosts ()
gchar ** | e_source_proxy_dup_ignore_hosts ()
void | e_source_proxy_set_ignore_hosts ()
const gchar * | e_source_proxy_get_ftp_host ()
gchar * | e_source_proxy_dup_ftp_host ()
void | e_source_proxy_set_ftp_host ()
guint16 | e_source_proxy_get_ftp_port ()
void | e_source_proxy_set_ftp_port ()
const gchar * | e_source_proxy_get_http_host ()
gchar * | e_source_proxy_dup_http_host ()
void | e_source_proxy_set_http_host ()
guint16 | e_source_proxy_get_http_port ()
void | e_source_proxy_set_http_port ()
gboolean | e_source_proxy_get_http_use_auth ()
void | e_source_proxy_set_http_use_auth ()
const gchar * | e_source_proxy_get_http_auth_user ()
gchar * | e_source_proxy_dup_http_auth_user ()
void | e_source_proxy_set_http_auth_user ()
const gchar * | e_source_proxy_get_http_auth_password ()
gchar * | e_source_proxy_dup_http_auth_password ()
void | e_source_proxy_set_http_auth_password ()
const gchar * | e_source_proxy_get_https_host ()
gchar * | e_source_proxy_dup_https_host ()
void | e_source_proxy_set_https_host ()
guint16 | e_source_proxy_get_https_port ()
void | e_source_proxy_set_https_port ()
const gchar * | e_source_proxy_get_socks_host ()
gchar * | e_source_proxy_dup_socks_host ()
void | e_source_proxy_set_socks_host ()
guint16 | e_source_proxy_get_socks_port ()
void | e_source_proxy_set_socks_port ()
gchar ** | e_source_proxy_lookup_sync ()
void | e_source_proxy_lookup ()
gchar ** | e_source_proxy_lookup_finish ()

## Types and Values

#define | E_SOURCE_EXTENSION_PROXY
struct | ESourceProxy

## Object Hierarchy

        GObject
        ╰── ESourceExtension
            ╰── ESourceProxy

## Includes

    #include <libedataserver/libedataserver.h>

## 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);

## Functions

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

source | an ESource |
uri | a URI representing the destination to connect to |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

a `NULL`-terminated array of proxy URIs, or `NULL`.

[transfer full][nullable]

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.

#### Parameters

source | an ESource |
uri | a URI representing the destination to connect to |
cancellable | optional GCancellable object, or `NULL` |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | data to pass to the callback function |

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.

#### Parameters

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][nullable]

Since: 3.12

## Types and Values

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

Since: 3.12