Doc/libmactcp.tex

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