$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 :datagram,
which
means
TCP
or
UDP (Start from USOCKET 0.5)
element-type argument is used in the
construction of the associated stream, i.e. 'character or
'(unsigned-byte 8), only used by TCP.
timeout is a integer, it represents the socket option SO_RCVTIMEO
(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 (simple-array
(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 (simple-array
(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
used.
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.
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
0.5)
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 nil.
When it's T, the server will be created in a new thread
and socket-server returns immediately in current thread.
protocol could be either :stream (default)
or :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))
(terpri 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))
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
read).
Used to store the stream associated with the tcp socket
connection.
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
handler
function
for
getting
current
client
address. (Start from
USOCKET 0.5)
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>)
==> list-of-sockets-to-read-from
(trivial-sockets:open-socket-stream ....)And replace all invocations of
with
(usocket:socket-stream (usocket:socket-connect ...))
(trivial-sockets:socket-accept ...)And replace all invocations of
with
(usocket:socket-stream (usocket:socket-accept ...))
(trivial-sockets:open-server ...)
with
(usocket:socket-listen ...)