1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
/*******************************************************************************
* libproxy - A library for proxy configuration
* Copyright (C) 2006 Nathaniel McCallum <nathaniel@natemccallum.com>
*
* 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
******************************************************************************/
#ifndef PROXY_H_
#define PROXY_H_
#ifdef __cplusplus
extern "C"
{
#endif
typedef struct pxProxyFactory_ pxProxyFactory;
/**
* 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.
*
* @return A new pxProxyFactory instance or NULL on error
*/
pxProxyFactory *px_proxy_factory_new(void);
/**
* 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
* sock5://), 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
*
* @url The URL we are trying to reach
* @return A NULL-terminated array of proxy strings to use
*/
char **px_proxy_factory_get_proxies(pxProxyFactory *self, const char *url);
/**
* Frees the pxProxyFactory instance when no longer used.
*/
void px_proxy_factory_free(pxProxyFactory *self);
#ifdef __cplusplus
}
#endif
#endif /*PROXY_H_*/
|
