Before a client can connect to a server, it must know the network address on which the server accepts connections. Network addresses consist of a host address or name, and a port number. Host addresses are either a string of the form VANCOUVER.SLISP.CS.CMU.EDU or a 32 bit unsigned integer. Port numbers are 16 bit unsigned integers. Note: port in this context has nothing to do with Mach ports and message passing.
When a process wants to receive connection requests (that is, become a server), it first picks an integer to use as the port. Only one server (Lisp or otherwise) can use a given port number on a given machine at any particular time. This can be an iterative process to find a free port: picking an integer and calling create-request-server. This function signals an error if the chosen port is unusable. You will probably want to write a loop using handler-case, catching conditions of type error, since this function does not signal more specific conditions.
[Function]
wire: create-request-server port &optional on-connect
create-request-server sets up the current Lisp to accept connections on the given port. If port is unavailable for any reason, this signals an error. When a client connects to this port, the acceptance mechanism makes a wire structure and invokes the on-connect function. Invoking this function has a couple purposes, and on-connect may be nil in which case the system foregoes invoking any function at connect time.
The on-connect function is both a hook that allows you access to the wire created by the acceptance mechanism, and it confirms the connection. This function takes two arguments, the wire and the host address of the connecting process. See the section on host addresses below. When on-connect is nil, the request server allows all connections. When it is non-nil, the function returns two values, whether to accept the connection and a function the system should call when the connection terminates. Either value may be nil, but when the first value is nil, the acceptance mechanism destroys the wire.
create-request-server returns an object that destroy-request-server uses to terminate a connection.
[Function]
wire: destroy-request-server server
destroy-request-server takes the result of create-request-server and terminates that server. Any existing connections remain intact, but all additional connection attempts will fail.
[Function]
wire: connect-to-remote-server host port &optional on-death
connect-to-remote-server attempts to connect to a remote server at the given port on host and returns a wire structure if it is successful. If on-death is non-nil, it is a function the system invokes when this connection terminates.