Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b721ef1

Browse files
jackjansenjackjansen
committed
Half the mactcp documentation (macdnr still to come)
1 parent 81b3060 commit b721ef1

2 files changed

Lines changed: 328 additions & 0 deletions

File tree

‎Doc/libmactcp.tex‎

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

‎Doc/mac/libmactcp.tex‎

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

0 commit comments

Comments
 (0)