[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net> |
---|
| 3 | '\" |
---|
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 6 | '\" |
---|
| 7 | '\" RCS: @(#) $Id: refchan.n,v 1.11 2008/03/26 09:59:22 dkf Exp $ |
---|
| 8 | .so man.macros |
---|
| 9 | .TH refchan n 8.5 Tcl "Tcl Built-In Commands" |
---|
| 10 | .BS |
---|
| 11 | .\" Note: do not modify the .SH NAME line immediately below! |
---|
| 12 | .SH NAME |
---|
| 13 | refchan \- Command handler API of reflected channels, version 1 |
---|
| 14 | .SH SYNOPSIS |
---|
| 15 | \fBcmdPrefix \fIoption\fR ?\fIarg arg ...\fR? |
---|
| 16 | .BE |
---|
| 17 | .SH DESCRIPTION |
---|
| 18 | .PP |
---|
| 19 | The Tcl-level handler for a reflected channel has to be a command with |
---|
| 20 | subcommands (termed an \fIensemble\fR, as it is a command such as that |
---|
| 21 | created by \fBnamespace ensemble create\fR, though the implementation |
---|
| 22 | of handlers for reflected channel \fIis not\fR tied to \fBnamespace |
---|
| 23 | ensemble\fRs in any way). Note that \fIcmdPrefix\fR is whatever was |
---|
| 24 | specified in the call to \fBchan create\fR, and may consist of |
---|
| 25 | multiple arguments; this will be expanded to multiple words in place |
---|
| 26 | of the prefix. |
---|
| 27 | .PP |
---|
| 28 | Of all the possible subcommands, the handler \fImust\fR support |
---|
| 29 | \fBinitialize\fR, \fBfinalize\fR, and \fBwatch\fR. Support for the |
---|
| 30 | other subcommands is optional. |
---|
| 31 | .SS "MANDATORY SUBCOMMANDS" |
---|
| 32 | .TP |
---|
| 33 | \fIcmdPrefix \fBinitialize \fIchannelId mode\fR |
---|
| 34 | . |
---|
| 35 | An invocation of this subcommand will be the first call the |
---|
| 36 | \fIcmdPrefix\fR will receive for the specified new \fIchannelId\fR. It |
---|
| 37 | is the responsibility of this subcommand to set up any internal data |
---|
| 38 | structures required to keep track of the channel and its state. |
---|
| 39 | .RS |
---|
| 40 | .PP |
---|
| 41 | The return value of the method has to be a list containing the names |
---|
| 42 | of all subcommands supported by the \fIcmdPrefix\fR. This also tells |
---|
| 43 | the Tcl core which version of the API for reflected channels is used by |
---|
| 44 | this command handler. |
---|
| 45 | .PP |
---|
| 46 | Any error thrown by the method will abort the creation of the channel |
---|
| 47 | and no channel will be created. The thrown error will appear as error |
---|
| 48 | thrown by \fBchan create\fR. Any exception other than an \fBerror\fR |
---|
| 49 | (e.g. \fBbreak\fR, etc.) is treated as (and converted to) an error. |
---|
| 50 | .PP |
---|
| 51 | \fBNote:\fR If the creation of the channel was aborted due to failures |
---|
| 52 | here, then the \fBfinalize\fR subcommand will not be called. |
---|
| 53 | .PP |
---|
| 54 | The \fImode\fR argument tells the handler whether the channel was |
---|
| 55 | opened for reading, writing, or both. It is a list containing any of |
---|
| 56 | the strings \fBread\fR or \fBwrite\fR. The list will always |
---|
| 57 | contain at least one element. |
---|
| 58 | .PP |
---|
| 59 | The subcommand must throw an error if the chosen mode is not |
---|
| 60 | supported by the \fIcmdPrefix\fR. |
---|
| 61 | .RE |
---|
| 62 | .TP |
---|
| 63 | \fIcmdPrefix \fBfinalize \fIchannelId\fR |
---|
| 64 | . |
---|
| 65 | An invocation of this subcommand will be the last call the |
---|
| 66 | \fIcmdPrefix\fR will receive for the specified \fIchannelId\fR. It will |
---|
| 67 | be generated just before the destruction of the data structures of the |
---|
| 68 | channel held by the Tcl core. The command handler \fImust not\fR |
---|
| 69 | access the \fIchannelId\fR anymore in no way. Upon this subcommand being |
---|
| 70 | called, any internal resources allocated to this channel must be |
---|
| 71 | cleaned up. |
---|
| 72 | .RS |
---|
| 73 | .PP |
---|
| 74 | The return value of this subcommand is ignored. |
---|
| 75 | .PP |
---|
| 76 | If the subcommand throws an error the command which caused its |
---|
| 77 | invocation (usually \fBclose\fR) will appear to have thrown this |
---|
| 78 | error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is |
---|
| 79 | treated as (and converted to) an error. |
---|
| 80 | .PP |
---|
| 81 | This subcommand is not invoked if the creation of the channel was |
---|
| 82 | aborted during \fBinitialize\fR (See above). |
---|
| 83 | .RE |
---|
| 84 | .TP |
---|
| 85 | \fIcmdPrefix \fBwatch \fIchannelId eventspec\fR |
---|
| 86 | . |
---|
| 87 | This subcommand notifies the \fIcmdPrefix\fR that the specified |
---|
| 88 | \fIchannelId\fR is interested in the events listed in the |
---|
| 89 | \fIeventspec\fR. This argument is a list containing any of \fBread\fR |
---|
| 90 | and \fBwrite\fR. The list may be empty, which signals that the |
---|
| 91 | channel does not wish to be notified of any events. In that situation, |
---|
| 92 | the handler should disable event generation completely. |
---|
| 93 | .RS |
---|
| 94 | .PP |
---|
| 95 | \fBWarning:\fR Any return value of the subcommand is ignored. This |
---|
| 96 | includes all errors thrown by the subcommand, break, continue, and |
---|
| 97 | custom return codes. |
---|
| 98 | .PP |
---|
| 99 | This subcommand interacts with \fBchan postevent\fR. Trying to post an |
---|
| 100 | event which was not listed in the last call to \fBwatch\fR will cause |
---|
| 101 | \fBchan postevent\fR to throw an error. |
---|
| 102 | .RE |
---|
| 103 | .SS "OPTIONAL SUBCOMMANDS" |
---|
| 104 | .TP |
---|
| 105 | \fIcmdPrefix \fBread \fIchannelId count\fR |
---|
| 106 | . |
---|
| 107 | This \fIoptional\fR subcommand is called when the user requests data from the |
---|
| 108 | channel \fIchannelId\fR. \fIcount\fR specifies how many \fBbytes\fR have been |
---|
| 109 | requested. If the subcommand is not supported then it is not possible to read |
---|
| 110 | from the channel handled by the command. |
---|
| 111 | .RS |
---|
| 112 | .PP |
---|
| 113 | The return value of this subcommand is taken as the requested data |
---|
| 114 | \fIbytes\fR. If the returned data contains more bytes than requested, |
---|
| 115 | an error will be signaled and later thrown by the command which |
---|
| 116 | performed the read (usually \fBgets\fR or \fBread\fR). However, |
---|
| 117 | returning fewer bytes than requested is acceptable. |
---|
| 118 | .PP |
---|
| 119 | If the subcommand throws an error, the command which caused its |
---|
| 120 | invocation (usually \fBgets\fR, or \fBread\fR) will appear to have |
---|
| 121 | thrown this error. Any exception beyond \fIerror\fR, (e.g. |
---|
| 122 | \fIbreak\fR, etc.) is treated as and converted to an error. |
---|
| 123 | .RE |
---|
| 124 | .TP |
---|
| 125 | \fIcmdPrefix \fBwrite \fIchannelId data\fR |
---|
| 126 | . |
---|
| 127 | This \fIoptional\fR subcommand is called when the user writes data to |
---|
| 128 | the channel \fIchannelId\fR. The \fIdata\fR argument contains \fIbytes\fR, not |
---|
| 129 | characters. Any type of transformation (EOL, encoding) configured for |
---|
| 130 | the channel has already been applied at this point. If this subcommand |
---|
| 131 | is not supported then it is not possible to write to the channel |
---|
| 132 | handled by the command. |
---|
| 133 | .RS |
---|
| 134 | .PP |
---|
| 135 | The return value of the subcommand is taken as the number of bytes |
---|
| 136 | written by the channel. Anything non-numeric will cause an error to be |
---|
| 137 | signaled and later thrown by the command which performed the write. A |
---|
| 138 | negative value implies that the write failed. Returning a value |
---|
| 139 | greater than the number of bytes given to the handler, or zero, is |
---|
| 140 | forbidden and will cause the Tcl core to throw an error. |
---|
| 141 | .PP |
---|
| 142 | If the subcommand throws an error the command which caused its |
---|
| 143 | invocation (usually \fBputs\fR) will appear to have thrown this error. |
---|
| 144 | Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated |
---|
| 145 | as and converted to an error. |
---|
| 146 | .RE |
---|
| 147 | .TP |
---|
| 148 | \fIcmdPrefix \fBseek \fIchannelId offset base\fR |
---|
| 149 | . |
---|
| 150 | This \fIoptional\fR subcommand is responsible for the handling of |
---|
| 151 | \fBseek\fR and \fBtell\fR requests on the channel \fIchannelId\fR. If it is not |
---|
| 152 | supported then seeking will not be possible for the channel. |
---|
| 153 | .RS |
---|
| 154 | .PP |
---|
| 155 | The \fIbase\fR argument is one of |
---|
| 156 | .TP 10 |
---|
| 157 | \fBstart\fR |
---|
| 158 | . |
---|
| 159 | Seeking is relative to the beginning of the channel. |
---|
| 160 | .TP 10 |
---|
| 161 | \fBcurrent\fR |
---|
| 162 | . |
---|
| 163 | Seeking is relative to the current seek position. |
---|
| 164 | .TP 10 |
---|
| 165 | \fBend\fR |
---|
| 166 | . |
---|
| 167 | Seeking is relative to the end of the channel. |
---|
| 168 | .PP |
---|
| 169 | The \fIbase\fR argument of the builtin \fBchan seek\fR command takes |
---|
| 170 | the same names. |
---|
| 171 | .PP |
---|
| 172 | The \fIoffset\fR is an integer number specifying the amount of |
---|
| 173 | \fBbytes\fR to seek forward or backward. A positive number should seek |
---|
| 174 | forward, and a negative number should seek backward. |
---|
| 175 | .PP |
---|
| 176 | A channel may provide only limited seeking. For example sockets can |
---|
| 177 | seek forward, but not backward. |
---|
| 178 | .PP |
---|
| 179 | The return value of the subcommand is taken as the (new) location of |
---|
| 180 | the channel, counted from the start. This has to be an integer number |
---|
| 181 | greater than or equal to zero. |
---|
| 182 | .PP |
---|
| 183 | If the subcommand throws an error the command which caused its |
---|
| 184 | invocation (usually \fBseek\fR, or \fBtell\fR) will appear to have |
---|
| 185 | thrown this error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, |
---|
| 186 | etc.) is treated as and converted to an error. |
---|
| 187 | .PP |
---|
| 188 | The offset/base combination of 0/\fBcurrent\fR signals a \fBtell\fR |
---|
| 189 | request, i.e. seek nothing relative to the current location, making |
---|
| 190 | the new location identical to the current one, which is then returned. |
---|
| 191 | .RE |
---|
| 192 | .TP |
---|
| 193 | \fIcmdPrefix \fBconfigure \fIchannelId option value\fR |
---|
| 194 | . |
---|
| 195 | This \fIoptional\fR subcommand is for setting the type-specific options of |
---|
| 196 | channel \fIchannelId\fR. The \fIoption\fR argument indicates the option to be |
---|
| 197 | written, and the \fIvalue\fR argument indicates the value to set the option to. |
---|
| 198 | .RS |
---|
| 199 | .PP |
---|
| 200 | This subcommand will never try to update more than one option at a |
---|
| 201 | time; that is behavior implemented in the Tcl channel core. |
---|
| 202 | .PP |
---|
| 203 | The return value of the subcommand is ignored. |
---|
| 204 | .PP |
---|
| 205 | If the subcommand throws an error the command which performed the |
---|
| 206 | (re)configuration or query (usually \fBfconfigure\fR or \fBchan |
---|
| 207 | configure\fR) will appear to have thrown this error. Any exception |
---|
| 208 | beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is treated as and |
---|
| 209 | converted to an error. |
---|
| 210 | .RE |
---|
| 211 | .TP |
---|
| 212 | \fIcmdPrefix \fBcget \fIchannelId option\fR |
---|
| 213 | . |
---|
| 214 | This \fIoptional\fR subcommand is used when reading a single type-specific |
---|
| 215 | option of channel \fIchannelId\fR. If this subcommand is supported then the |
---|
| 216 | subcommand \fBcgetall\fR must be supported as well. |
---|
| 217 | .RS |
---|
| 218 | .PP |
---|
| 219 | The subcommand should return the value of the specified \fIoption\fR. |
---|
| 220 | .PP |
---|
| 221 | If the subcommand throws an error, the command which performed the |
---|
| 222 | (re)configuration or query (usually \fBfconfigure\fR) will appear to |
---|
| 223 | have thrown this error. Any exception beyond \fIerror\fR (e.g. |
---|
| 224 | \fIbreak\fR, etc.) is treated as and converted to an error. |
---|
| 225 | .RE |
---|
| 226 | .TP |
---|
| 227 | \fIcmdPrefix \fBcgetall \fIchannelId\fR |
---|
| 228 | . |
---|
| 229 | This \fIoptional\fR subcommand is used for reading all type-specific options |
---|
| 230 | of channel \fIchannelId\fR. If this subcommand is supported then the |
---|
| 231 | subcommand \fBcget\fR has to be supported as well. |
---|
| 232 | .RS |
---|
| 233 | .PP |
---|
| 234 | The subcommand should return a list of all options and their values. |
---|
| 235 | This list must have an even number of elements. |
---|
| 236 | .PP |
---|
| 237 | If the subcommand throws an error the command which performed the |
---|
| 238 | (re)configuration or query (usually \fBfconfigure\fR) will appear to |
---|
| 239 | have thrown this error. Any exception beyond \fIerror\fR (e.g. |
---|
| 240 | \fIbreak\fR, etc.) is treated as and converted to an error. |
---|
| 241 | .RE |
---|
| 242 | .TP |
---|
| 243 | \fIcmdPrefix \fBblocking \fIchannelId mode\fR |
---|
| 244 | . |
---|
| 245 | This \fIoptional\fR subcommand handles changes to the blocking mode of the |
---|
| 246 | channel \fIchannelId\fR. The \fImode\fR is a boolean flag. A true value means |
---|
| 247 | that the channel has to be set to blocking, and a false value means that the |
---|
| 248 | channel should be non-blocking. |
---|
| 249 | .RS |
---|
| 250 | .PP |
---|
| 251 | The return value of the subcommand is ignored. |
---|
| 252 | .PP |
---|
| 253 | If the subcommand throws an error the command which caused its |
---|
| 254 | invocation (usually \fBfconfigure\fR) will appear to have thrown this |
---|
| 255 | error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR, etc.) is |
---|
| 256 | treated as and converted to an error. |
---|
| 257 | .RE |
---|
| 258 | .SH NOTES |
---|
| 259 | Some of the functions supported in channels defined in Tcl's C |
---|
| 260 | interface are not available to channels reflected to the Tcl level. |
---|
| 261 | .PP |
---|
| 262 | The function \fBTcl_DriverGetHandleProc\fR is not supported; i.e. |
---|
| 263 | reflected channels do not have OS specific handles. |
---|
| 264 | .PP |
---|
| 265 | The function \fBTcl_DriverHandlerProc\fR is not supported. This driver |
---|
| 266 | function is relevant only for stacked channels, i.e. transformations. |
---|
| 267 | Reflected channels are always base channels, not transformations. |
---|
| 268 | .PP |
---|
| 269 | The function \fBTcl_DriverFlushProc\fR is not supported. This is |
---|
| 270 | because the current generic I/O layer of Tcl does not use this |
---|
| 271 | function anywhere at all. Therefore support at the Tcl level makes no |
---|
| 272 | sense either. This may be altered in the future (through extending the |
---|
| 273 | API defined here and changing its version number) should the function |
---|
| 274 | be used at some time in the future. |
---|
| 275 | .SH "SEE ALSO" |
---|
| 276 | chan(n) |
---|
| 277 | .SH KEYWORDS |
---|
| 278 | channel, reflection |
---|