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 the foo phrase.
  • Tolerating up to 1 second between characters.