Doc/libctb.tex

   1 \section{Built-in Module \module{ctb}}
   2 \label{module-ctb}
   3 \bimodindex{ctb}
   4
   5 This module provides a partial interface to the Macintosh
   6 Communications Toolbox. Currently, only Connection Manager tools are
   7 supported.  It may not be available in all Mac Python versions.
   8 \index{Communications Toolbox, Macintosh}
   9 \index{Macintosh Communications Toolbox}
  10 \index{Connection Manager}
  11
  12 \begin{datadesc}{error}
  13 The exception raised on errors.
  14 \end{datadesc}
  15
  16 \begin{datadesc}{cmData}
  17 \dataline{cmCntl}
  18 \dataline{cmAttn}
  19 Flags for the \var{channel} argument of the \method{Read()} and
  20 \method{Write()} methods.
  21 \end{datadesc}
  22
  23 \begin{datadesc}{cmFlagsEOM}
  24 End-of-message flag for \method{Read()} and \method{Write()}.
  25 \end{datadesc}
  26
  27 \begin{datadesc}{choose*}
  28 Values returned by \method{Choose()}.
  29 \end{datadesc}
  30
  31 \begin{datadesc}{cmStatus*}
  32 Bits in the status as returned by \method{Status()}.
  33 \end{datadesc}
  34
  35 \begin{funcdesc}{available}{}
  36 Return \code{1} if the Communication Toolbox is available, zero otherwise.
  37 \end{funcdesc}
  38
  39 \begin{funcdesc}{CMNew}{name, sizes}
  40 Create a connection object using the connection tool named
  41 \var{name}. \var{sizes} is a 6-tuple given buffer sizes for data in,
  42 data out, control in, control out, attention in and attention out.
  43 Alternatively, passing \code{None} for \var{sizes} will result in
  44 default buffer sizes.
  45 \end{funcdesc}
  46
  47 \subsection{connection object}
  48 \label{connection-object}
  49
  50 For all connection methods that take a \var{timeout} argument, a value
  51 of \code{-1} is indefinite, meaning that the command runs to completion.
  52
  53 \begin{memberdesc}[connection]{callback}
  54 If this member is set to a value other than \code{None} it should point
  55 to a function accepting a single argument (the connection
  56 object). This will make all connection object methods work
  57 asynchronously, with the callback routine being called upon
  58 completion.
  59
  60 \emph{Note:} for reasons beyond my understanding the callback routine
  61 is currently never called. You are advised against using asynchronous
  62 calls for the time being.
  63 \end{memberdesc}
  64
  65
  66 \begin{methoddesc}[connection]{Open}{timeout}
  67 Open an outgoing connection, waiting at most \var{timeout} seconds for
  68 the connection to be established.
  69 \end{methoddesc}
  70
  71 \begin{methoddesc}[connection]{Listen}{timeout}
  72 Wait for an incoming connection. Stop waiting after \var{timeout}
  73 seconds. This call is only meaningful to some tools.
  74 \end{methoddesc}
  75
  76 \begin{methoddesc}[connection]{accept}{yesno}
  77 Accept (when \var{yesno} is non-zero) or reject an incoming call after
  78 \method{Listen()} returned.
  79 \end{methoddesc}
  80
  81 \begin{methoddesc}[connection]{Close}{timeout, now}
  82 Close a connection. When \var{now} is zero, the close is orderly
  83 (i.e.\ outstanding output is flushed, etc.)\ with a timeout of
  84 \var{timeout} seconds. When \var{now} is non-zero the close is
  85 immediate, discarding output.
  86 \end{methoddesc}
  87
  88 \begin{methoddesc}[connection]{Read}{len, chan, timeout}
  89 Read \var{len} bytes, or until \var{timeout} seconds have passed, from
  90 the channel \var{chan} (which is one of \constant{cmData},
  91 \constant{cmCntl} or \constant{cmAttn}). Return a 2-tuple:\ the data
  92 read and the end-of-message flag, \constant{cmFlagsEOM}.
  93 \end{methoddesc}
  94
  95 \begin{methoddesc}[connection]{Write}{buf, chan, timeout, eom}
  96 Write \var{buf} to channel \var{chan}, aborting after \var{timeout}
  97 seconds. When \var{eom} has the value \constant{cmFlagsEOM}, an
  98 end-of-message indicator will be written after the data (if this
  99 concept has a meaning for this communication tool). The method returns
 100 the number of bytes written.
 101 \end{methoddesc}
 102
 103 \begin{methoddesc}[connection]{Status}{}
 104 Return connection status as the 2-tuple \code{(\var{sizes},
 105 \var{flags})}. \var{sizes} is a 6-tuple giving the actual buffer sizes used
 106 (see \function{CMNew()}), \var{flags} is a set of bits describing the state
 107 of the connection.
 108 \end{methoddesc}
 109
 110 \begin{methoddesc}[connection]{GetConfig}{}
 111 Return the configuration string of the communication tool. These
 112 configuration strings are tool-dependent, but usually easily parsed
 113 and modified.
 114 \end{methoddesc}
 115
 116 \begin{methoddesc}[connection]{SetConfig}{str}
 117 Set the configuration string for the tool. The strings are parsed
 118 left-to-right, with later values taking precedence. This means
 119 individual configuration parameters can be modified by simply appending
 120 something like \code{'baud 4800'} to the end of the string returned by
 121 \method{GetConfig()} and passing that to this method. The method returns
 122 the number of characters actually parsed by the tool before it
 123 encountered an error (or completed successfully).
 124 \end{methoddesc}
 125
 126 \begin{methoddesc}[connection]{Choose}{}
 127 Present the user with a dialog to choose a communication tool and
 128 configure it. If there is an outstanding connection some choices (like
 129 selecting a different tool) may cause the connection to be
 130 aborted. The return value (one of the \constant{choose*} constants) will
 131 indicate this.
 132 \end{methoddesc}
 133
 134 \begin{methoddesc}[connection]{Idle}{}
 135 Give the tool a chance to use the processor. You should call this
 136 method regularly.
 137 \end{methoddesc}
 138
 139 \begin{methoddesc}[connection]{Abort}{}
 140 Abort an outstanding asynchronous \method{Open()} or \method{Listen()}.
 141 \end{methoddesc}
 142
 143 \begin{methoddesc}[connection]{Reset}{}
 144 Reset a connection. Exact meaning depends on the tool.
 145 \end{methoddesc}
 146
 147 \begin{methoddesc}[connection]{Break}{length}
 148 Send a break. Whether this means anything, what it means and
 149 interpretation of the \var{length} parameter depends on the tool in
 150 use.
 151 \end{methoddesc}