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 (i.e. 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.

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.