Author: ctian Date: Tue Sep 14 13:37:36 2010 New Revision: 557
Log: Updated USOCKET Web Documents
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 13:37:36 2010 @@ -1,11 +1,10 @@ -<?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"> +<!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"> <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"/> + <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; @@ -31,223 +30,346 @@ </style> </head> <body> - <ul> -<li><a href="#docs">API documentation</a></li> -<li><a href="#faqs">How do I ... (FAQ)</a></li> + <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$ <br /> - Work in progress.</p> - +<p style="font-size: 8px;">$Id: api-docs.shtml 417 2008-08-07 20:29:51Z +ehuelsmann $ <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 +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 + <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> - <li>a string containing an IP addres in dotted notation, or</li> - <li> a host name to be resolved through DNS lookup.</li> + <li>32-bit positive integer,</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> -</dd> + </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> + <dt class="sym"><span class="function-name"><a name="socket-connect">socket-connect</a></span> +host port &key protocol element-type timeout deadline nodelay +local-host local-port => socket</dt> + <dd> + <p>Creates a TCP (stream) or UDP (datagram) 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>, +or
-<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. + + + <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> + <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> + <em>timeout</em> is a integer, it represents the socket option <code>SO_RCVTIMEO</code> +(read timeout), in seconds.<br> + <em>deadline</em> is only supported in Clozure CL and Digitool MCL, +look up their documents please.<br> + <em>local-host</em> and <em>local-port</em>, when specified, will +cause the socket calling bind() on local address. This is useful for +selecting interfaces to send, or listening on UDP port. Note: use only +one of them are allowed when reasonable (listen on wildcard address, or +bind to random free port). <br> + <br> + </p> + </dd> + <dt class="sym"> <span class="function-name"><a name="socket-listen"></a>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"><a name="socket-close"></a>socket-close</span> +socket</dt> + <dd> + <p>Flushes the stream associated with the socket and closes the +socket connection.</p> + </dd> + <dt class="sym"><span class="function-name"><a name="get-local-name"></a>get-local-name</span> +socket => address, port<br> + <span class="function-name"><a name="get-local-address"></a>get-local-address</span> +socket => address<br> + <span class="function-name"><a name="get-local-port"></a>get-local-port</span> +socket => port</dt> + <dd> + <p>Returns the local address and/or port information of socket.</p> + </dd> + <dt class="sym"><span class="function-name"><a name="get-peer-name"></a>get-peer-name</span> +socket => address, port<br> + <span class="function-name"><a name="get-peer-address"></a>get-peer-address</span> +socket => address<br> + <span class="function-name"><a name="get-peer-port"></a>get-peer-port</span> +socket => port</dt> + <dd> + <p>Returns the remote address and/or port information of socket. +The socket passed to this function must be a <em>connected</em> socket.</p> + </dd> + <dt class="sym"><span class="function-name"><a name="socket-send"></a>socket-send</span> +socket buffer length &key host port<br> + </dt> + <dd> + <p>Send a (unsigned-byte 8) data buffer to a datagram socket, and +return the number of bytes sent. (Start from USOCKET 0.5)</p> + <p><em>socket</em> should be a <a href="#datagram-usocket"><em>datagram-usocket</em></a>.<br> + <em>buffer</em> is a Lisp vector, type of <code>(simple-array +(unsigned-byte 8) *)</code>.<br> + <em>length</em> is used to tell <a href="#socket-send"><em>socket-send</em></a> +the actual useful length of data buffer for sending to socket.<br> + <em>host</em> and <em>port</em> are used for unconnected datagram +sockets, for sending to specific destination.<br> </p> -</dd> + </dd> + <dt class="sym"><span class="function-name"><a name="socket-receive"></a>socket-receive</span> +socket buffer length<br> + </dt> + <dd> + <p>Receive data from a datagram socket, and return 4 values: <em>return-buffer</em>,
-<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>
-<dt class="sym"><span class="function-name">get-local-name</span> socket => address, port<br/> -<span class="function-name">get-local-name</span> socket => address<br/> -<span class="function-name">get-local-port</span> socket => port</dt> -<dd><p>Returns the local address and/or port information of socket.</p></dd> - -<dt class="sym"><span class="function-name">get-peer-name</span> socket => address, port<br/> -<span class="function-name">get-peer-name</span> socket => address<br/> -<span class="function-name">get-peer-port</span> socket => port</dt> -<dd><p>Returns the remote address and/or port information of socket. - The socket passed to this function must be a <em>connected</em> socket.</p></dd>
+ <em>return-length</em>, <em>remote-host</em>, and <em>remove-port</em>. +If +the +datagram +socket +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> + <em>buffer</em> is a Lisp vector, type of <code>(simple-array +(unsigned-byte 8) *)</code>. Using <code>nil</code> here is also +allowed, new buffer will be created to hold data.<br> + <em>length</em> is used to specify the length of a exist buffer for +receiving at most these data. Using <em>nil</em> here is allowed, and +the actual length of <em>buffer</em> will be used; when <em>buffer</em> +is also <code>nil</code>, a default maximum length (65507) will be +used. <br> + </p> + </dd> + <dt class="sym"><span class="function-name"><a name="wait-for-input"></a>wait-for-input</span> +socket-or-sockets &key timeout ready-only<br> + </dt> + <dd> + <p>Waiting on one or multiple sockets for given time, and returns +once some of them are available of reading data. This is like UNIX's +"select" function.<br> + <br> +It returns two values: the first is the list of sockets which are +readable (or in case of server sockets acceptable). nil may be returned +for this value either when waiting timed out or when it was interrupted +(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 +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> + </p> + </dd> + <dt class="sym"><span class="function-name"><a name="socket-server"></a>socket-server</span> +host port function &optional arguments &key in-new-thread +protocol timeout max-buffer-size element-type reuse-address +multi-threading<br> + </dt> + <dd> + <p>Create a simple TCP or UDP socket server ... (Start from USOCKET +0.5) </p> + </dd> </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</dt> - <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> + <dt><span class="slot-name">socket</span> :accessor socket<br> + </dt> + <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> + <dt><span class="slot-name">state</span> :accessor state<br> + </dt> + <dd> + <p>Used to store socket state: NIL (not ready), :READ (ready to +read).<br> + </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: + <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</dt> + <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">stream</span> :accessor socket-stream</dt> - <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: + <dt><span class="slot-name">element-type</span> :reader +element-type</dt> + <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> + <dt class="sym"><span class="class-name"><a name="datagram-usocket">datagram-usocket +(Start from USOCKET 0.5)<br> + </a></span></dt> + <dd>Parent classes: usocket<br> +Slots: <dl> - <dt><span class="slot-name">element-type</span> :reader element-type</dt> - <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> + <dt><span class="slot-name">connected-p</span> :accessor +connected-p</dt> + <dd> + <p>Used to identify if the datagram is connected. It will be +setup by <a href="#socket-connect"><em>socket-connect</em></a>, and +used by <a href="#socket-send"><em>socket-send</em></a> and <a + href="#socket-receive"><em>socket-receive</em></a>.</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> + <dt class="sym"><span class="var-name">*wildcard-host*</span></dt> + <dd> + <p>The host to use with <a href="#socket-listen"><em>socket-listen</em></a> +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> + <dt class="sym"><span class="var-name">*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 +USOCKET 0.5)<br> + </p> + </dd> + <dt class="sym"><span class="var-name">*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 +0.5)</p> + </dd> </dl> - - <h1><a name="faqs">How do I ...</a></h1> - <dl class="faq"> -<dt>... force the output to be written to the network? -</dt> -<dd>When you write output to the stream, it may be buffered before - sent over the network - for optimal performance of small writes. You - can force the buffer to be flushed the same way as with normal streams: - -<pre>(format (socket-stream socket) "Hello there~%") ;; output into buffers -(force-output (socket-stream socket)) ;; <== flush the buffers, if any -</pre> -</dd> -<dt>... check whether the other end has closed my socket stream? -</dt> -<dd>Reading from a stream which has been closed at the remote end - signals an END-OF-FILE condition, meaning that reading from the stream - and detecting that condition is the way to do it. -</dd> -<dt>... check whether reading from a socket stream will block? -</dt> -<dd>When you want to check <b>one</b> stream for readiness of input, - call the - <a href="http://www.lisp.org/HyperSpec/Body/fun_listen.html">listen</a> - function on the stream object associated with the socket.<br /> - Example: -<pre>(listen (usocket:socket-stream your-socket)) - ==> NIL (if no input is available) -</pre> -</dd> -<dt>... wait for input to become available on (at least) one stream (of a set) -</dt> -<dd>Currently, that's hard to do efficiently if you want to use releases. - The next minor release (0.4.0) will include this functionality and - for all platforms (except SBCL and LispWorks; both Win32) it's already - available in trunk (svn://common-lisp.net/project/usocket/svn/usocket/trunk). - <br /> - If you want to use this code you're most welcome and feedback is appreciated.<br /> - Example to be used with trunk: -<pre>(usocket:wait-for-input (list socket1 socket2 socket3) :timeout <your optional timeout value>) - ==> list-of-sockets-to-read-from</pre> -</dd> -<dt>... convert my existing trivial-sockets based application to usocket? -</dt> -<dd>There are actually 3 answers to that question. - <ol> - <li>Rewrite your code to keep a usocket object instead of the stream - object returned by trivial-sockets.</li> - <li>The quick conversion with the good performance characteristics - (use only when you don't want to use the socket object):<br /> - Replace all your invocations of -<pre> - (trivial-sockets:open-socket-stream ....) - -with - (usocket:socket-stream (usocket:socket-connect ...)) -</pre> - + <dt>... force the output to be written to the network? </dt> + <dd>When you write output to the stream, it may be buffered before +sent over the network - for optimal performance of small writes. You +can force the buffer to be flushed the same way as with normal streams: + <pre>(format (socket-stream socket) "Hello there~%") ;; output into buffers<br>(force-output (socket-stream socket)) ;; <== flush the buffers, if any<br></pre> + </dd> + <dt>... check whether the other end has closed my socket stream? </dt> + <dd>Reading from a stream which has been closed at the remote end +signals an END-OF-FILE condition, meaning that reading from the stream +and detecting that condition is the way to do it. </dd> + <dt>... check whether reading from a socket stream will block? </dt> + <dd>When you want to check <b>one</b> stream for readiness of input, +call the <a href="http://www.lisp.org/HyperSpec/Body/fun_listen.html">listen</a> +function on the stream object associated with the socket.<br> +Example: + <pre>(listen (usocket:socket-stream your-socket))<br> ==> NIL (if no input is available)<br></pre> + </dd> + <dt>... wait for input to become available on (at least) one stream +(of a set) </dt> + <dd>Currently, that's hard to do efficiently if you want to use +releases. The next minor release (0.4.0) will include this +functionality and for all platforms (except SBCL and LispWorks; both +Win32) it's already available in trunk +(svn://common-lisp.net/project/usocket/svn/usocket/trunk). <br> +If you want to use this code you're most welcome and feedback is +appreciated.<br> +Example to be used with trunk: + <pre>(usocket:wait-for-input (list socket1 socket2 socket3) :timeout <your optional timeout value>)<br> ==> list-of-sockets-to-read-from</pre> + </dd> + <dt>... convert my existing trivial-sockets based application to +usocket? </dt> + <dd>There are actually 3 answers to that question. + <ol> + <li>Rewrite your code to keep a usocket object instead of the +stream object returned by trivial-sockets.</li> + <li>The quick conversion with the good performance +characteristics (use only when you don't want to use the socket object):<br> +Replace all your invocations of + <pre> (trivial-sockets:open-socket-stream ....)<br><br>with<br> (usocket:socket-stream (usocket:socket-connect ...))<br></pre> And replace all invocations of -<pre> - (trivial-sockets:socket-accept ...) - -with - (usocket:socket-stream (usocket:socket-accept ...)) -</pre> - + <pre> (trivial-sockets:socket-accept ...)<br><br>with<br> (usocket:socket-stream (usocket:socket-accept ...))<br></pre> And replace all invocations of -<pre> - (trivial-sockets:open-server ...) - -with - (usocket:socket-listen ...) -</pre></li> - <li>And the last option which provides a compatible - (but slower, because it uses Gray streams) interface is to use - trivial-usocket.<br /> - The trivial-usocket package provides a 1-1 mapped interface to - trivial-sockets, but uses Gray streams; that way, it's later possible - to retrieve the socket object from the stream returned and to use that - socket for other usocket operations. Use this approach as a migration - path where you're not rewriting your application at once, but in - small steps. + <pre> (trivial-sockets:open-server ...)<br><br>with<br> (usocket:socket-listen ...)<br></pre> </li> + <li>And the last option which provides a compatible (but slower, +because it uses Gray streams) interface is to use trivial-usocket.<br> +The trivial-usocket package provides a 1-1 mapped interface to +trivial-sockets, but uses Gray streams; that way, it's later possible +to retrieve the socket object from the stream returned and to use that +socket for other usocket operations. Use this approach as a migration +path where you're not rewriting your application at once, but in small +steps. </li> </ol> -</dd> - + </dd> </dl> - - -<div style="float:left;font-size:x-small;font-weight:bold"> +<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> +<div class="check" style="float: right;"> <a + href="http://validator.w3.org/check/referer%22%3EValid XHTML 1.0 Strict</a> +</div> </body> </html>