path: root/Doc/libmactcp.tex

\section{Built-in Module \sectcode{mactcp}}
\label{module-mactcp}
\bimodindex{mactcp}

\renewcommand{\indexsubitem}{(in module mactcp)}

This module provides an interface to the Macintosh TCP/IP driver
MacTCP\@. There is an accompanying module \code{macdnr} which provides an
interface to the name-server (allowing you to translate hostnames to
ip-addresses), a module \code{MACTCPconst} which has symbolic names for
constants constants used by MacTCP. Since the builtin module
\code{socket} is also available on the mac it is usually easier to use
sockets in stead of the mac-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.
\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}

\renewcommand{\indexsubitem}{(TCP stream attribute)}

\begin{datadesc}{asr}
When set to a value different than \code{None} this should point 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. In addition, it is called with eventcode
\code{MACTCP.PassiveOpenDone} when a \code{PassiveOpen} completes. This
is a Python addition to the MacTCP semantics.
It is safe to do further calls from the \code{asr}.
\end{datadesc}

\renewcommand{\indexsubitem}{(TCP stream method)}

\begin{funcdesc}{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 \var{wait} to wait for completion. You should not issue any method
calls other than
\code{wait}, \code{isdone} or \code{GetSockName} before the call
completes.
\end{funcdesc}

\begin{funcdesc}{wait}{}
Wait for \code{PassiveOpen} to complete.
\end{funcdesc}

\begin{funcdesc}{isdone}{}
Return 1 if a \code{PassiveOpen} has completed.
\end{funcdesc}

\begin{funcdesc}{GetSockName}{}
Return the TCP address of this side of a connection as a 2-tuple
\code{(host, port)}, both integers.
\end{funcdesc}

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{Abort}{}
Forcibly close both sides of a connection, ignoring outstanding data.
\end{funcdesc}

\begin{funcdesc}{Status}{}
Return a TCP status object for this stream giving the current status
(see below).
\end{funcdesc}

\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:

\renewcommand{\indexsubitem}{(TCP status attribute)}

\begin{datadesc}{localHost}
\dataline{localPort}
\dataline{remoteHost}
\dataline{remotePort}
The integer IP-addresses and port numbers of both endpoints of the
connection. 
\end{datadesc}

\begin{datadesc}{sendWindow}
The current window size.
\end{datadesc}

\begin{datadesc}{amtUnackedData}
The number of bytes sent but not yet acknowledged. \code{sendWindow -
amtUnackedData} is what you can pass to \code{Send} without blocking.
\end{datadesc}

\begin{datadesc}{amtUnreadData}
The number of bytes received but not yet read (what you can \code{Recv}
without blocking).
\end{datadesc}



\subsection{UDP Stream Objects}
Note that, unlike the name suggests, there is nothing stream-like
about UDP.

\renewcommand{\indexsubitem}{(UDP stream attribute)}

\begin{datadesc}{asr}
The asynchronous service routine to be called on events such as
datagram arrival without outstanding \code{Read} call. The \code{asr} has a
single argument, the event code.
\end{datadesc}

\begin{datadesc}{port}
A read-only member giving the port number of this UDP stream.
\end{datadesc}

\renewcommand{\indexsubitem}{(UDP stream method)}

\begin{funcdesc}{Read}{timeout}
Read a datagram, waiting at most \var{timeout} seconds ($-1$ is
infinite).  Return the data.
\end{funcdesc}

\begin{funcdesc}{Write}{host\, port\, buf}
Send \var{buf} as a datagram to IP-address \var{host}, port
\var{port}.
\end{funcdesc}