Function

Summary

Creates an async-io-state which attempts to make a TCP connection.

Package

comm

Signature

create-async-io-state-and-connected-tcp-socket collection host service callback &key read-timeout write-timeout user-info connect-timeout local-address local-port keepalive nodelay name queue-output => async-io-state ssl-ctx ctx-configure-callback ssl-configure-callback handshake-timeout

Arguments

collection

A wait-state-collection.

host

An integer or a string or an ipv6-address object.

service

A string or a fixnum.

callback

A function designator for a function of two arguments.

read-timeout

nil or a positive real.

write-timeout

nil or a positive real.

user-info

A Lisp object.

connect-timeout

nil or a positive real.

local-address

nil, an integer, a string or an ipv6-address object.

local-port

nil, a string or a fixnum.

keepalive

A generalized boolean.

nodelay

A generalized boolean.

queue-output

A boolean.

name

A Lisp object.

ssl-ctx

A symbol or a foreign pointer.

ctx-configure-callback

A function designator or nil. The default value is nil.

ssl-configure-callback

A function designator or nil. The default value is nil.

handshake-timeout

A real or nil (the default).

Values

async-io-state

An async-io-state.

Description

The function create-async-io-state-and-connected-tcp-socket creates an async-io-state which attempts to make a TCP connection to host on port service within connect-timeout seconds. host and service are interpreted as described in Specifying the target for connecting and binding a socket.

When the connection has been made, callback is called with arguments async-io-state and nil. Normally callback will start asynchronous I/O by calling async-io-state-read-buffer, async-io-state-write-buffer or async-io-state-read-with-checking.

If no connection can be made, callback is called with async-io-state and a list of a format control-string and args, suitable for applying to format. In general, it doesn't make much sense for the callback to call error within callback, so it should report the problem in some way, typiclaly by writing to some log. It may also needs to inform the user interactively, but that needs be done in another process, and is better done by using some kind of a end-user dialog rather than invoking error.

local-address and local-port are used to bind the local side of the socket to a particular address and/or port if non-nil.

keepalive and nodelay set the SO_KEEPALIVE and TCP_NODELAY in the socket. The default value of keepalive is nil. The default value of nodelay is t.

queue-output controls what happens if you try to perform a write operation on the state while another write operation is ongoing. When nil, this will cause an error. When non-nil, the second write operation is queued and actually executed later. The default value of queue-output is nil.

read-timeout, write-timeout, user-info and name are set in async-io-state using the corresponding accessors async-io-state-read-timeout, async-io-state-write-timeout, async-io-state-user-info and async-io-state-name.

The default value of name is a string "Connected TCP".

ssl-ctx, ctx-configure-callback, ssl-configure-callback and handshake-timeout are interpreted as described in Keyword arguments for use with SSL. Unlike the other ways of creating a socket stream with SSL processing, create-async-io-state-and-connected-tcp-socket does not take the ssl-side argument and always uses the value :client.

Once the connection has been made,, you can get the socket by calling async-io-state-object on async-io-state (see async-io-state)

See also

create-async-io-state
accept-tcp-connections-creating-async-io-states
The Async-I/O-State API