Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{ctb}} |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 2 | \bimodindex{ctb} |
Jack Jansen | 64f0845 | 1995-03-01 14:06:52 +0000 | [diff] [blame] | 3 | \renewcommand{\indexsubitem}{(in module ctb)} |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 4 | |
| 5 | This module provides a partial interface to the Macintosh |
| 6 | Communications Toolbox. Currently, only Connection Manager tools are |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame^] | 7 | supported. It may not be available in all Mac Python versions. |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 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}{} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 33 | Return 1 if the communication toolbox is available, zero otherwise. |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 40 | Alternatively, passing \code{None} will result in default buffer sizes. |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 47 | \renewcommand{\indexsubitem}{(connection object attribute)} |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 48 | |
| 49 | \begin{datadesc}{callback} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 50 | If this member is set to a value other than \code{None} it should point |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 57 | is currently never called. You are advised against using asynchronous |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 58 | calls for the time being. |
| 59 | \end{datadesc} |
| 60 | |
| 61 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 62 | \renewcommand{\indexsubitem}{(connection object method)} |
| 63 | |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 81 | (i.e.\ outstanding output is flushed, etc.)\ with a timeout of |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 82 | \var{timeout} seconds. When \var{now} is non-zero the close is |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 83 | immediate, discarding output. |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 84 | \end{funcdesc} |
| 85 | |
| 86 | \begin{funcdesc}{Read}{len\, chan\, timeout} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 87 | Read \var{len} bytes, or until \var{timeout} seconds have passed, from |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 88 | the channel \var{chan} (which is one of \var{cmData}, \var{cmCntl} or |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 89 | \var{cmAttn}). Return a 2-tuple:\ the data read and the end-of-message |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 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}{} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 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 |
Jack Jansen | dcb0a9b | 1995-03-01 14:05:27 +0000 | [diff] [blame] | 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} |