<!-- ** Cookie management

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

<sect1 id="cookie">
<title>Tracking Partners With Cookies</title>

<para>Sometimes a server needs some session management to keep track of the clients
involved. One solution would be, to add an extra parameter representing some unique
identifier to each method invocation and return value. But this means additional
work for each possible method call.</para>

<para>A more convenient solution when using HTTP as transportation media is
to apply cookie management. In this case the server checks the incoming HTTP header
for a special line with session information. This is called a cookie. If the
information is missing, the server adds one to the response. The client is then
expected to store the cookie and add it to further requests if appropriate.</para>

<sect2 id="server-cookie">
<title>Cookies in Server Mode</title>

<para>To use cookies on the server side the following steps are needed:

<programlisting>

  TcpIpConnection conn (true, host, port);
  HttpProtocol prot(&amp;conn);

  prot.setAcceptCookies(true);  <co  id="cookie-serv-ena-co" linkends="cookie-serv-ena-link" />

  if (prot.hasCookie()) <co  id="cookie-serv-get-co" linkends="cookie-serv-get-link" />
    prot.getCookie();

  prot.setServerCookie("cookie-test=123"); <co  id="cookie-serv-set-co" linkends="cookie-serv-set-link" />

</programlisting>

<calloutlist>

  <callout arearefs="cookie-serv-ena-co" id="cookie-serv-ena-link">
    <para>Enable cookie managent. Otherwise cookies are completely ignored.</para>
  </callout>

  <callout arearefs="cookie-serv-get-co" id="cookie-serv-get-link">
    <para>Check for incoming cookie information and use it.</para>
  </callout>

  <callout arearefs="cookie-serv-set-co" id="cookie-serv-set-link">
    <para>Add a cookie to further responses over this protocol object.</para>
  </callout>

</calloutlist>

</para>

</sect2>


<sect2 id="client-cookie">
<title>Cookies in Client Mode</title>

<para>On the client side you have to do the following to benefit form
session management with cookies:

<programlisting>

  TcpIpConnection conn (false, host, port);
  HttpProtocol prot(&amp;conn);

  prot.setAcceptCookies(true);  <co  id="cookie-clnt-ena-co" linkends="cookie-clnt-ena-link" />

  prot.setClientCookie("cookie-test=123"); <co  id="cookie-clnt-set-co" linkends="cookie-clnt-set-link" />

  if (prot.hasCookie())
    prot.getCookie(); <co  id="cookie-clnt-get-co" linkends="cookie-clnt-get-link" />

</programlisting>

<calloutlist>

 <callout arearefs="cookie-clnt-ena-co" id="cookie-clnt-ena-link">
  <para>Enable cookie managent. Otherwise cookies are completely ignored.</para>
 </callout>

 <callout arearefs="cookie-clnt-set-co" id="cookie-clnt-set-link">
  <para>Add a cookie to the request if available.</para>
 </callout>

 <callout arearefs="cookie-clnt-get-co" id="cookie-clnt-get-link">
  <para>Check for incoming cookie information and store for later re-use.</para>
 </callout>

</calloutlist>


</para>

</sect2>

</sect1>
