1include(head.html.m4)
2define(SECTION,lower)
3include(navbar.html.m4)
4
5TITLE(Layer one: protocol abstraction)
6<p align=justify>
7Skip this layer if you really want to use Armagetron's networking system
8fast; it contains details you do not need to know from the start.
9</p>
10<p align=justify>
11This layer is responsible for sending raw data packets to other computers.
12The files <CODE>net_anet.h,net_sysdep.C,net_udp.C</CODE> and
13<CODE>net_wins.C</CODE> are responsible for it;
14they are written in pure C.
15<CODE>net_anet.h</CODE> is the header file with the declarations visible to
16layer two, and <CODE>net_systep.C</CODE> just includes the real
17implementation from <CODE>net_udp.C</CODE> or <CODE>net_wins.C</CODE> depending
18on the system Armagetron is compiled for.
19</p>
20
21SECTION(Data structures)
22
23CODELISTBEGIN
24CODEITEM(sockaddr,struct sockaddr:,
25[Everything the network protocol needs to identify
26a connection to another computer. In the case of UDP, it contains the IP
27address and port number.])
28
29CODEITEM(socket,Sockets:,
30[represented by integers: in analogy to file descriptors,
31all network IO is done
32through sockets. Every client has one socket where all the messages to/from
33the server are sent/received through. The server has one listening socket for
34the messages from new clients, and one IO socket for each client.
35(With the UDP protocol, all these sockets are really identical, as there is
36no such thing as a connection and no need/possibility to assign a connection
37to the sockets.)])
38CODELISTEND
39
40SECTION(Function list)
41(only the functions layer two actually uses are mentioned)
42
43CODELISTBEGIN
44CODEITEM(init,Socket ANET_Init();,[Initialises the network system, returns the
45control socket. All future IO is done through that socket.])
46
47CODEITEM(shutdown,void ANET_Shutdown (void);,Closes the network system.)
48
49CODEITEM(listen,void ANET_Listen(bool state);,[If state is true, the listening
50socket is initialised (listening at the port ]<CODE>net_hostport=4532</CODE>[)
51 and can be queried by]
52<CODE>ANET_CheckNewConnections</CODE>.)
53
54CODEITEM(checknewconnections,Socket ANET_CheckNewConnections (void);,
55[On the server, this checks if there are any new connections
56from clients wanting to join the game. Returns a socket ready to receive
57the newcomer if there is one, or -1 if not. In case of the UDP protocol,
58even the messages from the known clients are caught by this function
59(as there is no way to distinguish new and old connections with UDP), so layer
60two needs to do some extra checks with this function.
61])
62
63CODEITEM(getaddrfromname,[int ANET_GetAddrFromName
64(const char *name, struct sockaddr *addr);],[
65Fills <CODE>*addr</CODE> with the information necessary to reach the server
66<CODE>name</CODE> (containing the IP address in numerical notation or the
67hostname);
68the port number is set to ]<CODE>net_hostport=4532</CODE> to match the port
69the server listens on.)
70
71CODEITEM(connect,ANET_Connect(Socket s,struct sockaddr *addr);,[
72Opens a connection to the computer given by ]<CODE>addr</CODE>[ through
73the socket] <CODE>s</CODE>.
74[As UDP is a connectionless protocol, this does not do
75anything currently.])
76
77CODEITEM(write,int  ANET_Write (Socket sock, const byte *buf, int len, struct sockaddr *addr);,
78Sends <CODE>len</CODE> bytes of data from <CODE>buf</CODE> through the socket
79<CODE>sock</CODE> to the peer identified with <CODE>*addr</CODE>. A connection
80has to be established before with <CODE>ANET_Connect()</CODE>.)
81
82CODEITEM(read,int  ANET_Read (Socket sock, byte *buf, int len, struct sockaddr *addr);,
83Reads up to <CODE>len</CODE> bytes from the connection associated to
84socket <CODE>sock</CODE> and stores them in the buffer <CODE>buf</CODE>.
85[(If a connectionless protocol like UDP is used and the socket is a listening
86socket, this can mean ANY data coming in at the port the socket listens on...)
87]The sender's address is stored in <CODE>*addr</CODE>[, the number of actually
88read bytes is returned (Zero means no data was received.)])
89
90CODEITEM(addrtostring,char *ANET_AddrToString (const struct sockaddr *addr);,[
91Returns the information from ]<CODE>addr</CODE>[ in human readable form.])
92
93CODEITEM(addrcompare,int ANET_AddrCompare (struct sockaddr *addr1, struct sockaddr *addr2);,
94Checks whether <CODE>*addr1</CODE> and <CODE>*addr2</CODE> [are the same
95computer (ignoring the port number). If they are, 0 is returned, -1 if not.])
96
97CODEITEM(getsocketport,int  ANET_GetSocketPort (struct sockaddr *addr),
98Returns the port number from <CODE>*addr</CODE>.)
99
100CODELISTEND
101
102
103include(sig.m4)
104include(navbar.html.m4)
105
106</body>
107</html>
108
109