create-async-io-state-and-connected-tcp-socket 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 hostspec service callback &key read-timeout write-timeout user-info connect-timeout local-address local-port keepalive nodelay name queue-output ssl-ctx ctx-configure-callback ssl-configure-callback handshake-timeout tlsext-host-name => async-io-state

Arguments

Values

Description

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

async-io-state is associated with collection. When you have finished with async-io-state, you should close it by calling close-async-io-state.

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. New operations on async-io-state must not be started before callback has been called.

If no connection can be made, callback is called with async-io-state, which is already closed, 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.

Note: callback is called on the process of collection and therefore should not do any significant amout of work. If it does need to do work, it should do it on another process.

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

If tlsext-host-name is a string, then the SNI extension in the SSL connection to set to its value. If tlsext-host-name is t and hostspec is a string that does not specify a numeric IP address, then the SNI extension in the SSL connection to set to hostspec. If tlsext-host-name is not supplied and ssl-ctx is non-nil, then the SNI extension is set to hostspec if it is a string that does not specify a numeric IP address and ssl-ctx is not an ssl-abstract-context that was created with a tlsext-host-name.

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
create-ssl-client-context
close-async-io-state
25.7.2 The Async-I/O-State API
25 TCP and UDP socket communication and SSL