<!-- ** Proxy connections

     $Id: sect_proxy.docbook 755 2005-06-26 15:26:24Z ewald-arnold $
-->

<sect1 id="proxy">
<title>Connections Via a Proxy Server</title>

<para>Clients in a production environment are often behind a restrictive firewall.
To connect
to a server in the outside world this client must then connect via a proxy server.
Sometimes the client even has to authenticate with the proxy with a
user identifier and a password. &ulxmlrpcpp; supports both variants.</para>

<sect2 id="transparent-proxy">
<title>Transparently Using a Proxy Server</title>

<para>To turn on proxy usage within &ulxmlrpcpp; the following code is
needed:

<programlisting>

  TcpIpConnection conn (false, host, port);
  conn.setProxy("sonne", 8080); <co  id="proxy-server-co" linkends="proxy-server-link" />

  HttpProtocol prot(&amp;conn);
  prot.setProxyAuthentication("proxyuser", "proxypassword");  <co  id="proxy-auth-co" linkends="proxy-auth-link" />

</programlisting>

<calloutlist>

 <callout arearefs="proxy-server-co" id="proxy-server-link">
  <para>Tell the <classname>Connection</classname> object which proxy server
  and port to use.</para>
 </callout>

 <callout arearefs="proxy-auth-co" id="proxy-auth-link">
  <para>Pass the <classname>Protocol</classname> object the username and
  password for the proxy.</para>
 </callout>

</calloutlist>

</para>

</sect2>


<sect2 id="connect-proxy">
<title>A SSL Connection over a Proxy Server</title>

<para>When using SSL connections it is not possible to send the authentication
credentials within the HTTP header. Since the connection is encrypted the
proxy server can't extract the credentials. For that reason proxies support
a special mode called HTTP CONNECT. In this mode the client sends an unencrypted
CONNECT header with the credentials to the proxy server. The proxy then establishes
a basic connection with the server. Afterwards the client turns encryption on
and continues as usual.</para>

<para>

<calloutlist>

 <callout id="proxy-connect-link" arearefs="proxy-connect-co" >
  <para>The only thing you have to do is to turn this behaviour on.</para>
 </callout>

</calloutlist>

<programlisting>

  TcpIpConnection conn (false, host, port);
  conn.setProxy("sonne", 8080);

  HttpProtocol prot(&amp;conn);
  prot.setProxyAuthentication("proxyuser", "proxypassword");

  prot.enableConnect(); <co  id="proxy-connect-co" linkends="proxy-connect-link" />

</programlisting>

</para>

</sect2>

</sect1>
