[usocket-cvs] r229 - public_html
ehuelsmann at common-lisp.net
ehuelsmann at common-lisp.net
Mon May 7 17:50:49 UTC 2007
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>
More information about the usocket-cvs
mailing list