Warning: That file was not part of the compilation database. It may have many parsing errors.

1/*******************************************************************************
2 * libproxy - A library for proxy configuration
3 * Copyright (C) 2006 Nathaniel McCallum <nathaniel@natemccallum.com>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18 ******************************************************************************/
19
20#ifndef PROXY_H_
21#define PROXY_H_
22
23#ifdef __cplusplus
24extern "C"
25{
26#endif
27
28typedef struct pxProxyFactory_ pxProxyFactory;
29
30/**
31 * Creates a new pxProxyFactory instance. This instance should be kept
32 * around as long as possible as it contains cached data to increase
33 * performance. Memory usage should be minimal (cache is small) and the
34 * cache lifespan is handled automatically.
35 *
36 * @return A new pxProxyFactory instance or NULL on error
37 */
38pxProxyFactory *px_proxy_factory_new(void);
39
40/**
41 * Get which proxies to use for the specified URL.
42 *
43 * A NULL-terminated array of proxy strings is returned.
44 * If the first proxy fails, the second should be tried, etc...
45 * Don't forget to free the strings/array when you are done.
46 * If an unrecoverable error occurs, this function returns NULL.
47 *
48 * Regarding performance: this method always blocks and may be called
49 * in a separate thread (is thread-safe). In most cases, the time
50 * required to complete this function call is simply the time required
51 * to read the configuration (i.e. from gconf, kconfig, etc).
52 *
53 * In the case of PAC, if no valid PAC is found in the cache (i.e.
54 * configuration has changed, cache is invalid, etc), the PAC file is
55 * downloaded and inserted into the cache. This is the most expensive
56 * operation as the PAC is retrieved over the network. Once a PAC exists
57 * in the cache, it is merely a javascript invocation to evaluate the PAC.
58 * One should note that DNS can be called from within a PAC during
59 * javascript invocation.
60 *
61 * In the case of WPAD, WPAD is used to automatically locate a PAC on the
62 * network. Currently, we only use DNS for this, but other methods may
63 * be implemented in the future. Once the PAC is located, normal PAC
64 * performance (described above) applies.
65 *
66 * The format of the returned proxy strings are as follows:
67 * - http://[username:password@]proxy:port
68 * - socks://[username:password@]proxy:port
69 * - socks5://[username:password@]proxy:port
70 * - socks4://[username:password@]proxy:port
71 * - <procotol>://[username:password@]proxy:port
72 * - direct://
73 * Please note that the username and password in the above URLs are optional
74 * and should be use to authenticate the connection if present.
75 *
76 * For SOCKS proxies, when the protocol version is specified (socks4:// or
77 * sock5://), it is expected that only this version is used. When only
78 * socks:// is set, the client MUST try SOCKS version 5 protocol and, on
79 * connection failure, fallback to SOCKS version 4.
80 *
81 * Other proxying protocols may exist. It is expected that the returned
82 * configuration scheme shall match the network service name of the
83 * proxy protocol or the service name of the protocol being proxied if the
84 * previous does not exist. As an example, on Mac OS X you can configure a
85 * RTSP streaming proxy. The expected returned configuration would be:
86 * - rtsp://[username:password@]proxy:port
87 *
88 * @url The URL we are trying to reach
89 * @return A NULL-terminated array of proxy strings to use
90 */
91char **px_proxy_factory_get_proxies(pxProxyFactory *self, const char *url);
92
93/**
94 * Frees the pxProxyFactory instance when no longer used.
95 */
96void px_proxy_factory_free(pxProxyFactory *self);
97
98#ifdef __cplusplus
99}
100#endif
101
102#endif /*PROXY_H_*/
103

Warning: That file was not part of the compilation database. It may have many parsing errors.