# HG changeset patch # User Tero Marttila # Date 1232136229 -7200 # Node ID d64bf28c4340e5918499e54e13370446a47a0636 # Parent c7295b72731ac8a6cf17e1d7b076c52ddb52e56c more documentation tweaking, all Network/ files now have a @file comment. Fix Platform.h -> Platform.hh, and Buffer.hh + Packet.cc diff -r c7295b72731a -r d64bf28c4340 src/Network/Address.hh --- a/src/Network/Address.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Address.hh Fri Jan 16 22:03:49 2009 +0200 @@ -20,6 +20,8 @@ * used in a more specifc fashion like NetworkSocket::send or NetworkSocket::accept, where a definitive address is * required. * + * The update() method does a blocking reverse-DNS lookup. XXX: only do the reverse lookup if get_hostname is called? + * * XXX: currently, there is no way to form a NetworkAddress from a NetworkEndpoint for e.g. sending UDP packets without * an associated TCP connection. */ diff -r c7295b72731a -r d64bf28c4340 src/Network/Buffer.hh --- a/src/Network/Buffer.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Buffer.hh Fri Jan 16 22:03:49 2009 +0200 @@ -224,7 +224,7 @@ /* * NetworkBufferInput template method implementation */ -template bool NetworkBufferOutput::peek_data (PrefixType &prefix, char *&buf_ref) { +template bool NetworkBufferInput::peek_data (PrefixType &prefix, char *&buf_ref) { size_t missing = 0; do { @@ -261,7 +261,7 @@ return true; } -template void NetworkBufferOutput::flush_data (void) { +template void NetworkBufferInput::flush_data (void) { PrefixType prefix; // we *must* have a valid prefix diff -r c7295b72731a -r d64bf28c4340 src/Network/Client.hh --- a/src/Network/Client.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Client.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,6 +1,12 @@ #ifndef NETWORKCLIENT_HH #define NETWORKCLIENT_HH +/** + * @file + * + * Game client implementation + */ + // forward-declare class NetworkClient; class NetworkClientLocalPlayer; diff -r c7295b72731a -r d64bf28c4340 src/Network/Config.hh --- a/src/Network/Config.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Config.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,28 +1,24 @@ #ifndef NETWORK_CONFIG_HH #define NETWORK_CONFIG_HH -// socket-related includes -// copied from clanlib code, so should be relatively OS-safe -#ifndef WIN32 - #include - #include - #include - #include - #include - #include -#else - #include - #include - typedef int socklen_t; -#endif +/** + * @file + * + * Network-related configuration + */ #include +/** Default port used for network games */ const std::string NETWORK_PORT_STR = "9338"; +/** Maximum packet size used for normal NetworkPackets... aligned to a sensible UDP mtu */ const size_t NETWORK_PACKET_SIZE = 1280; + +/** Backlog used for TCP server... doesn't really matter all that much */ const int NETWORK_LISTEN_BACKLOG = 5; +/** Magic string used to identify game between client/server */ const char NETWORK_MAGIC_STR[8+1] = "KISNGLIS"; const uint64_t NETWORK_MAGIC_ID = * ((const uint64_t *) NETWORK_MAGIC_STR); diff -r c7295b72731a -r d64bf28c4340 src/Network/Endpoint.hh --- a/src/Network/Endpoint.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Endpoint.hh Fri Jan 16 22:03:49 2009 +0200 @@ -31,6 +31,8 @@ * It may be of value to note that the hostname/service is only interpreted by the get_addrinfo() method, which means * that invalid/non-existant hostnames/services will only raise an error once the NetworkEndpoint is passed to * NetworkSocket. + * + * All DNS lookups are blocking. */ class NetworkEndpoint { protected: diff -r c7295b72731a -r d64bf28c4340 src/Network/Error.hh --- a/src/Network/Error.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Error.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,6 +1,12 @@ #ifndef NETWORK_ERROR_HH #define NETWORK_ERROR_HH +/** + * @file + * + * Base classes for shared errno-enabled errors + */ + #include "../Error.hh" /** diff -r c7295b72731a -r d64bf28c4340 src/Network/Node.hh --- a/src/Network/Node.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Node.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,6 +1,12 @@ #ifndef NETWORK_NODE_HH #define NETWORK_NODE_HH +/** + * @file + * + * Remote NetworkSessions + */ + // forward-declare class NetworkNode; diff -r c7295b72731a -r d64bf28c4340 src/Network/Object.hh --- a/src/Network/Object.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Object.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,6 +1,12 @@ #ifndef NETWORK_OBJECT_HH #define NETWORK_OBJECT_HH +/** + * @file + * + * Object-based network protocol for use with NetworkSession + */ + #include "Session.hh" #include "Node.hh" #include "../Logger.hh" diff -r c7295b72731a -r d64bf28c4340 src/Network/Packet.cc --- a/src/Network/Packet.cc Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Packet.cc Fri Jan 16 22:03:49 2009 +0200 @@ -3,6 +3,7 @@ #include #include "Packet.hh" +#include "Platform.hh" #include diff -r c7295b72731a -r d64bf28c4340 src/Network/Packet.hh --- a/src/Network/Packet.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Packet.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,6 +1,12 @@ #ifndef NETWORK_PACKET_HH #define NETWORK_PACKET_HH +/** + * @file + * + * Provides the NetworkPackets that are used to communicate over a NetworkTCP/NetworkUDP sockets. + */ + #include "Config.hh" #include "../Types.hh" #include "../Error.hh" @@ -101,6 +107,9 @@ protected: /** * Adjust size of the most recent write_ptr area of buf_len bytes to data_len bytes. + * + * You must not call write() between calls to write_ptr() and write_ptr_adjust(). This is only valid for the + * most recent write_ptr() */ virtual void write_ptr_adjust (size_t buf_len, size_t data_len) = 0; @@ -182,7 +191,6 @@ */ char *buf_ptr; - // the buffer size, the amount of data in the buffer, and the current read/write offset /** * The size of the memory region pointed to by buf_ptr */ @@ -263,6 +271,8 @@ /* * Accessor functions, used by the actual socket code to read/write the buffer + * + * XXX: own abstract class for these? Virtual methods <3 */ char* get_buf (void) { return buf_ptr; } const char* get_buf (void) const { return buf_ptr; } diff -r c7295b72731a -r d64bf28c4340 src/Network/Platform.h --- a/src/Network/Platform.h Fri Jan 16 21:24:45 2009 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,30 +0,0 @@ -#ifndef NETWORK_PLATFORM_H -#define NETWORK_PLATFORM_H - -/** - * @file - * - * Takes care of platform-specific imports and #defines as regards the Network code - */ - -#ifndef WIN32 - // NetworkAddress - #include - - // NetworkEndpoint - #include - #include - - // NetworkSocket - #include - #include - #include - #include - #define closesocket close - -#else - #error "This network code won't compile on win32 :)" -#endif - - -#endif diff -r c7295b72731a -r d64bf28c4340 src/Network/Platform.hh --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/Network/Platform.hh Fri Jan 16 22:03:49 2009 +0200 @@ -0,0 +1,43 @@ +#ifndef NETWORK_PLATFORM_HH +#define NETWORK_PLATFORM_HH + +/** + * @file + * + * Takes care of platform-specific imports and #defines as regards the Network code + */ + +#ifndef WIN32 + // NetworkAddress + #include + + // NetworkEndpoint + #include + #include + + // NetworkSocket + #include + #include + #include + #include + #define closesocket close + + // NetworkReactor + #include + #include + + // misc, here because ClanLib included these... + #include + #include + #include +#else + // misc, here because ClanLib included these... + #include + #include + typedef int socklen_t; + + #error "This network code won't compile on win32 :)" +#endif + + +#endif diff -r c7295b72731a -r d64bf28c4340 src/Network/Protocol.hh --- a/src/Network/Protocol.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Protocol.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,10 +1,15 @@ #ifndef NETWORK_PROTOCOL_HH #define NETWORK_PROTOCOL_HH -/* - * The network protocol is defined here :o +/** + * @file + * + * Definitions for game network protocol */ +/** + * The various NetworkChannelIDs used with our NetworkSession + */ enum NetworkChannel { /* * Core channel used for NetworkSession @@ -21,15 +26,27 @@ NETCHAN_TERRAIN_ARRAY = 0x0010, }; +/** + * Various flags used with NETMSG_PLAYER_POSITION related to PhysicsObject state + */ enum NetworkPhysicsFlags { NETWORK_PHYSICS_INAIR = 0x01, NETWORK_PHYSICS_FACE_RIGHT = 0x02, }; +/** + * Various flags used with NETMSG_PROJECTILE_* messages... + */ enum NetworkProjectileFlags { + /** NETMSG_PROJECTILE_DESTROY */ NETWORK_PROJECTILE_REMOVE_GROUND = 0x01, }; +/** + * Various NetworkMessageIDs used with our NetworkSession's NetworkObjects. + * + * Message names are of the form 'NETMSG__' + */ enum NetworkMessage { NETMSG_PACKET_INVALID = 0x0000, diff -r c7295b72731a -r d64bf28c4340 src/Network/Reactor.cc --- a/src/Network/Reactor.cc Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Reactor.cc Fri Jan 16 22:03:49 2009 +0200 @@ -10,7 +10,7 @@ void NetworkReactor::poll (timeval *timeout) { int ret; - // start counting the maximum fd from -1, so that select is given nfds=0 if our list is empty + // start counting the maximum fd from 0, select will be given nfds=1 if empty int fd_max = 0; // zero our fdsets @@ -25,7 +25,7 @@ // ask socket what events it wants NetworkPollMask mask = socket->get_poll(); - // set read/write + // ignore if nothing if (mask) { // socket file descriptor... int fd = socket->get_socket(); @@ -40,11 +40,11 @@ // read... if (mask & POLL_READ) - FD_SET(socket->get_socket(), &read); + FD_SET(fd, &read); // write... if (mask & POLL_WRITE) - FD_SET(socket->get_socket(), &write); + FD_SET(fd, &write); } } diff -r c7295b72731a -r d64bf28c4340 src/Network/Reactor.hh --- a/src/Network/Reactor.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Reactor.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,11 +1,17 @@ #ifndef NETWORK_REACTOR_HH #define NETWORK_REACTOR_HH +/** + * @file + * + * A select() based reactor for NetworkSocket's + */ + // forward-declare class NetworkReactor; /** - * Events to poll for + * Event types to poll for */ enum NetworkPollBit { POLL_READ = 0x01, @@ -17,24 +23,21 @@ */ typedef int NetworkPollMask; +#include "Platform.hh" #include "Socket.hh" #include "Error.hh" -/* - * Platform-specific includes - */ -#ifndef WIN32 - // linux - #include - #include -#else - #error "This network code won't compile on win32 :)" -#endif - #include /** - * A Reactor manages a set of NetworkSockets, providing readyness notification and a poll method + * A reactor maintains a list of NetworkSockets (which must register themselves to their reactor), and providers + * readyness notification of non-blocking I/O operations. + * + * NetworkSockets must call add_socket(), whereup the NetworkReactor will use NetworkSocket::get_poll() to build the + * set of sockets to notify. If activity is detected, I will call NetworkSocket::notify(). + * + * The poll() method can then be used by the application main loop to do timed sleeps, waking up on socket activity and + * driving the sockets. */ class NetworkReactor { protected: @@ -47,13 +50,13 @@ NetworkReactor (void); /** - * Our static global reactor + * The global NetworkReactor, used by default for all NetworkSockets. */ static NetworkReactor *current; /** * Add a NetworkSocket to our list of sockets. The desired notification states are fetched directly from the - * socket itself. + * socket itself using NetworkSocket::get_poll(), and it will be notified using NetworkSocket::notify(). * * @param socket the socket to watch */ @@ -67,8 +70,11 @@ void remove_socket (NetworkSocket *socket) { sockets.remove(socket); } /** - * Poll our sockets and drive any I/O, optionally sleeping for the given timeout. This is efficient if our - * sockets list is empty. + * Wait for activity on any of the sockets registered and with notification enabled, driving them using + * NetworkSocket::notify() if select() indicates activity. This method will sleep at most \a timeout, returning + * once there was socket activity, or the timeout ran out. + * + * This is intended to be particularly efficient if the socket list is empty. */ void poll (timeval *timeout = NULL); }; diff -r c7295b72731a -r d64bf28c4340 src/Network/Server.hh --- a/src/Network/Server.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Server.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,6 +1,12 @@ #ifndef NETWORKSERVER_HH #define NETWORKSERVER_HH +/** + * @file + * + * Game server implementation + */ + #include "../GameState.hh" #include "Session.hh" #include "Object.hh" diff -r c7295b72731a -r d64bf28c4340 src/Network/Session.hh --- a/src/Network/Session.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Session.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,6 +1,12 @@ #ifndef NETWORK_SESSION_HH #define NETWORK_SESSION_HH +/** + * @file + * + * Support for a groups of clients/servers with associated TCP/UDP sockets + */ + #include #include diff -r c7295b72731a -r d64bf28c4340 src/Network/Socket.hh --- a/src/Network/Socket.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/Socket.hh Fri Jan 16 22:03:49 2009 +0200 @@ -147,37 +147,47 @@ int get_socket (void) const { return fd; } /** - * Bind to a specific local address + * Bind to a local endpoint. This can be specified in hostname form, and a suitable socket will be chosen. */ void bind (const NetworkEndpoint &addr); /** - * Put socket into listen mode + * Put socket into listen mode for accept() */ void listen (int backlog); /** * Get local address + * + * Note that this may block on a reverse DNS lookup. */ NetworkAddress get_local_address (void); /** * Get remote address + * + * Note that this may block on a reverse DNS lookup. */ NetworkAddress get_remote_address (void); /** - * Make send/recv/connect non-blocking + * Make send/recv non-blocking. The current connect() implementation does not support use of non-blocking + * connects. */ void set_nonblocking (bool nonblocking); /** - * Accept a new connection, optionally giving the connection's source address + * Accept an incoming connection on a listen() socket as a new socket, optionally storing the connection's + * source address. + * + * Note that this may block on a reverse DNS lookup if \a src is given. */ NetworkSocket* accept (NetworkAddress *src); /** - * Establish a new connection + * Connect this socket to a remote endpoint, going through the resolved addresses until we find one that works. + * + * This is currently implemented in an entirely blocking fashion, DNS lookups and connect() included. */ void connect (const NetworkEndpoint &addr); @@ -225,24 +235,24 @@ void register_poll (void); /** - * Trigger sig_read() once socket is ready for recv? + * Trigger sig_read() once socket is ready for recv() */ void set_poll_read (bool want_read) { this->want_read = want_read; if (!registered) register_poll(); } /** - * Trigger sig_write() once socket is ready for send? + * Trigger sig_write() once socket is ready for send() */ void set_poll_write (bool want_write) { this->want_write = want_write; if (!registered) register_poll(); } /** - * What events this socket is interested in. + * What events this socket is interested in (called by NetworkReactor) */ NetworkPollMask get_poll (void) { return (want_read ? POLL_READ : 0) | (want_write ? POLL_WRITE : 0); } /** - * Notify of events + * Notify of events (called by NetworkReactor) */ void notify (NetworkPollMask mask) { if (mask & POLL_READ) _sig_read(); diff -r c7295b72731a -r d64bf28c4340 src/Network/TCP.hh --- a/src/Network/TCP.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/TCP.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,6 +1,12 @@ #ifndef NETWORK_TCP_HH #define NETWORK_TCP_HH +/** + * @file + * + * Simple message-based TCP implementation + */ + #include #include "Socket.hh" @@ -19,7 +25,12 @@ // @} /** - * A connected TCP socket, so either a client or a server-accept socket + * A connected TCP socket, so either a client or a server's accept'd socket. Can be used to send/receive messages. + * + * Not instanted directly, use NetworkTCPServer/NetworkTCPClient. + * + * Most of the functionality is present in NetworkSocket/NetworkBuffer*, so mostly this just implements the + * higher-level logic for reading messages, triggering signals, driving connect/listen and maintaing the poll flags. */ class NetworkTCPTransport { protected: @@ -120,7 +131,8 @@ public: /** - * Listen on the specific address. + * Listen on the specific endpoint for incoming client connections. \a listen_addr may be a hostname, a + * suitable address will be chosen. */ NetworkTCPServer (const NetworkEndpoint &listen_addr); @@ -158,7 +170,10 @@ class NetworkTCPClient : public NetworkTCPTransport { public: /** - * Create a NetworkTCPTransport, and then connect our socket to the given address. + * Create a NetworkTCPTransport, and then connect our socket to the given remote endpoint + * + * This is address-family-agnostic, and fully supports endpoints with multiple addresses. They will be tried in + * turn until one works. * * @param connect_addr the address to connect to */ diff -r c7295b72731a -r d64bf28c4340 src/Network/UDP.hh --- a/src/Network/UDP.hh Fri Jan 16 21:24:45 2009 +0200 +++ b/src/Network/UDP.hh Fri Jan 16 22:03:49 2009 +0200 @@ -1,6 +1,12 @@ #ifndef NETWORK_UDP_HH #define NETWORK_UDP_HH +/** + * @file + * + * UDP implementation + */ + #include "Socket.hh" #include "Address.hh" #include "Packet.hh" @@ -44,6 +50,9 @@ public: /** * Send the given packet on this UDP socket to the given destination address + * + * @return true if the packet was passed on to the socket API, false if the socket was busy and the packet was + * dropped (no chance of it arriving). */ bool sendto (const NetworkPacketBuffer &packet, const NetworkAddress &dst);