Doc/mac/libmactcp.tex

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