Networking

MzScheme provides a minimal collection of TCP-based communication procedures.

• (tcp-listen port-k [max-allow-wait-k]) creates a ``listening'' server on the local machine at the specified port number (where port-k is an exact integer between 1 and 65535). The max-allow-wait-k argument determines the maximum number of client connections that can be waiting for acceptance. (When max-allow-wait-k clients are waiting acceptance, no new client connections can be made.) The default value for max-allow-wait-k argument is 4.

  The return value of tcp-listen is a TCP listener value. This value can be used in future calls to tcp-accept, tcp-accept-ready?, and tcp-close. Each new TCP listener value is placed into the management of the current custodian (see section 9.5).

  If the server cannot be started by tcp-listen, the exn:i/o:tcp exception is raised.

• (tcp-connect hostname-string [port-k]) attempts to connect as a client to a listening server. The hostname-string argument is the server host's internet address name (e.g., "cs.rice.edu"), and port-k (an exact integer between 1 and 65535) is the port where the server is listening.

  Two values (see Chapter 2) are returned by tcp-connect: an input port and an output port. Data can be received from the server through the input port and sent to the server through the output port. If the server is a MzScheme process, it can obtain ports to communicate to the client with tcp-accept. These ports are placed into the management of the current custodian (see section 9.5).

  If a connection cannot be established by tcp-connect, the exn:i/o:tcp exception is raised.

• (tcp-accept tcp-listener) accepts a client connection for the server associated with tcp-listener. The tcp-listener argument is a TCP listener value returned by tcp-listen. If no client connection is waiting on the listening port, the call to tcp-accept will block. (See also tcp-accept-ready?, below.)

  Two values (see Chapter 2) are returned by tcp-accept: an input port and an output port. Data can be received from the client through the input port and sent to the client through the output port. These ports are placed into the management of the current custodian (see section 9.5).

  If a connection cannot be accepted by tcp-accept, or if the listener has been closed, the exn:i/o:tcp exception is raised.

• (tcp-accept-ready? tcp-listener) tests whether an unaccepted client has connected to the server associated with tcp-listener. The tcp-listener argument is a TCP listener value returned by tcp-listen. If a client is waiting, the return value is #t, otherwise it is #f. A client is accepted with the tcp-accept procedure, which returns ports for communicating with the client and removes the client from the list of unaccepted clients.

  If the listener has been closed, the exn:i/o:tcp exception is raised.

• (tcp-close tcp-listener) shuts down the server associated with tcp-listener. The tcp-listener argument is a TCP listener value returned by tcp-listen. All unaccepted clients receive an end-of-file from the server; connections to accepted clients are unaffected.

  If the listener has already been closed, the exn:i/o:tcp exception is raised.

• (tcp-listener? v) returns #t if v is a TCP listener value created by tcp-listen, #f otherwise.
• (tcp-addresses tcp-port) returns two strings. The first string is the internet address for the local machine a viewed by the given TCP port's connection. The second string is the internet address for the other end of the connection.

  If the given port has been closed, the exn:i/o:tcp exception is raised.