Function

Summary

Attempts to connect to a socket on another machine and returns a stream object for the connection.

Package

comm

Signature

open-tcp-stream hostname service &key direction element-type errorp read-timeout timeout => stream-object

Arguments

hostname

An integer or string.

service

A string or a fixnum.

direction

One of :input , :output or :io .

element-type

base-char or a subtype of integer .

errorp

A boolean.

read-timeout

A positive number, or nil .

timeout

A positive number, or nil .

Values

stream-object

A socket stream.

Description

The open-tcp-stream function attempts to connect to a socket on another machine and returns stream-object for the connection if successful. The server machine to connect to is given by hostname , which can be one of the following:

• A string naming the host, for example "www.nowhere.com"
• A string providing the IP address, for example "204.71.177.75"
• An integer IP address in network order, for example #xCC47B14B

The name of the service to provide is given by service . If service is a string, the location of the file specifying the names of the services available varies, but typically on Windows 95 it is called SERVICES and is stored in the Windows directory., and on Windows NT it is the file

%SystemRoot%\system32\drivers\etc\SERVICES

The service can also be a fixnum representing the port number of the desired connection.

The direction of the connection is given by direction . Its default value is :io . The element type of the connection is determined from element-type , and is base-char by default.

If errorp is nil , failure to connect (possibly after timeout seconds) returns nil , otherwise an error is signaled.

timeout specifies a connection timeout. open-tcp-stream waits for timeout seconds for the TCP connection to be made. If timeout is nil (the default) it does not wait. On failure, open-tcp-stream signals an error or returns nil according to the value of errorp . To provide a timeout for reads after the connection is made, see read-timeout .

read-timeout specifies the read timeout of the stream. If it is nil (the default), the stream does not time out during reads, and these may hang. See socket-stream for more details. To provide a connection timeout, see timeout .

Unlike the other ways of creating a socket stream with SSL processing, open-tcp-stream does not take the ssl-side argument and always uses the value :client .

Example

The following example opens an HTTP connection to a given host, and retrieves the root page:

(with-open-stream (http (comm:open-tcp-stream 

                         "www.lispworks.com" 80))

  (format http "GET / HTTP/1.0~C~C~C~C"

               (code-char 13) (code-char 10)

               (code-char 13) (code-char 10))

  (force-output http)

  (write-string "Waiting to reply...")

  (loop for ch = (read-char-no-hang http nil :eof)

        until ch

        do (write-char #\.)

           (sleep 0.25)

        finally (unless (eq ch :eof)

                  (unread-char ch http))) 

  (terpri)

  (loop for line = (read-line http nil nil)

        while line

        do (write-line line)))

See also

start-up-server
socket-stream