2.3.1 Connection Objects
Keywords: mac

##
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.

`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.