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