diff options
Diffstat (limited to 'src/libproxy/proxy.h')
-rw-r--r-- | src/libproxy/proxy.h | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/src/libproxy/proxy.h b/src/libproxy/proxy.h index 50f9944..cf4fc34 100644 --- a/src/libproxy/proxy.h +++ b/src/libproxy/proxy.h @@ -28,15 +28,113 @@ extern "C" { #include <gio/gio.h> +/** + * SECTION:px-proxy + * @short_description: A convient helper for using proxy servers + */ + typedef struct _pxProxyFactory pxProxyFactory; #define PX_TYPE_PROXY_FACTORY (px_proxy_factory_get_type ()) +/** + * px_proxy_factory_new: + * + * Creates a new `pxProxyFactory` instance. + * + * This instance should be kept around as long as possible as it contains + * cached data to increase performance. Memory usage should be minimal + * (cache is small) and the cache lifespan is handled automatically. + * + * Returns: The newly created `pxProxyFactory` + */ pxProxyFactory *px_proxy_factory_new (void); + GType px_proxy_factory_get_type (void) G_GNUC_CONST; +/** + * px_proxy_factory_get_proxies: + * @self: a #pxProxyFactory + * @url: Get proxxies for specificed URL + * + * Get which proxies to use for the specified @URL. + * + * A %NULL-terminated array of proxy strings is returned. + * If the first proxy fails, the second should be tried, etc... + * Don't forget to free the strings/array when you are done. + * If an unrecoverable error occurs, this function returns %NULL. + * + * Regarding performance: this method always blocks and may be called + * in a separate thread (is thread-safe). In most cases, the time + * required to complete this function call is simply the time required + * to read the configuration (i.e. from gconf, kconfig, etc). + * + * In the case of PAC, if no valid PAC is found in the cache (i.e. + * configuration has changed, cache is invalid, etc), the PAC file is + * downloaded and inserted into the cache. This is the most expensive + * operation as the PAC is retrieved over the network. Once a PAC exists + * in the cache, it is merely a javascript invocation to evaluate the PAC. + * One should note that DNS can be called from within a PAC during + * javascript invocation. + * + * In the case of WPAD, WPAD is used to automatically locate a PAC on the + * network. Currently, we only use DNS for this, but other methods may + * be implemented in the future. Once the PAC is located, normal PAC + * performance (described above) applies. + * + * The format of the returned proxy strings are as follows: + * + * - http://[username:password@]proxy:port + * + * - socks://[username:password@]proxy:port + * + * - socks5://[username:password@]proxy:port + * + * - socks4://[username:password@]proxy:port + * + * - <procotol>://[username:password@]proxy:port + * + * - direct:// + * + * Please note that the username and password in the above URLs are optional + * and should be use to authenticate the connection if present. + * + * For SOCKS proxies, when the protocol version is specified (socks4:// or + * socks5://), it is expected that only this version is used. When only + * socks:// is set, the client MUST try SOCKS version 5 protocol and, on + * connection failure, fallback to SOCKS version 4. + * + * Other proxying protocols may exist. It is expected that the returned + * configuration scheme shall match the network service name of the + * proxy protocol or the service name of the protocol being proxied if the + * previous does not exist. As an example, on Mac OS X you can configure a + * RTSP streaming proxy. The expected returned configuration would be: + * + * - rtsp://[username:password@]proxy:port + * + * To free the returned value, call @px_proxy_factory_free_proxies. + * + * Returns: (transfer full): a list of proxies + */ char **px_proxy_factory_get_proxies (pxProxyFactory *self, const char *url); + +/** + * px_proxy_factory_free_proxies + * @proxies: (array zero-terminated=1): a %NULL-terminated array of proxies + * + * Frees the proxy array returned by @px_proxy_factory_get_proxies when no + * longer used. + * + * @since 0.4.16 + */ void px_proxy_factory_free_proxies (char **proxies); + +/** + * px_proxy_factory_free: + * @self: a #pxProxyFactory + * + * Frees the `pxProxyFactory`. + */ void px_proxy_factory_free (pxProxyFactory *self); #ifdef __cplusplus |