$Id: api-docs.shtml 558 2010-09-15 03:35:27Z ctian $
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.
Creates a TCP (stream) or UDP (datagram) socket to the host and port specified. The return value is a socket object of class stream-usocket, or datagram-usocket.
protocol should be
:stream (default) or
UDP (Start from USOCKET 0.5)
element-type argument is used in the construction of the associated stream, i.e.
'(unsigned-byte 8), only used by TCP.
timeout is a integer, it represents the socket option
(read timeout), in seconds.
deadline is only supported in Clozure CL and Digitool MCL, look up their documents please.
local-host and local-port, 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).
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.
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.
Flushes the stream associated with the socket and closes the socket connection.
Returns the local address and/or port information of socket.
Returns the remote address and/or port information of socket. The socket passed to this function must be a connected socket.
Send a (unsigned-byte 8) data buffer to a datagram socket, and return the number of bytes sent. (Start from USOCKET 0.5)
socket should be a datagram-usocket.
buffer is a Lisp vector, type of
(unsigned-byte 8) *).
length is used to tell socket-send the actual useful length of data buffer for sending to socket.
host and port are used for unconnected datagram sockets, for sending to specific destination.
Receive data from a datagram socket, and return 4 values: return-buffer, return-length, remote-host, and remove-port. If the datagram socket was created by socket-connect with a timeout keyword argument, this function will block at most that timeout value (in seconds). (Start from USOCKET 0.5)
socket should be a datagram-usocket.
buffer is a Lisp vector, type of
(unsigned-byte 8) *). Using
nil here is also
allowed, new buffer will be created to hold data.
length is used to specify the length of a exist buffer for receiving at most these data. Using nil here is allowed, and the actual length of buffer will be used; when buffer is also
nil, a default maximum length (65507) will be
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
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.
Without the ready-only 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.
Without the ready-only arg, you need to check the socket STATE slot for the values documented in usocket class.
Create a simple TCP or UDP socket server. (Start from USOCKET
host names a local interface,
port names a local port,
function names a function object, which is used to handle TCP or UDP connections, the actual API of this function will be explained later.
arguments is a list used for passing extra arguments to user-defined function.
in-new-thread is a boolean, default is
T, the server will be created in a new thread
and socket-server returns immediately in current thread.
protocol could be either
:datagram, which decide the socket server is TCP
server or UDP server.
timeout is UDP only, it provides the internal socket-receive call (in UDP event loop of the socket server) a read timeout, default value is 1 (second).
max-buffer-size is UDP only, it's the max UDP data buffer size when handling UDP packets, default value is 65507.
element-type is TCP only, it's element-type of the stream provided for user-defined function,
reuse-address is TCP only, it's a boolean option for internal call of socket-listen in the socket server,
multi-threading is TCP only, it's a boolean, default value is
nil. When it's
T, 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)
The handler function for TCP is stream-based. A template function is this one:
(defun default-tcp-handler (stream) ; null
(declare (type stream stream))
Note: 1. you don't need to close the stream as socket-server will do that for you. 2. More function arguments can be defined, and these extra arguments must be feeded as the optional arguments of socket-server.
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:
(defun default-udp-handler (buffer) ; echo
(declare (type (simple-array (unsigned-byte 8) *) buffer))
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 *remote-host* and *remote-port* when handler function is running.
Used to store sockets as used by the current implementation - may be any of socket handles, socket objects and stream objects
Used to store socket state: NIL (not ready), :READ (ready to
Used to store the stream associated with the tcp socket
When you want to write to the socket stream, use this function.
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.
Used to identify if the datagram is connected. It will be setup by socket-connect, and used by socket-send and socket-receive.
The host to use with socket-listen to make the socket listen on all available interfaces.
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.
Special variable used in socket-server's
address. (Start from
Special variable used in socket-server's handler function for getting current client port. (Start from USOCKET 0.5)
(format (socket-stream socket) "Hello there~%") ;; output into buffers
(force-output (socket-stream socket)) ;; <== flush the buffers, if any
(listen (usocket:socket-stream your-socket))
==> NIL (if no input is available)
(usocket:wait-for-input (list socket1 socket2 socket3) :timeout <your optional timeout value>)
(trivial-sockets:open-socket-stream ....)And replace all invocations of
(usocket:socket-stream (usocket:socket-connect ...))
(trivial-sockets:socket-accept ...)And replace all invocations of
(usocket:socket-stream (usocket:socket-accept ...))