1refchan(n) Tcl Built-In Commands refchan(n)
2______________________________________________________________________________
6
8 refchan - Command handler API of reflected channels, version 1
9
11 cmdPrefix option ?arg arg ...?
12_________________________________________________________________
13
15 The Tcl-level handler for a reflected channel has to be a command with
16 subcommands (termed an ensemble, as it is a command such as that cre‐
17 ated by namespace ensemble create, though the implementation of han‐
18 dlers for reflected channel is not tied to namespace ensembles in any
19 way). Note that cmdPrefix is whatever was specified in the call to chan
20 create, and may consist of multiple arguments; this will be expanded to
21 multiple words in place of the prefix.
22 Of all the possible subcommands, the handler must support initialize,
24 finalize, and watch. Support for the other subcommands is optional.
25 MANDATORY SUBCOMMANDS
27 cmdPrefix initialize channelId mode
28 An invocation of this subcommand will be the first call the cmd‐
29 Prefix will receive for the specified new channelId. It is the
30 responsibility of this subcommand to set up any internal data
31 structures required to keep track of the channel and its state.
32 The return value of the method has to be a list containing the
34 names of all subcommands supported by the cmdPrefix. This also
35 tells the Tcl core which version of the API for reflected chan‐
36 nels is used by this command handler.
37 Any error thrown by the method will abort the creation of the
39 channel and no channel will be created. The thrown error will
40 appear as error thrown by chan create. Any exception other than
41 an error (e.g. break, etc.) is treated as (and converted to) an
42 error.
43 Note: If the creation of the channel was aborted due to failures
45 here, then the finalize subcommand will not be called.
46 The mode argument tells the handler whether the channel was
48 opened for reading, writing, or both. It is a list containing
49 any of the strings read or write. The list will always contain
50 at least one element.
51 The subcommand must throw an error if the chosen mode is not
53 supported by the cmdPrefix.
54 cmdPrefix finalize channelId
56 An invocation of this subcommand will be the last call the cmd‐
57 Prefix will receive for the specified channelId. It will be gen‐
58 erated just before the destruction of the data structures of the
59 channel held by the Tcl core. The command handler must not
60 access the channelId anymore in no way. Upon this subcommand
61 being called, any internal resources allocated to this channel
62 must be cleaned up.
63 The return value of this subcommand is ignored.
65 If the subcommand throws an error the command which caused its
67 invocation (usually close) will appear to have thrown this
68 error. Any exception beyond error (e.g. break, etc.) is treated
69 as (and converted to) an error.
70 This subcommand is not invoked if the creation of the channel
72 was aborted during initialize (See above).
73 cmdPrefix watch channelId eventspec
75 This subcommand notifies the cmdPrefix that the specified chan‐
76 nelId is interested in the events listed in the eventspec. This
77 argument is a list containing any of read and write. The list
78 may be empty, which signals that the channel does not wish to be
79 notified of any events. In that situation, the handler should
80 disable event generation completely.
81 Warning: Any return value of the subcommand is ignored. This
83 includes all errors thrown by the subcommand, break, continue,
84 and custom return codes.
85 This subcommand interacts with chan postevent. Trying to post an
87 event which was not listed in the last call to watch will cause
88 chan postevent to throw an error.
89 OPTIONAL SUBCOMMANDS
91 cmdPrefix read channelId count
92 This optional subcommand is called when the user requests data
93 from the channel channelId. count specifies how many bytes have
94 been requested. If the subcommand is not supported then it is
95 not possible to read from the channel handled by the command.
96 The return value of this subcommand is taken as the requested
98 data bytes. If the returned data contains more bytes than
99 requested, an error will be signaled and later thrown by the
100 command which performed the read (usually gets or read). How‐
101 ever, returning fewer bytes than requested is acceptable.
102 If the subcommand throws an error, the command which caused its
104 invocation (usually gets, or read) will appear to have thrown
105 this error. Any exception beyond error, (e.g. break, etc.) is
106 treated as and converted to an error.
107 cmdPrefix write channelId data
109 This optional subcommand is called when the user writes data to
110 the channel channelId. The data argument contains bytes, not
111 characters. Any type of transformation (EOL, encoding) config‐
112 ured for the channel has already been applied at this point. If
113 this subcommand is not supported then it is not possible to
114 write to the channel handled by the command.
115 The return value of the subcommand is taken as the number of
117 bytes written by the channel. Anything non-numeric will cause an
118 error to be signaled and later thrown by the command which per‐
119 formed the write. A negative value implies that the write
120 failed. Returning a value greater than the number of bytes given
121 to the handler, or zero, is forbidden and will cause the Tcl
122 core to throw an error.
123 If the subcommand throws an error the command which caused its
125 invocation (usually puts) will appear to have thrown this error.
126 Any exception beyond error (e.g. break, etc.) is treated as and
127 converted to an error.
128 cmdPrefix seek channelId offset base
130 This optional subcommand is responsible for the handling of seek
131 and tell requests on the channel channelId. If it is not sup‐
132 ported then seeking will not be possible for the channel.
133 The base argument is one of
135 start Seeking is relative to the beginning of the channel.
137 current Seeking is relative to the current seek position.
139 end Seeking is relative to the end of the channel.
141 The base argument of the builtin chan seek command takes the
143 same names.
144 The offset is an integer number specifying the amount of bytes
146 to seek forward or backward. A positive number should seek for‐
147 ward, and a negative number should seek backward.
148 A channel may provide only limited seeking. For example sockets
150 can seek forward, but not backward.
151 The return value of the subcommand is taken as the (new) loca‐
153 tion of the channel, counted from the start. This has to be an
154 integer number greater than or equal to zero.
155 If the subcommand throws an error the command which caused its
157 invocation (usually seek, or tell) will appear to have thrown
158 this error. Any exception beyond error (e.g. break, etc.) is
159 treated as and converted to an error.
160 The offset/base combination of 0/current signals a tell request,
162 i.e. seek nothing relative to the current location, making the
163 new location identical to the current one, which is then
164 returned.
165 cmdPrefix configure channelId option value
167 This optional subcommand is for setting the type-specific
168 options of channel channelId. The option argument indicates the
169 option to be written, and the value argument indicates the value
170 to set the option to.
171 This subcommand will never try to update more than one option at
173 a time; that is behavior implemented in the Tcl channel core.
174 The return value of the subcommand is ignored.
176 If the subcommand throws an error the command which performed
178 the (re)configuration or query (usually fconfigure or chan con‐
179 figure) will appear to have thrown this error. Any exception
180 beyond error (e.g. break, etc.) is treated as and converted to
181 an error.
182 cmdPrefix cget channelId option
184 This optional subcommand is used when reading a single type-spe‐
185 cific option of channel channelId. If this subcommand is sup‐
186 ported then the subcommand cgetall must be supported as well.
187 The subcommand should return the value of the specified option.
189 If the subcommand throws an error, the command which performed
191 the (re)configuration or query (usually fconfigure) will appear
192 to have thrown this error. Any exception beyond error (e.g.
193 break, etc.) is treated as and converted to an error.
194 cmdPrefix cgetall channelId
196 This optional subcommand is used for reading all type-specific
197 options of channel channelId. If this subcommand is supported
198 then the subcommand cget has to be supported as well.
199 The subcommand should return a list of all options and their
201 values. This list must have an even number of elements.
202 If the subcommand throws an error the command which performed
204 the (re)configuration or query (usually fconfigure) will appear
205 to have thrown this error. Any exception beyond error (e.g.
206 break, etc.) is treated as and converted to an error.
207 cmdPrefix blocking channelId mode
209 This optional subcommand handles changes to the blocking mode of
210 the channel channelId. The mode is a boolean flag. A true value
211 means that the channel has to be set to blocking, and a false
212 value means that the channel should be non-blocking.
213 The return value of the subcommand is ignored.
215 If the subcommand throws an error the command which caused its
217 invocation (usually fconfigure) will appear to have thrown this
218 error. Any exception beyond error (e.g. break, etc.) is treated
219 as and converted to an error.
220
222 Some of the functions supported in channels defined in Tcl's C inter‐
223 face are not available to channels reflected to the Tcl level.
224 The function Tcl_DriverGetHandleProc is not supported; i.e. reflected
226 channels do not have OS specific handles.
227 The function Tcl_DriverHandlerProc is not supported. This driver func‐
229 tion is relevant only for stacked channels, i.e. transformations.
230 Reflected channels are always base channels, not transformations.
231 The function Tcl_DriverFlushProc is not supported. This is because the
233 current generic I/O layer of Tcl does not use this function anywhere at
234 all. Therefore support at the Tcl level makes no sense either. This may
235 be altered in the future (through extending the API defined here and
236 changing its version number) should the function be used at some time
237 in the future.
238
240 chan(n)
241
243 channel, reflection
244Tcl 8.5 refchan(n)