Next: Time Up: System Utilities Previous: Directories

# 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.

Next: Time Up: System Utilities Previous: Directories