diff options
author | Jan-Michael Brummer <jan.brummer@tabos.org> | 2023-05-02 10:53:36 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-05-02 10:53:36 +0200 |
commit | d159c5f40ff7e82354e45116d9b66b1f596d9320 (patch) | |
tree | 34506d9ee6c699444a170c6bba8c925c45407d3e /src/libproxy/proxy.h | |
parent | 8fec01ed4b95afc71bf7710bf5b736a5de03b343 (diff) | |
parent | 5272fb3d114f0d012871380bd429546c73f0226d (diff) | |
download | libproxy-git-d159c5f40ff7e82354e45116d9b66b1f596d9320.tar.gz |
Merge pull request #201 from janbrummer/rewrite
Complete rewrite
Diffstat (limited to 'src/libproxy/proxy.h')
-rw-r--r-- | src/libproxy/proxy.h | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/src/libproxy/proxy.h b/src/libproxy/proxy.h new file mode 100644 index 0000000..cf4fc34 --- /dev/null +++ b/src/libproxy/proxy.h @@ -0,0 +1,142 @@ +/* proxy.h + * + * Copyright 2022-2023 The Libproxy Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + * + * SPDX-License-Identifier: LGPL-2.1-or-later + */ + + +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +#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 +} +#endif |