Doc/mac/libctb.tex

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