package require TclServer
set server [TclServer %AUTO% ?options?]
$server methodname ?params?
TclServer provides a pure Tcl Tcl server that
can be embedded into a script. A script using
TclServer must be based on the Tcl event
loop as that is used to dispatch connection and input events.
In insecure environments you should probably embed the
TclServer in a secure slave interpreter.
Users can implement authentication protocols via the
-onconnect script. Error handling can also be
customized via the -onerror script.
The sever can be in two states. In the inactive
state the server is not listening for new connections. Prior connections
could still be executing. In the active state,
the server is listening for connections on the port configured
via the -port option.
Several options control the way the server works:
-port port-num
Determines which TCP/IP port the server will listen on
for client connections. This can only be configured when
the server is in the inactive state.
See the start and
stop methods in the METHODS
section below for more information.
-onconnect scriptSpecifies a script to be called when a connection request is received. The script must take three parameters which are in order;
The socket fd on which data are transferred
The IP address of the client
The port assigned the client
If the script returns false, the connection will be immediately
closed by the server. If true, the server will set up
to handle commands from the client. This option therefore
allows users of the TclServer object
to implement authentication protocols.
-onerror scriptSpecifies a script that will be called whenever a remotely requested script has thrown an error. The script is called with three parameters that are in order:
The channel on which the script was received.
The command that caused the error.
The error message produced by the command.
If the script returns false the client connection is closed by the server. If the script returns true the client connection remains open.
The following methods control the server.
start
Starts the server. This puts the server into the
active mode. Configuring the
-port option when active
results in an error. If the server is already
active an error is also thrown.
If the -port configuration option is
not a legal positive integer an error will be thrown.
If a privileged port is chosen but the application does
not have privilege the socket -server
command will throw an error.
stop
Stops the server. This puts the server into the
inactive state. Note that
this only stops listening for new connections.
Existing connections are retained unless or until
the close method is invoked.
It is an error to stop the
server when it is inactive.
close
Closes all active client connections. This can be
performed in any server state. It is not an error
to close if there are no
active connections.