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