2.3.1 Connection Objects
For all connection methods that take a timeout argument, a value
of -1 is indefinite, meaning that the command runs to completion.
- callback
-
If this member is set to a value other than
None it should point
to a function accepting a single argument (the connection
object). This will make all connection object methods work
asynchronously, with the callback routine being called upon
completion.
Note:
For reasons beyond my understanding, the callback routine
is currently never called. You are advised against using asynchronous
calls for the time being.
- Open(timeout)
-
Open an outgoing connection, waiting at most timeout seconds for
the connection to be established.
- Listen(timeout)
-
Wait for an incoming connection. Stop waiting after timeout
seconds. This call is only meaningful to some tools.
- accept(yesno)
-
Accept (when yesno is non-zero) or reject an incoming call after
Listen() returned.
- Close(timeout, now)
-
Close a connection. When now is zero, the close is orderly
(outstanding output is flushed, etc.) with a timeout of
timeout seconds. When now is non-zero the close is
immediate, discarding output.
- Read(len, chan, timeout)
-
Read len bytes, or until timeout seconds have passed, from
the channel chan (which is one of cmData,
cmCntl or cmAttn). Return a 2-tuple: the data
read and the end-of-message flag, cmFlagsEOM.
- Write(buf, chan, timeout, eom)
-
Write buf to channel chan, aborting after timeout
seconds. When eom has the value cmFlagsEOM, an
end-of-message indicator will be written after the data (if this
concept has a meaning for this communication tool). The method returns
the number of bytes written.
- Status()
-
Return connection status as the 2-tuple
(sizes,
flags). sizes is a 6-tuple giving the actual buffer sizes used
(see CMNew()), flags is a set of bits describing the state
of the connection.
- GetConfig()
-
Return the configuration string of the communication tool. These
configuration strings are tool-dependent, but usually easily parsed
and modified.
- SetConfig(str)
-
Set the configuration string for the tool. The strings are parsed
left-to-right, with later values taking precedence. This means
individual configuration parameters can be modified by simply appending
something like
'baud 4800' to the end of the string returned by
GetConfig() and passing that to this method. The method returns
the number of characters actually parsed by the tool before it
encountered an error (or completed successfully).
- Choose()
-
Present the user with a dialog to choose a communication tool and
configure it. If there is an outstanding connection some choices (like
selecting a different tool) may cause the connection to be
aborted. The return value (one of the choose* constants) will
indicate this.
- Idle()
-
Give the tool a chance to use the processor. You should call this
method regularly.
- Abort()
-
Abort an outstanding asynchronous Open() or Listen().
- Reset()
-
Reset a connection. Exact meaning depends on the tool.
- Break(length)
-
Send a break. Whether this means anything, what it means and
interpretation of the length parameter depends on the tool in
use.
See About this document... for information on suggesting changes.
