forked from python/cpython
-
Notifications
You must be signed in to change notification settings - Fork 0
/
libmactcp.tex
178 lines (139 loc) · 6.1 KB
/
libmactcp.tex
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
175
176
177
178
\section{Built-in Module \module{mactcp}}
\label{module-mactcp}
\bimodindex{mactcp}
This module provides an interface to the Macintosh TCP/IP driver%
\index{MacTCP} MacTCP\@. There is an accompanying module,
\module{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} 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 \code{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 \code{PassiveOpen} to complete.
\end{methoddesc}
\begin{methoddesc}[TCP Stream]{isdone}{}
Return \code{1} if a \code{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}