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