'\" 
'\" Copyright (c) 2006 Andreas Kupries
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: chan.n,v 1.2 2005/06/10 15:22:43 dkf Exp $
.so man.macros
.TH reflectedchan n 8.5 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
reflectedchan \- Command handler API of reflected channels, version 1
.SH SYNOPSIS
\fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
The Tcl-level handler for a reflected channel has to be a command with
subcommands (termed an \fIensemble\fR, as it is a command such as that
created by \fBnamespace ensemble create\fR, though the implementation
of handlers for reflected channel \fIis not\fR tied to \fBnamespace
ensemble\fRs in any way). Note that \fIcmdPrefix\fR is whatever was
specified in the call to \fBchan create\fR, and may consist of
multiple arguments; this will be expanded to multiple words in place
of the prefix.
.PP
Of all the possible subcommands, the handler \fImust\fR support
\fBinitialize\fR, \fBfinalize\fR, and \fBwatch\fR. Support for the
other subcommands is optional.
.SS "MANDATORY SUBCOMMANDS"
.TP
\fIcmdPrefix \fBinitialize \fIchannel mode\fR
.
An invokation of this subcommand will be the first call the
\fIcmdPrefix\fR will receive for the specified new \fBchannel\fR. It
is the responsibility of this subcommand to set up any internal data
structures required to keep track of the channel and its state.
.RS
.PP
The return value of the method has to be a list containing the names
of all subcommands supported by the \fIcmdPrefix\fR. This also tells
the Tcl core which version of the API for reflected channels is used by
this command handler.
.PP
Any error thrown by the method will abort the creation of the channel
and no channel will be created. The thrown error will appear as error
thrown by \fBchan create\fR. Any exception other than an \fBerror\fR
(e.g. \fBbreak\fR, etc.) is treated as (and converted to) an error.
.PP
\fBNote:\fR If the creation of the channel was aborted due to failures
here, then the \fBfinalize\fR subcommand will not be called.
.PP
The \fImode\fR argument tells the handler whether the channel was
opened for reading, writing, or both. It is a list containing any of
the strings "\fBread\fR" or "\fBwrite\fR". The list will always
contain at least one element.
.PP
The subcommand must throw an error if the chosen mode is not
supported by the \fIcmdPrefix\fR.
.RE
.TP
\fIcmdPrefix \fBfinalize \fIchannel\fR
.
An invokation of this subcommand will be the last call the
\fIcmdPrefix\fR will receive for the specified \fIchannel\fR. It will
be generated just before the destruction of the data structures of the
channel held by the Tcl core. The command handler \fImust not\fR
access the \fIchannel\fR anymore in no way. Upon this subcommand being
called, any internal resources allocated to this channel must be
cleaned up.
.RS
.PP
The return value of this subcommand is ignored.
.PP
If the subcommand throws an error the command which caused its
invocation (usually \fBclose\fR) will appear to have thrown this
error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is
treated as (and converted to) an error.
.PP
This subcommand is not invoked if the creation of the channel was
aborted during \fBinitialize\fR (See above).
.RE
.TP
\fIcmdPrefix \fBwatch \fIchannel eventspec\fR
.
This subcommand notifies the \fIcmdPrefix\fR that the specified
\fIchannel\fR is interested in the events listed in the
\fIeventspec\fR. This argument is a list containing any of "\fBread\fR"
and "\fBwrite\fR". The list may be empty, which signals that the
channel does not wish to be notified of any events. In that situation,
the handler should disable event generation completely.
.RS
.PP
\fBWarning:\fR Any return value of the subcommand is ignored. This
includes all errors thrown by the subcommand, break, continue, and
custom return codes.
.PP
This subcommand interacts with \fBchan postevent\fR. Trying to post an
event which was not listed in the last call to \fBwatch\fR will cause
\fBchan postenvent\fR to throw an error.
.RE
.SS "OPTIONAL SUBCOMMANDS"
.TP
\fIcmdPrefix \fBread \fIchannel count\fR
.
This \fIoptional\fR subcommand is called when the user requests data
from a channel. \fIcount\fR specifies how many \fBbytes\fR have been
requested. If the subcommand is not supported then it is not possible
to read from the channel handled by the command.
.RS
.PP
The return value of this subcommand is taken as the requested data
\fIbytes\fR. If the returned data contains more bytes than requested,
an error will be signalled and later thrown by the command which
performed the read (usually \fBgets\fR or \fBread\fR). However,
returning fewer bytes than requested is acceptable.
.PP
If the subcommand throws an error, the command which caused its
invocation (usually \fBgets\fR, or \fBread\fR) will appear to have
thrown this error. Any exception beyond \fIerror\fR, (e.g.
\fIbreak\fR, etc.) is treated as and converted to an error.
.RE
.TP
\fIcmdPrefix \fBwrite \fIchannel data\fR
.
This \fIoptional\fR subcommand is called when the user writes data to
the channel. The \fIdata\fR argument contains \fIbytes\fR, not
characters. Any type of transformation (EOL, encoding) configured for
the channel has already been applied at this point. If this subcommand
is not supported then it is not possible to write to the channel
handled by the command.
.RS
.PP
The return value of the subcommand is taken as the number of bytes
written by the channel. Anything non-numeric will cause an error to be
signaled and later thrown by the command which performed the write. A
negative value implies that the write failed. Returning a value
greater than the number of bytes given to the handler, or zero, is
forbidden and will cause the Tcl core to throw an error.
.PP
If the subcommand throws an error the command which caused its
invocation (usually \fBputs\fR) will appear to have thrown this error.
Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated
as and converted to an error.
.RE
.TP
\fIcmdPrefix \fBseek \fIchannel offset base\fR
.
This \fIoptional\fR subcommand is responsible for the handling of
\fBseek\fR and \fBtell\fR requests on the channel. If it is not
supported then seeking will not be possible for the channel.
.RS
.PP
The \fIbase\fR argument is one of
.TP 10
\fBstart\fR
.
Seeking is relative to the beginning of the channel.
.TP 10
\fBcurrent\fR
.
Seeking is relative to the current seek position.
.TP 10
\fBend\fR
.
Seeking is relative to the end of the channel.
.PP
The \fIbase\fR argument of the builtin \fBchan seek\fR command takes
the same names.
.PP
The \fIoffset\fR is an integer number specifying the amount of
\fBbytes\fR to seek forward or backward. A positive number should seek
forward, and a negative number should seek backward.
.PP
A channel may provide only limited seeking. For example sockets can
seek forward, but not backward.
.PP
The return value of the subcommand is taken as the (new) location of
the channel, counted from the start. This has to be an integer number
greater than or equal to zero.
.PP
If the subcommand throws an error the command which caused its
invocation (usually \fBseek\fR, or \fBtell\fR) will appear to have
thrown this error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR,
etc.) is treated as and converted to an error.
.PP
The offset/base combination of 0/"\fBcurrent\fR" signals a \fBtell\fR
request, i.e. seek nothing relative to the current location, making
the new location identical to the current one, which is then returned.
.RE
.TP
\fIcmdPrefix \fBconfigure \fIchannel option value\fR
.
This \fIoptional\fR subcommand is for writing the type specific
options. The \fIoption\fR argument indicates the option to be written,
and the \fIvalue\fR argument indicates the value to set the option to.
.RS
.PP
This subcommand will never try to update more than one option at a
time; that is behavior implemented in the Tcl channel core.
.PP
The return value of the subcommand is ignored.
.PP
If the subcommand throws an error the command which performed the
(re)configuration or query (usually \fBfconfigure\fR or \fBchan
configure\fR) will appear to have thrown this error. Any exception
beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated as and
converted to an error.
.RE
.TP
\fIcmdPrefix \fBcget \fIchannel option\fR
.
This \fIoptional\fR subcommand is used when reading a single type
specific option. If this subcommand is supported then the subcommand
\fBcgetall\fR must be supported as well.
.RS
.PP
The subcommand should return the value of the specified \fIoption\fR.
.PP
If the subcommand throws an error, the command which performed the
(re)configuration or query (usually \fBfconfigure\fR) will appear to
have thrown this error. Any exception beyond \fIerror\fR (e.g.
\fIbreak\fR, etc.) is treated as and converted to an error.
.RE
.TP
\fIcmdPrefix \fBcgetall \fIchannel\fR
.
This \fIoptional\fR subcommand is used for reading all type specific
options. If this subcommand is supported then the subcommand
\fBcget\fR has to be supported as well.
.RS
.PP
The subcommand should return a list of all options and their values.
This list must have an even number of elements.
.PP
If the subcommand throws an error the command which performed the
(re)configuration or query (usually \fBfconfigure\fR) will appear to
have thrown this error. Any exception beyond \fIerror\fR (e.g.
\fIbreak\fR, etc.) is treated as and converted to an error.
.RE
.TP
\fIcmdPrefix \fBblocking \fIchannel mode\fR
.
This \fIoptional\fR subcommand handles changes to the blocking mode of
the channel. The \fImode\fR is a boolean flag. A true value means that
the channel has to be set to blocking, and a false value means that
the channel should be non-blocking.
.RS
.PP
The return value of the subcommand is ignored.
.PP
If the subcommand throws an error the command which caused its
invocation (usually \fBfconfigure\fR) will appear to have thrown this
error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is
treated as and converted to an error.
.RE
.SH NOTES
Some of the functions supported in channels defined in Tcl's C
interface are not available to channels reflected to the Tcl level.
.PP
The function \fBTcl_DriverGetHandleProc\fR is not supported; i.e.
reflected channels do not have OS specific handles.
.PP
The function \fBTcl_DriverHandlerProc\fI is not supported. This driver
function is relevant only for stacked channels, i.e. transformations.
Reflected channels are always base channels, not transformations.
.PP
The function \fBTcl_DriverFlushProc\fR is not supported. This is
because the current generic I/O layer of Tcl does not use this
function anywhere at all. Therefore support at the Tcl level makes no
sense either. This may be altered in the future (through extending the
API defined here and changing its version number) should the function
be used at some time in the future.
.SH "SEE ALSO"
chan(n)
.SH KEYWORDS
channel, reflection