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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
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
|
