[Refdb-cvs] CVS: refdb/doc refdb-manual-chapter23.sgml,NONE,1.1.2.1

[Markus H. <mho...@us...>]

Update of /cvsroot/refdb/refdb/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv32064

Added Files:
      Tag: Release_0_9_5_stable
	refdb-manual-chapter23.sgml 
Log Message:
initial version

--- NEW FILE ---
<!-- $Id: refdb-manual-chapter23.sgml,v 1.1.2.1 2005/08/14 00:32:14 mhoenicka Exp $ -->
<chapter id="chapter-cs-protocol">
  <title>The &appname; client/server communication protocol</title>
  <para>This chapter describes the communication protocol that the &appname; clients and server use to talk to each other. Knowledge of this protocol is useful for programmers who want to write custom &appname; clients.</para>
  <tip>
    <para>The &appname; project provides a Perl client module in addition to the C clients shipped with the &appname; package proper. Due to the simplicity of the Perl language, this module is a good resource for programmers who want to implement clients in other programming languages.</para>
  </tip>
  <sect1>
    <title>Prerequisites</title>
    <para>Custom clients or client libraries can be implemented in any programming language that can create a Unix socket connection to the server and send/receive byte sequences through the socket. As the transferred data are essentially plain text, the endianness of the computer as well as the internal representation of data types in the particular programming language are irrelevant.</para>
  </sect1>
  <sect1>
    <title>Basic principles</title>
    <para>&appname;d is implemented as a forking server. The parent process waits to accept connections from the clients. If a valid connection request is detected, the server forks. The parent closes the connection and is ready to respond to further requests. The child processes the client request and terminates when done.</para>
    <para>The communication between the client and the server is at least a two-stage process. In the first stage, the validity of the client request is checked, the protocol version is checked and the password encryption is initiated. In the second stage, the command proper is executed and the results are sent back to the client. The second stage may use several iterations of client/server messages in order to transfer larger amounts of data.</para>
    <sect2>
      <title>Message format</title>
      <para>All data, that is client commands as well as the server-generated results, are sent as plain text. We have to distinguish between three types of messages:</para>
      <variablelist>
[...2725 lines suppressed...]
	    </tbody>
	  </tgroup>
	</informaltable>
      </sect3>
    </sect2>
    <sect2 id="sect-statusmessages">
      <title>Status messages</title>
      <note>
	<para>The status codes which are multiples of 100 are not associated with a fixed message. Instead, clients should retrieve the terminated string sent after these codes to read the dynamically generated message.</para>
      </note>
&statustable;
    </sect2>
  </sect1>
</chapter>

<!--
Local Variables:
sgml-parent-document: ("refdb-manual.sgml" "BOOK PART")
End:
-->