Doc/mac/libctb.tex

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