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 write-timeout timeout local-address local-port => 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 .

write-timeout

A positive number, or nil .

timeout

A positive number, or nil .

local-address

nil , an integer or a string.

local-port

nil , a string or a fixnum.

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 at most timeout seconds for the TCP connection to be made. If timeout is nil it waits until the connection attempt succeeds or fails. 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 . The default value of timeout is nil .

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 .

write-timeout is similar to read-timeout , but for writes. See socket-stream for more details.

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 .

If local-address is nil then the operating system chooses the local address of the socket. Otherwise the string or integer value is interpreted as for hostname and specifies the local address of the socket. The default value of local-address is nil .

If local-port is nil then the operating system chooses the local port of the socket. Otherwise the string or fixnum value is interpreted as for service and specifies the local port of the socket. The default value of local-port is nil .

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