182 lines
6.2 KiB
TeX
182 lines
6.2 KiB
TeX
\section{\module{mactcp} ---
|
|
The MacTCP interfaces}
|
|
|
|
\declaremodule{builtin}{mactcp}
|
|
\platform{Mac}
|
|
\modulesynopsis{The MacTCP interfaces.}
|
|
|
|
|
|
This module provides an interface to the Macintosh TCP/IP driver%
|
|
\index{MacTCP} MacTCP. There is an accompanying module,
|
|
\refmodule{macdnr}\refbimodindex{macdnr}, which provides an interface
|
|
to the name-server (allowing you to translate hostnames to IP
|
|
addresses), a module \module{MACTCPconst}\refstmodindex{MACTCPconst}
|
|
which has symbolic names for constants constants used by MacTCP. Since
|
|
the built-in module \module{socket}\refbimodindex{socket} is also
|
|
available on the Macintosh it is usually easier to use sockets instead
|
|
of the Macintosh-specific MacTCP API.
|
|
|
|
A complete description of the MacTCP interface can be found in the
|
|
Apple MacTCP API documentation.
|
|
|
|
\begin{funcdesc}{MTU}{}
|
|
Return the Maximum Transmit Unit (the packet size) of the network
|
|
interface.\index{Maximum Transmit Unit}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{IPAddr}{}
|
|
Return the 32-bit integer IP address of the network interface.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{NetMask}{}
|
|
Return the 32-bit integer network mask of the interface.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{TCPCreate}{size}
|
|
Create a TCP Stream object. \var{size} is the size of the receive
|
|
buffer, \code{4096} is suggested by various sources.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{UDPCreate}{size, port}
|
|
Create a UDP Stream object. \var{size} is the size of the receive
|
|
buffer (and, hence, the size of the biggest datagram you can receive
|
|
on this port). \var{port} is the UDP port number you want to receive
|
|
datagrams on, a value of zero will make MacTCP select a free port.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{TCP Stream Objects}
|
|
|
|
\begin{memberdesc}[TCP Stream]{asr}
|
|
\index{asynchronous service routine}
|
|
\index{service routine, asynchronous}
|
|
When set to a value different than \code{None} this should refer to a
|
|
function with two integer parameters:\ an event code and a detail. This
|
|
function will be called upon network-generated events such as urgent
|
|
data arrival. Macintosh documentation calls this the
|
|
\dfn{asynchronous service routine}. In addition, it is called with
|
|
eventcode \code{MACTCP.PassiveOpenDone} when a \method{PassiveOpen()}
|
|
completes. This is a Python addition to the MacTCP semantics.
|
|
It is safe to do further calls from \var{asr}.
|
|
\end{memberdesc}
|
|
|
|
|
|
\begin{methoddesc}[TCP Stream]{PassiveOpen}{port}
|
|
Wait for an incoming connection on TCP port \var{port} (zero makes the
|
|
system pick a free port). The call returns immediately, and you should
|
|
use \method{wait()} to wait for completion. You should not issue any method
|
|
calls other than \method{wait()}, \method{isdone()} or
|
|
\method{GetSockName()} before the call completes.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[TCP Stream]{wait}{}
|
|
Wait for \method{PassiveOpen()} to complete.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[TCP Stream]{isdone}{}
|
|
Return \code{1} if a \method{PassiveOpen()} has completed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[TCP Stream]{GetSockName}{}
|
|
Return the TCP address of this side of a connection as a 2-tuple
|
|
\code{(\var{host}, \var{port})}, both integers.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[TCP Stream]{ActiveOpen}{lport, host, rport}
|
|
Open an outgoing connection to TCP address \code{(\var{host},
|
|
\var{rport})}. Use
|
|
local port \var{lport} (zero makes the system pick a free port). This
|
|
call blocks until the connection has been established.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[TCP Stream]{Send}{buf, push, urgent}
|
|
Send data \var{buf} over the connection. \var{push} and \var{urgent}
|
|
are flags as specified by the TCP standard.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[TCP Stream]{Rcv}{timeout}
|
|
Receive data. The call returns when \var{timeout} seconds have passed
|
|
or when (according to the MacTCP documentation) ``a reasonable amount
|
|
of data has been received''. The return value is a 3-tuple
|
|
\code{(\var{data}, \var{urgent}, \var{mark})}. If urgent data is
|
|
outstanding \code{Rcv} will always return that before looking at any
|
|
normal data. The first call returning urgent data will have the
|
|
\var{urgent} flag set, the last will have the \var{mark} flag set.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[TCP Stream]{Close}{}
|
|
Tell MacTCP that no more data will be transmitted on this
|
|
connection. The call returns when all data has been acknowledged by
|
|
the receiving side.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[TCP Stream]{Abort}{}
|
|
Forcibly close both sides of a connection, ignoring outstanding data.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[TCP Stream]{Status}{}
|
|
Return a TCP status object for this stream giving the current status
|
|
(see below).
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{TCP Status Objects}
|
|
|
|
This object has no methods, only some members holding information on
|
|
the connection. A complete description of all fields in this objects
|
|
can be found in the Apple documentation. The most interesting ones are:
|
|
|
|
\begin{memberdesc}[TCP Status]{localHost}
|
|
\memberline{localPort}
|
|
\memberline{remoteHost}
|
|
\memberline{remotePort}
|
|
The integer IP-addresses and port numbers of both endpoints of the
|
|
connection.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[TCP Status]{sendWindow}
|
|
The current window size.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[TCP Status]{amtUnackedData}
|
|
The number of bytes sent but not yet acknowledged. \code{sendWindow -
|
|
amtUnackedData} is what you can pass to \method{Send()} without
|
|
blocking.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[TCP Status]{amtUnreadData}
|
|
The number of bytes received but not yet read (what you can
|
|
\method{Recv()} without blocking).
|
|
\end{memberdesc}
|
|
|
|
|
|
|
|
\subsection{UDP Stream Objects}
|
|
|
|
Note that, unlike the name suggests, there is nothing stream-like
|
|
about UDP.
|
|
|
|
|
|
\begin{memberdesc}[UDP Stream]{asr}
|
|
\index{asynchronous service routine}
|
|
\index{service routine, asynchronous}
|
|
The asynchronous service routine to be called on events such as
|
|
datagram arrival without outstanding \code{Read} call. The \var{asr}
|
|
has a single argument, the event code.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[UDP Stream]{port}
|
|
A read-only member giving the port number of this UDP Stream.
|
|
\end{memberdesc}
|
|
|
|
|
|
\begin{methoddesc}[UDP Stream]{Read}{timeout}
|
|
Read a datagram, waiting at most \var{timeout} seconds (-1 is
|
|
infinite). Return the data.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[UDP Stream]{Write}{host, port, buf}
|
|
Send \var{buf} as a datagram to IP-address \var{host}, port
|
|
\var{port}.
|
|
\end{methoddesc}
|