NaviServer - programmable web server

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

# ns_connchan(n) 4.99.8 naviserver "NaviServer Built-in Commands"

## Name

ns_connchan - Manage connection channels.

## Table Of Contents

## Synopsis

- ns_connchan detach
- ns_connchan close channel
- ns_connchan list ?-server server?
- ns_connchan callback ?-timeout s? ?-receivetimeout s? ?-sendtimeout s? channel command when
- ns_connchan read channel
- ns_connchan write channel string

## Description

The command ns_connchan allows to detach the current channel from a connection thread and manage the connection outside the initiating connection thread. It allows 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 ansynchronous deliveries (e.g. h264 streams) including secure connections. This makes it more powerful 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.

## COMMANDS

ns_connchan detach

  The command 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.

ns_connchan close channel

  Close the named connection channel.

ns_connchan list ?-server server?

  Return a list 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, and

  - the client data as provided via [ns_conn clientdata].

ns_connchan callback ?-timeout s? ?-receivetimeout s? ?-sendtimeout s? channel command when

  Register a Tcl callback for the names connection channel. 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?. When the callback is fired, the specified Tcl command will be called with two additional arguments, namely the handle and and indicator for the reson of the call when. The value of when will be as follows:

  - r - the socket is readable

  - w - the socket is writeable

  - e - the socket has an exceptional condition

  - x - the server is shutting down

  - t - timeout received

ns_connchan read channel

  Read from the specified connection channel.

ns_connchan write channel string

  Write to the specified connection channel.

## See Also

ns_chan, ns_conn, ns_sockcallback, ns_write

## Keywords

channels, driver, socket