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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<refentry id="refproxy">
<refmeta>
<refentrytitle>ne_session_proxy</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname id="ne_session_proxy">ne_session_proxy</refname>
<refname id="ne_session_socks_proxy">ne_session_socks_proxy</refname>
<refname id="ne_session_system_proxy">ne_session_system_proxy</refname>
<refname id="ne_set_addrlist">ne_set_addrlist</refname>
<refpurpose>configure proxy servers</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ne_session.h></funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>ne_session_proxy</function></funcdef>
<paramdef>ne_session *<parameter>session</parameter></paramdef>
<paramdef>const char *<parameter>hostname</parameter></paramdef>
<paramdef>unsigned int <parameter>port</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ne_session_system_proxy</function></funcdef>
<paramdef>ne_session *<parameter>session</parameter></paramdef>
<paramdef>unsigned int <parameter>flags</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ne_session_socks_proxy</function></funcdef>
<paramdef>ne_session *<parameter>session</parameter></paramdef>
<paramdef>enum ne_sock_sversion <parameter>version</parameter></paramdef>
<paramdef>const char *<parameter>hostname</parameter></paramdef>
<paramdef>unsigned int <parameter>port</parameter></paramdef>
<paramdef>const char *<parameter>username</parameter></paramdef>
<paramdef>const char *<parameter>password</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ne_set_addrlist</function></funcdef>
<paramdef>ne_session *<parameter>session</parameter></paramdef>
<paramdef>const ne_inet_addr **<parameter>addrlist</parameter></paramdef>
<paramdef>size_t <parameter>count</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>One (and no more than one) of the functions
<function>ne_session_proxy</function>,
<function>ne_session_system_proxy</function>,
<function>ne_session_socks_proxy</function>,
<function>ne_set_addrlist</function> can be used to configure
a proxy server for a given session object. If more than one
function is invoked for any given session object, only the
last call has effect. If one of the functions is to be used,
it must be used before the creation of any request object for
the session.</para>
<refsect2>
<title>HTTP proxy specification</title>
<para>The <function>ne_session_proxy</function> function
configures use of an HTTP proxy server for the session, the
location of which is given by the
<parameter>hostname</parameter> and
<parameter>port</parameter> parameters. If the proxy
requires authentication, <xref linkend="ne_set_proxy_auth"/>
should be used.</para>
</refsect2>
<refsect2>
<title>System proxy configuration</title>
<para>The <function>ne_session_system_proxy</function>
function configures the session to use any proxy servers
specified by the system configuration. Support for this
function is platform-specific; if unsupported, the function
has no effect.</para>
</refsect2>
<refsect2>
<title>SOCKS proxy configuration</title>
<para>The <function>ne_session_socks_proxy</function>
function configures the session to use a SOCKS proxy. The
<parameter>version</parameter> indicates which version of
the SOCKS protocol should be used. The
<parameter>hostname</parameter> and
<parameter>port</parameter> parameters specify the SOCKS
proxy location. Note that a server with only an IPv6
address cannot be used with SOCKS v4 or v4A. The
interpretation of the other arguments depends on the version
specified:</para>
<variablelist>
<varlistentry><term><constant>NE_SOCK_SOCKSV4</constant> (version 4)</term>
<listitem>
<simpara>The <parameter>username</parameter> parameter
must be non-&null;; the <parameter>password</parameter>
parameter is ignored.</simpara>
</listitem>
</varlistentry>
<varlistentry><term><constant>NE_SOCK_SOCKSV4A</constant> (version 4A)</term>
<listitem>
<simpara>The <parameter>username</parameter> parameter
must be non-&null;; the <parameter>password</parameter>
parameter is ignored.</simpara>
</listitem>
</varlistentry>
<varlistentry><term><constant>NE_SOCK_SOCKSV5</constant> (version 5)</term>
<listitem>
<simpara>The <parameter>username</parameter> parameter
may be &null;; if it is non-&null;,
the <parameter>password</parameter> parameter must also
be non-&null;; otherwise, it is ignored..</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Origin server address override</title>
<para>The <function>ne_set_addrlist</function> function
forces use of an address and port the a specified list when
establishing a TCP connection, ignoring the "real" hostname
and port identifying the origin server for the session (as
passed to <function>ne_session_create</function>). The
origin server's "real" hostname and port will still be used
in the <literal>Host</literal> header in HTTP requests.
When a connection is required, the library will iterate
through the <parameter>addrlist</parameter> list, attempting
to connect to the address <parameter>addrlist[0]</parameter>
through to <parameter>addrlist[count-1]</parameter> in turn,
until a connection can be established.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Return Values</title>
<para>None of the functions described here has a return
value.</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>Create and destroy a session:</para>
<programlisting>ne_session *sess;
sess = ne_session_create("http", "host.example.com", 80);
ne_session_proxy(sess, "proxy.example.com", 3128);
/* ... use sess ... */
ne_session_destroy(sess);
</programlisting>
</refsect1>
<refsect1>
<title>See Also</title>
<para><xref linkend="ne_ssl_set_verify"/>, <xref linkend="ne_ssl_trust_cert"/>, <xref linkend="ne_sock_init"/>, <xref linkend="ne_set_session_flag"/></para>
</refsect1>
</refentry>
|
