summaryrefslogtreecommitdiffstats
path: root/Doc/mac/libmactcp.tex
blob: a16afc8cb5e576724a85ceea6332108c2a5e0236 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
\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}