Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{mactcp}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-mactcp} |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 3 | \bimodindex{mactcp} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 4 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 5 | \setindexsubitem{(in module mactcp)} |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 6 | |
| 7 | This module provides an interface to the Macintosh TCP/IP driver |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 8 | MacTCP\@. There is an accompanying module \code{macdnr} which provides an |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 9 | interface to the name-server (allowing you to translate hostnames to |
Guido van Rossum | 66774a9 | 1996-07-21 02:20:58 +0000 | [diff] [blame] | 10 | ip-addresses), a module \code{MACTCPconst} which has symbolic names for |
| 11 | constants constants used by MacTCP. Since the builtin module |
| 12 | \code{socket} is also available on the mac it is usually easier to use |
| 13 | sockets in stead of the mac-specific MacTCP API. |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 14 | |
| 15 | A complete description of the MacTCP interface can be found in the |
| 16 | Apple MacTCP API documentation. |
| 17 | |
| 18 | \begin{funcdesc}{MTU}{} |
| 19 | Return the Maximum Transmit Unit (the packet size) of the network |
| 20 | interface. |
| 21 | \end{funcdesc} |
| 22 | |
| 23 | \begin{funcdesc}{IPAddr}{} |
| 24 | Return the 32-bit integer IP address of the network interface. |
| 25 | \end{funcdesc} |
| 26 | |
| 27 | \begin{funcdesc}{NetMask}{} |
| 28 | Return the 32-bit integer network mask of the interface. |
| 29 | \end{funcdesc} |
| 30 | |
| 31 | \begin{funcdesc}{TCPCreate}{size} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 32 | Create a TCP Stream object. \var{size} is the size of the receive |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 33 | buffer, \code{4096} is suggested by various sources. |
| 34 | \end{funcdesc} |
| 35 | |
| 36 | \begin{funcdesc}{UDPCreate}{size, port} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 37 | Create a UDP stream object. \var{size} is the size of the receive |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 38 | buffer (and, hence, the size of the biggest datagram you can receive |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 39 | on this port). \var{port} is the UDP port number you want to receive |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 40 | datagrams on, a value of zero will make MacTCP select a free port. |
| 41 | \end{funcdesc} |
| 42 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 43 | \subsection{TCP Stream Objects} |
| 44 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 45 | \setindexsubitem{(TCP stream attribute)} |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 46 | |
| 47 | \begin{datadesc}{asr} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 48 | When set to a value different than \code{None} this should point to a |
| 49 | function with two integer parameters:\ an event code and a detail. This |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 50 | function will be called upon network-generated events such as urgent |
| 51 | data arrival. In addition, it is called with eventcode |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 52 | \code{MACTCP.PassiveOpenDone} when a \code{PassiveOpen} completes. This |
| 53 | is a Python addition to the MacTCP semantics. |
| 54 | It is safe to do further calls from the \code{asr}. |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 55 | \end{datadesc} |
| 56 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 57 | \setindexsubitem{(TCP stream method)} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 58 | |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 59 | \begin{funcdesc}{PassiveOpen}{port} |
| 60 | Wait for an incoming connection on TCP port \var{port} (zero makes the |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 61 | system pick a free port). The call returns immediately, and you should |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 62 | use \var{wait} to wait for completion. You should not issue any method |
| 63 | calls other than |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 64 | \code{wait}, \code{isdone} or \code{GetSockName} before the call |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 65 | completes. |
| 66 | \end{funcdesc} |
| 67 | |
| 68 | \begin{funcdesc}{wait}{} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 69 | Wait for \code{PassiveOpen} to complete. |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 70 | \end{funcdesc} |
| 71 | |
| 72 | \begin{funcdesc}{isdone}{} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 73 | Return 1 if a \code{PassiveOpen} has completed. |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 74 | \end{funcdesc} |
| 75 | |
| 76 | \begin{funcdesc}{GetSockName}{} |
| 77 | Return the TCP address of this side of a connection as a 2-tuple |
| 78 | \code{(host, port)}, both integers. |
| 79 | \end{funcdesc} |
| 80 | |
| 81 | \begin{funcdesc}{ActiveOpen}{lport\, host\, rport} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 82 | Open an outgoing connection to TCP address \code{(\var{host}, \var{rport})}. Use |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 83 | local port \var{lport} (zero makes the system pick a free port). This |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 84 | call blocks until the connection has been established. |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 85 | \end{funcdesc} |
| 86 | |
| 87 | \begin{funcdesc}{Send}{buf\, push\, urgent} |
| 88 | Send data \var{buf} over the connection. \var{Push} and \var{urgent} |
| 89 | are flags as specified by the TCP standard. |
| 90 | \end{funcdesc} |
| 91 | |
| 92 | \begin{funcdesc}{Rcv}{timeout} |
| 93 | Receive data. The call returns when \var{timeout} seconds have passed |
| 94 | or when (according to the MacTCP documentation) ``a reasonable amount |
| 95 | of data has been received''. The return value is a 3-tuple |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 96 | \code{(\var{data}, \var{urgent}, \var{mark})}. If urgent data is outstanding \code{Rcv} |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 97 | will always return that before looking at any normal data. The first |
| 98 | call returning urgent data will have the \var{urgent} flag set, the |
| 99 | last will have the \var{mark} flag set. |
| 100 | \end{funcdesc} |
| 101 | |
| 102 | \begin{funcdesc}{Close}{} |
| 103 | Tell MacTCP that no more data will be transmitted on this |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 104 | connection. The call returns when all data has been acknowledged by |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 105 | the receiving side. |
| 106 | \end{funcdesc} |
| 107 | |
| 108 | \begin{funcdesc}{Abort}{} |
| 109 | Forcibly close both sides of a connection, ignoring outstanding data. |
| 110 | \end{funcdesc} |
| 111 | |
| 112 | \begin{funcdesc}{Status}{} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 113 | Return a TCP status object for this stream giving the current status |
| 114 | (see below). |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 115 | \end{funcdesc} |
| 116 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 117 | \subsection{TCP Status Objects} |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 118 | This object has no methods, only some members holding information on |
| 119 | the connection. A complete description of all fields in this objects |
| 120 | can be found in the Apple documentation. The most interesting ones are: |
| 121 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 122 | \setindexsubitem{(TCP status attribute)} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 123 | |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 124 | \begin{datadesc}{localHost} |
| 125 | \dataline{localPort} |
| 126 | \dataline{remoteHost} |
| 127 | \dataline{remotePort} |
| 128 | The integer IP-addresses and port numbers of both endpoints of the |
| 129 | connection. |
| 130 | \end{datadesc} |
| 131 | |
| 132 | \begin{datadesc}{sendWindow} |
| 133 | The current window size. |
| 134 | \end{datadesc} |
| 135 | |
| 136 | \begin{datadesc}{amtUnackedData} |
| 137 | The number of bytes sent but not yet acknowledged. \code{sendWindow - |
| 138 | amtUnackedData} is what you can pass to \code{Send} without blocking. |
| 139 | \end{datadesc} |
| 140 | |
| 141 | \begin{datadesc}{amtUnreadData} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 142 | The number of bytes received but not yet read (what you can \code{Recv} |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 143 | without blocking). |
| 144 | \end{datadesc} |
| 145 | |
| 146 | |
| 147 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 148 | \subsection{UDP Stream Objects} |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 149 | Note that, unlike the name suggests, there is nothing stream-like |
| 150 | about UDP. |
| 151 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 152 | \setindexsubitem{(UDP stream attribute)} |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 153 | |
| 154 | \begin{datadesc}{asr} |
| 155 | The asynchronous service routine to be called on events such as |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 156 | datagram arrival without outstanding \code{Read} call. The \code{asr} has a |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 157 | single argument, the event code. |
| 158 | \end{datadesc} |
| 159 | |
| 160 | \begin{datadesc}{port} |
| 161 | A read-only member giving the port number of this UDP stream. |
| 162 | \end{datadesc} |
| 163 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 164 | \setindexsubitem{(UDP stream method)} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 165 | |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 166 | \begin{funcdesc}{Read}{timeout} |
Guido van Rossum | f259efe | 1997-11-25 01:00:40 +0000 | [diff] [blame] | 167 | Read a datagram, waiting at most \var{timeout} seconds (-1 is |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 168 | infinite). Return the data. |
Jack Jansen | b721ef1 | 1995-03-01 14:54:30 +0000 | [diff] [blame] | 169 | \end{funcdesc} |
| 170 | |
| 171 | \begin{funcdesc}{Write}{host\, port\, buf} |
| 172 | Send \var{buf} as a datagram to IP-address \var{host}, port |
| 173 | \var{port}. |
| 174 | \end{funcdesc} |