Author: ehuelsmann Date: Mon May 7 13:50:47 2007 New Revision: 229
Added: public_html/api-docs.shtml (contents, props changed) Log: Add public API documentation (WIP).
Added: public_html/api-docs.shtml ============================================================================== --- (empty file) +++ public_html/api-docs.shtml Mon May 7 13:50:47 2007 @@ -0,0 +1,144 @@ +<?xml version="1.0"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> + <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"/> + <style type="text/css"> +dt.sym { font-weight: normal; width: 100%; background-color: #8ca } +.function-name { font-weight: bold } +.class-name { font-weight: bold } +.slot-name { font-weight: bold } +.var-name { font-weight: bold } + </style> +</head> +<body> +<h1>usocket API documentation</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 +some of the functionality may be split up in different functions +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 + <ul> + <li>32-bit positive integer, + <li>a string containing an IP addres in dotted notation, or + <li> a host name to be resolved through DNS lookup. + </ul> +</dd> +</dl> + +<h2>Functions for socket creation and manipulation</h2> + +<dl> +<dt class="sym"><span class=function-name>socket-connect</span> host port &key element-type => socket</dt> + +<dd> +<p>Creates a tcp (stream) socket to the <em>host</em> and <em>port</em> specified. The return value is +a socket object of class <em><a href="#stream-usocket">stream-usocket</a></em>.</p> + +<p>The <em>element-type</em> argument is used in the +construction of the associated stream.</p></dd> + +<dt class="sym"> +<span class=function-name>socket-listen</span> host port &key reuse-address backlog element-type => socket</dt> +<dd><p>Creates and returns a passive ("server") socket associated with <em>host</em> and <em>port</em>. + The object returned is of subtype <a href="#stream-server-usocket">stream-server-usocket</a>.</p> + <p><em>host</em> names a local interface.<br /> + <em>port</em> names a local port, or 0 (zero) to request a random free port.<br /> + <em>reuse-address</em> is a boolean (t, nil) value signalling reuse of the address is requested (or not).<br /> + <em>backlog</em> is the length of the queue containing connections which haven't actually been accepted yet.<br /> + <em>element-type</em> is the default element type used for sockets created by socket-accept. <em>character</em> is + the default when it's not explicitly provided. + </p></dd> + + +<dt class="sym"><span class=function-name><a name="socket-accept">socket-accept</a></span> socket &key element-type => new-socket</dt> +<dd><p>Creates and returns an active ("connected") stream socket <em>new-socket</em> from the + <em>socket</em> passed. The return value is a socket object of class + <em><a href="#stream-usocket">stream-usocket</a></em>.</p> + <p><em>element-type</em> is the element type used to construct the associated stream. If it's not specified, + the element-type of <em>socket</em> (as used when it was created by the call to socket-listen) is + used. + </p> +</dd> + +<dt class="sym"><span class=function-name>socket-close</span> socket</dt> +<dd><p>Flushes the stream associated with the socket and closes the socket connection.</p></dd> + + +<!-- Items to document: + +Informational functions: +get-local-address +get-peer-address +get-local-port +get-peer-port +get-local-name +get-peer-name + + + --> + +</dl> + +<h2>Classes</h2> + +<dl> + <dt class="sym"><span class="class-name"><a name="usocket">usocket</a></span></dt> + <dd>Slots: + <dl> + <dt><span class="slot-name">socket</span> :accessor socket</td> + <dd><p>Used to store sockets as used by the current implementation - may be any of socket handles, socket objects and stream objects</p></dd></dl> + </dd> + +<dt class="sym"><span class="class-name"><a name="stream-usocket">stream-usocket</a></span></dt> +<dd>Parent classes: usocket<br /> + Slots: + <dl> + <dt><span class="slot-name">stream</span> :accessor socket-stream</td> + <dd><p>Used to store the stream associated with the tcp socket connection.<br /> + When you want to write to the socket stream, use this function.</p></dd></dl> +</dd> + +<dt class="sym"><span class="class-name"><a name="stream-server-usocket">stream-server-usocket</a></span></dt> +<dd>Parent classes: usocket<br /> + Slots: + <dl> + <dt><span class="slot-name">element-type</span> :reader element-type</td> + <dd><p>Indicates the default element-type to be used when constructing streams off this socket when + no element type is specified in the call to <em><a href="#socket-accept">socket-accept</a></em>.</p></dd></dl> +</dd> +</dl> + +<h2>Variables / constants</h2> + +<dl> +<dt class="sym"><span class="var-name">*wildcard-host*</span></dt> +<dd><p>The host to use with socket-listen to make the socket listen on all available interfaces.</p></dd> +<dt class="sym"><span class="var-name">*auto-port*</span></dt> +<dd><p>The port number to use with socket-listen to make the socket listen on a random available port. The port number assigned can be + retrieved from the returned socket by calling <em><a href="#get-local-port">get-local-port</a></em>.</p></dd> +</dl> + +<div style="float:left;font-size:x-small;font-weight:bold"> +Back to <a href="http://common-lisp.net/">Common-lisp.net</a>. +</div> + <div class="check" style="float:right"> + <a href="http://validator.w3.org/check/referer">Valid XHTML 1.0 Strict</a> + </div> + +</body> +</html>