usocket API documentation

$Id: api-docs.shtml 417 2008-08-07 20:29:51Z ehuelsmann $
Work in progress.

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.

Conventions

Specification of a host parameter
A host parameter may be any one of

Functions for socket creation and manipulation

socket-connect host port &key element-type => socket

Creates a tcp (stream) socket to the host and port specified. The return value is a socket object of class stream-usocket.

The element-type argument is used in the construction of the associated stream.

socket-listen host port &key reuse-address backlog element-type => socket

Creates and returns a passive ("server") socket associated with host and port. The object returned is of subtype stream-server-usocket.

host names a local interface.
port names a local port, or 0 (zero) to request a random free port.
reuse-address is a boolean (t, nil) value signalling reuse of the address is requested (or not).
backlog is the length of the queue containing connections which haven't actually been accepted yet.
element-type is the default element type used for sockets created by socket-accept. character is the default when it's not explicitly provided.

socket-accept socket &key element-type => new-socket

Creates and returns an active ("connected") stream socket new-socket from the socket passed. The return value is a socket object of class stream-usocket.

element-type is the element type used to construct the associated stream. If it's not specified, the element-type of socket (as used when it was created by the call to socket-listen) is used.

socket-close socket

Flushes the stream associated with the socket and closes the socket connection.

get-local-name socket => address, port
get-local-name socket => address
get-local-port socket => port

Returns the local address and/or port information of socket.

get-peer-name socket => address, port
get-peer-name socket => address
get-peer-port socket => port

Returns the remote address and/or port information of socket. The socket passed to this function must be a connected socket.

Classes

usocket
Slots:
socket :accessor socket

Used to store sockets as used by the current implementation - may be any of socket handles, socket objects and stream objects

stream-usocket
Parent classes: usocket
Slots:
stream :accessor socket-stream

Used to store the stream associated with the tcp socket connection.
When you want to write to the socket stream, use this function.

stream-server-usocket
Parent classes: usocket
Slots:
element-type :reader element-type

Indicates the default element-type to be used when constructing streams off this socket when no element type is specified in the call to socket-accept.

Variables / constants

*wildcard-host*

The host to use with socket-listen to make the socket listen on all available interfaces.

*auto-port*

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 get-local-port.

How do I ...

... force the output to be written to the network?
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: 
(format (socket-stream socket) "Hello there~%")   ;; output into buffers
(force-output (socket-stream socket))             ;; <== flush the buffers, if any
... check whether the other end has closed my socket stream?
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.
... check whether reading from a socket stream will block?
When you want to check one stream for readiness of input, call the listen function on the stream object associated with the socket.
Example: 
(listen (usocket:socket-stream your-socket))
 ==> NIL (if no input is available)
... wait for input to become available on (at least) one stream (of a set)
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).
If you want to use this code you're most welcome and feedback is appreciated.
Example to be used with trunk: 
(usocket:wait-for-input (list socket1 socket2 socket3) :timeout <your optional timeout value>)
 ==> list-of-sockets-to-read-from
... convert my existing trivial-sockets based application to usocket?
There are actually 3 answers to that question.
  1. Rewrite your code to keep a usocket object instead of the stream object returned by trivial-sockets.
  2. The quick conversion with the good performance characteristics (use only when you don't want to use the socket object):
    Replace all your invocations of 
      (trivial-sockets:open-socket-stream ....)

with
  (usocket:socket-stream (usocket:socket-connect ...))
    And replace all invocations of 
      (trivial-sockets:socket-accept ...)

with
  (usocket:socket-stream (usocket:socket-accept ...))
    And replace all invocations of 
      (trivial-sockets:open-server ...)

with
  (usocket:socket-listen ...)
  3. And the last option which provides a compatible (but slower, because it uses Gray streams) interface is to use trivial-usocket.
    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.
Back to Common-lisp.net.
Valid XHTML 1.0 Strict