Author: ctian Date: Tue Sep 14 23:35:27 2010 New Revision: 558
Log: API documentation for SOCKET-SERVER was added.
Modified: public_html/api-docs.shtml
Modified: public_html/api-docs.shtml ============================================================================== --- public_html/api-docs.shtml (original) +++ public_html/api-docs.shtml Tue Sep 14 23:35:27 2010 @@ -1,7 +1,7 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" lang="en"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> - <title>usocket API documentation</title> + <title>USOCKET API documentation</title> <link rel="stylesheet" type="text/css" href="style.css"> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> @@ -34,9 +34,8 @@ <li><a href="#docs">API documentation</a></li> <li><a href="#faqs">How do I ... (FAQ)</a></li> </ul> -<h1><a name="docs">usocket API documentation</a></h1> -<p style="font-size: 8px;">$Id: api-docs.shtml 417 2008-08-07 20:29:51Z -ehuelsmann $ <br> +<h1><a name="docs">USOCKET API documentation</a></h1> +<p style="font-size: 8px;">$Id$<br> Work in progress.</p> <p><em>Please note that we're committed to the interface described below for the entire 0.x phase of the library. When 1.0 comes @@ -44,10 +43,15 @@ and guarantees may change because of it.</em></p> <h2>Conventions</h2> <dl> - <dt>Specification of a <em>host</em> parameter</dt> - <dd>A <em>host</em> parameter may be any one of + <dt>Specification of a <em>host</em> or <em>local-host</em> +parameter</dt> + <dd>A <em>host</em> or <em>local-host</em> parameter may be any one +of <ul> <li>32-bit positive integer,</li> + <li>A four element integer list representing IPv4 address, i.e. +#(127 0 0 1)<br> + </li> <li>a string containing an IP addres in dotted notation, or</li> <li> a host name to be resolved through DNS lookup.</li> </ul> @@ -63,16 +67,13 @@ and <em>port</em> specified. The return value is a socket object of class <em><a href="#stream-usocket">stream-usocket</a></em>, or - - - <a href="#datagram-usocket"><em>datagram-usocket</em></a>.</p> <p><em>protocol</em> should be <code>:stream</code> (default) or <code>:datagram</code>, which means TCP or -UDP. <cite>(Start from USOCKET 0.5)</cite><br> +UDP <cite>(Start from USOCKET 0.5)</cite><br> <em>element-type</em> argument is used in the construction of the associated stream, i.e. <code>'character</code> or <code>'(unsigned-byte 8)</code>, only used by TCP.<br> @@ -169,7 +170,13 @@ the datagram socket -was created by <a href="#socket-connect"><em>socket-connect</em></a> +was +created +by + + + + <a href="#socket-connect"><em>socket-connect</em></a> with a <em>timeout</em> keyword argument, this function will block at most that timeout value (in seconds). (Start from USOCKET 0.5) </p> <p><em>socket</em> should be a <a href="#datagram-usocket"><em>datagram-usocket</em></a>.<br> @@ -197,14 +204,16 @@ (EINTR). The second value is a real number indicating the time remaining within the timeout period or nil if none.<br> <br> -Without the READY-ONLY arg, WAIT-FOR-INPUT will return all sockets in +Without the <em>ready-only</em> argument, WAIT-FOR-INPUT will return +all sockets in the original list you passed it. This prevents a new list from being consed up. Some users of USOCKET were reluctant to use it if it wouldn't behave that way, expecting it to cost significant performance to do the associated garbage collection.<br> <br> -Without the READY-ONLY arg, you need to check the socket STATE slot for -the values documented in usocket.lisp in the usocket class.<br> +Without the <em>ready-only</em> arg, you need to check the socket +STATE slot for +the values documented in <a href="#usocket"><em>usocket</em></a> class.<br> </p> </dd> <dt class="sym"><span class="function-name"><a name="socket-server"></a>socket-server</span> @@ -213,8 +222,58 @@ multi-threading<br> </dt> <dd> - <p>Create a simple TCP or UDP socket server ... (Start from USOCKET -0.5) </p> + <p>Create a simple TCP or UDP socket server. (Start from USOCKET +0.5)<br> + </p> + <p><em>host</em> names a local interface,<br> + <em>port</em> names a local port,<br> + <em>function</em> names a function object, which is used to handle +TCP or UDP connections, the actual API of this function will be +explained later.<br> + <em>arguments</em> is a list used for passing extra arguments to +user-defined <em>function</em>.<br> + <em>in-new-thread</em> is a boolean, default is <code>nil</code>. +When it's <code>T</code>, the server will be created in a new thread +and socket-server returns immediately in current thread.<br> + <em>protocol</em> could be either <code>:stream</code> (default) +or <code>:datagram</code>, which decide the socket server is TCP +server or UDP server.<br> + <em>timeout</em> is UDP only, it provides the internal <a + href="#socket-receive"><em>socket-receive</em></a> call (in UDP event +loop of the socket server) a read timeout, default value is 1 (second).<br> + <em>max-buffer-size</em> is UDP only, it's the max UDP data buffer +size when handling UDP packets, default value is 65507.<br> + <em>element-type</em> is TCP only, it's element-type of the stream +provided for user-defined function,<br> + <em>reuse-address</em> is TCP only, it's a boolean option for +internal call of socket-listen in the socket server,<br> + <em>multi-threading</em> is TCP only, it's a boolean, default value +is <code>nil</code>. When it's <code>T</code>, each client connection +will cause a new thread being created to handle that client, so that +the TCP server could handle multiple clients at the same time. (Note: +since UDP server is connectionless, it can always handle multiple +clients, as long as the handler function run fast enough)<br> + </p> + <p>The handler function for TCP is stream-based. A template +function +is this one: </p> + <pre>(defun default-tcp-handler (stream) ; null<br> (declare (type stream stream))<br> (terpri stream))</pre> + <p>Note: 1. you don't need to close the stream as <a + href="#socket-server"><em>socket-server</em></a> +will do that for you. +2. More function arguments can be defined, and these extra arguments +must be feeded as the optional <em>arguments</em> of <a + href="#socket-server"><em>socket-server</em></a>.</p> + <p>The handler function for UDP is buffer-based, that is, +you receive a buffer of data as input, and you return another buffer +for output. A template function is a simple UDP echo server:</p> + <pre>(defun default-udp-handler (buffer) ; echo<br> (declare (type (simple-array (unsigned-byte 8) *) buffer))<br> buffer)</pre> + <p>Note: 1. data length is the length of the whole buffer. 2. +Sometimes you may want to know the client's IP address and sending +port, these informations are specially bounded on variables + <a href="#remote-host"><em>*remote-host*</em></a> and <a + href="#remote-port"><em>*remote-port*</em></a> when handler function +is running.</p> </dd> </dl> <h2>Classes</h2> @@ -264,7 +323,10 @@ </dl> </dd> <dt class="sym"><span class="class-name"><a name="datagram-usocket">datagram-usocket -(Start from USOCKET 0.5)<br> +(Start +from +USOCKET +0.5)<br> </a></span></dt> <dd>Parent classes: usocket<br> Slots: @@ -294,17 +356,29 @@ retrieved from the returned socket by calling <em><a href="#get-local-port">get-local-port</a></em>.</p> </dd> - <dt class="sym"><span class="var-name">*remote-host*</span></dt> + <dt class="sym"><span class="var-name"><a name="remote-host"></a>*remote-host*</span></dt> <dd> <p>Special variable used in <a href="#socket-server"><em>socket-server</em></a>'s -handler function for getting current client address. (Start from +handler +function +for +getting +current +client +address. (Start from USOCKET 0.5)<br> </p> </dd> - <dt class="sym"><span class="var-name">*remote-port*</span></dt> + <dt class="sym"><span class="var-name"><a name="remote-port"></a>*remote-port*</span></dt> <dd> <p>Special variable used in <a href="api-docs.shtml#socket-server"><em>socket-server</em></a>'s -handler function for getting current client port. (Start from USOCKET +handler +function +for +getting +current +client +port. (Start from USOCKET 0.5)</p> </dd> </dl>