Doc/mac/libmactcp.tex

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