hci_pd_receive contns
This function prepares to parse the input off the line. It attempts to
match the input against each of the given phrases. The contns
argument is a keylist
that instructs the programmable driver what to do in various circumstances. Apart
from special keys, the mapping is from names of phrases to Tcl functions that are
called when the named phrase is read by the system.
This table shows keys in contns
which are treated specially and
not as phrase names:
Key | Description |
---|---|
no-match | Specifies the continuation to invoke when the received input does not
match any of the specified phrases. If a match is found, then the corresponding Tcl function (continuation) is called. no-match continuation is called. If, in trying to match the input, an I/O operation times out, then the time-out continuation is invoked. |
line-error | Invokes the continuation if the connection is lost. This is loss of
carrier signal for async lines with require-cd enabled, or remote closure of a socket for
TCP servers or clients. The continuation is also called if parity or
a framing error is detected, or there is an unexpected end of input.
Use this key for TCP devices if the remote process dies, or, in the case of an async modem line, if the carrier is lost. |
error | Specifies that both no-match and line-error are the same continuation. Do not use it with those keys. |
timeout | Specifies the time-out length and is a required procedure to invoke (a
Tcl continuation to resume) in the event of time-out. Make the value associated with the time-out key a Tcl list of two elements. The first is an integer which specifies the length of the time-out, in milliseconds. The second is the usual Tcl continuation. If omitted, then the operation can take arbitrary time. |
If an error continuation for no-match or line-error is not specified and error is not given, then the engine uses one of these default functions:
- no-match
Discards all of the buffered input and returns to the IDLE state.
- line-error
Signals an error and terminates the driver.
All of the continuations are passed a keylist that contains a status
key.
For a successful read, the value of status is ok
. The keylist that is passed to a successful read continuation reads
the field names of the phrase as keys. Each key has a value that is the field value
region of the input buffer. This keylist also contains the key end; its value is the
region of the input buffer which was not read to match the phrase.
For an error continuation, the status indicates the type of error:
no-match
line-error
timeout
Example
hci_pd_receive {{foo did_read.foo} {no-match failed} \
{timeout {1000 tooslow}}}
Use this example to match a foo
phrase with these options:
- Calling the Tcl procedure
did_read.foo
, when successful. - Calling the Tcl procedure
failed
, when the received data did not match thefoo
phrase. - Tolerating up to 1 second between characters.