ns_connchan - Manage connection channels.
The command ns_connchan allows one to detach the current channel from a connection thread and manage the connection outside the initiating connection thread. It allows one to write or read to the channel, to define callbacks and to list open connections and to close the connection. The read and write operations on this channel will use directly the driver infrastructure which was in use during the detach command.
The command allows e.g. to read from and to write to all network drivers (such as plain HTTP channels and from SSL/TLS connections). It can be used to implement e.g. WebSockets or asynchronous deliveries (e.g. h264 streams) including secure connections. Therefore, this command is more general than the approaches based on ns_conn channel using plain Tcl channels.
NaviServer maintains an internal table per server to keep track of the detached connection channels and to offer introspection to the state of the detached channels.
The command ns_connchan detach unplugs the connection channel from the current connection thread and stores it with a fresh handle name in a per-virtual-server private table. The command returns the created handle as result.
After this command was issued in a connection thread all attempts to access the connection socket directly (e.g. via ns_write) will fail.
Close the named connection channel.
Returns 1 if the named connection channel exists, 0 otherwise.
Return a list of the currently detached connection channels for the current or named server.
Every list entry contains
name of the channel
name of the thread
start time of the initiating request,
driver,
the ip-address of the requestor,
sent bytes,
received bytes,
the client data as provided via [ns_conn clientdata],
the cmd name of the callback, or "" when no callback is registered,
the callback condition flags, or "" when no callback is registered.
Register a Tcl callback for the names connection channel. -timeout is the poll timeout, -receivetimeout is a timeout for incoming packets, -sendtimeout is the timeout for outgoing packets. When -sendtimeout has the value of 0, a read operation might return the empty string. A value larger than 0 might block the event processing for the specified time.
The argument when consist of one or more characters of r, w, e, or x, specifying, when the callback should fire. All timeouts are specified in the form secs?:microsecs? or secs.fraction.
When the callback is fired, the specified Tcl command will be called with an additional argument, which is an indicator for the reason of the call when. The value of when will be as follows:
r - the socket is readable
w - the socket is writable
e - the socket has an exceptional condition
x - the server is shutting down
t - timeout received
When the callback exits, its return value determines, whether the callback should be canceled or not. The return value is interpreted as follows:
0 - the callback is canceled, and the channel is deleted automatically (typically, when an error occurs)
1 - the callback will be used as well for further events
2 - the callback will be suspended. No further events will be fired, but the channel is not deleted.
Open listening socket. Call the script callback on incoming connections. On success, this command returns a dict containing "channel", "port", "sock" and "address".
Open a connection channel to the specified url. The URL might be an HTTP or an HTTPS URL. -headers refers to a ns_set of request header fields, -method is the HTTP method (default GET), -timeout is the timeout for establishing the connection (default 1 second), and -version specifies the HTTP version (default 1.0)
Read from the specified connection channel.
Write to the specified connection channel. The function returns the number of bytes sent, which might be less than the input length.