From 99ec3a044aab32e0fe4aea03a5539cf0e4f129e9 Mon Sep 17 00:00:00 2001 From: rubidium Date: Sun, 1 May 2011 13:29:40 +0000 Subject: (svn r22403) -Document: some more network/core code --- src/network/core/address.h | 16 +++++----- src/network/core/os_abstraction.h | 14 +++++++-- src/network/core/packet.cpp | 63 ++++++++++++++++++++++++++++++++++----- src/network/core/tcp.cpp | 9 ++++-- src/network/core/tcp_admin.cpp | 4 +++ src/network/core/tcp_admin.h | 3 -- src/network/core/tcp_content.h | 4 ++- src/network/core/tcp_game.h | 25 ++++++++++++++-- src/network/core/tcp_http.cpp | 3 +- 9 files changed, 115 insertions(+), 26 deletions(-) (limited to 'src/network/core') diff --git a/src/network/core/address.h b/src/network/core/address.h index 3a23703ce..d2d43b4a9 100644 --- a/src/network/core/address.h +++ b/src/network/core/address.h @@ -20,8 +20,8 @@ #ifdef ENABLE_NETWORK class NetworkAddress; -typedef SmallVector NetworkAddressList; -typedef SmallMap SocketList; +typedef SmallVector NetworkAddressList; ///< Type for a list of addresses. +typedef SmallMap SocketList; ///< Type for a mapping between address and socket. /** * Wrapper for (un)resolved network addresses; there's no reason to transform @@ -44,8 +44,9 @@ private: SOCKET Resolve(int family, int socktype, int flags, SocketList *sockets, LoopProc func); public: /** - * Create a network address based on a resolved IP and port - * @param address the IP address with port + * Create a network address based on a resolved IP and port. + * @param address The IP address with port. + * @param address_length The length of the address. */ NetworkAddress(struct sockaddr_storage &address, int address_length) : address_length(address_length), @@ -55,8 +56,9 @@ public: } /** - * Create a network address based on a resolved IP and port - * @param address the IP address with port + * Create a network address based on a resolved IP and port. + * @param address The IP address with port. + * @param address_length The length of the address. */ NetworkAddress(sockaddr *address, int address_length) : address_length(address_length) @@ -68,7 +70,7 @@ public: /** * Create a network address based on a unresolved host and port - * @param ip the unresolved hostname + * @param hostname the unresolved hostname * @param port the port * @param family the address family */ diff --git a/src/network/core/os_abstraction.h b/src/network/core/os_abstraction.h index 1bdf942c6..133f3d958 100644 --- a/src/network/core/os_abstraction.h +++ b/src/network/core/os_abstraction.h @@ -279,6 +279,11 @@ typedef unsigned long in_addr_t; # endif #endif /* __MORPHOS__ || __AMIGA__ */ +/** + * Try to set the socket into non-blocking mode. + * @param d The socket to set the non-blocking more for. + * @return True if setting the non-blocking mode succeeded, otherwise false. + */ static inline bool SetNonBlocking(SOCKET d) { #ifdef WIN32 @@ -293,6 +298,11 @@ static inline bool SetNonBlocking(SOCKET d) #endif } +/** + * Try to set the socket to not delay sending. + * @param d The socket to disable the delaying for. + * @return True if disabling the delaying succeeded, otherwise false. + */ static inline bool SetNoDelay(SOCKET d) { /* XXX should this be done at all? */ @@ -306,8 +316,8 @@ static inline bool SetNoDelay(SOCKET d) } /* Make sure these structures have the size we expect them to be */ -assert_compile(sizeof(in_addr) == 4); -assert_compile(sizeof(in6_addr) == 16); +assert_compile(sizeof(in_addr) == 4); ///< IPv4 addresses should be 4 bytes. +assert_compile(sizeof(in6_addr) == 16); ///< IPv6 addresses should be 16 bytes. #endif /* ENABLE_NETWORK */ diff --git a/src/network/core/packet.cpp b/src/network/core/packet.cpp index cc098793b..d30ef9e5f 100644 --- a/src/network/core/packet.cpp +++ b/src/network/core/packet.cpp @@ -70,7 +70,7 @@ void Packet::PrepareToSend() this->pos = 0; // We start reading from here } -/** +/* * The next couple of functions make sure we can send * uint8, uint16, uint32 and uint64 endian-safe * over the network. The least significant bytes are @@ -82,17 +82,29 @@ void Packet::PrepareToSend() * and non-zero means true. */ +/** + * Package a boolean in the packet. + * @param data The data to send. + */ void Packet::Send_bool(bool data) { this->Send_uint8(data ? 1 : 0); } +/** + * Package a 8 bits integer in the packet. + * @param data The data to send. + */ void Packet::Send_uint8(uint8 data) { assert(this->size < SEND_MTU - sizeof(data)); this->buffer[this->size++] = data; } +/** + * Package a 16 bits integer in the packet. + * @param data The data to send. + */ void Packet::Send_uint16(uint16 data) { assert(this->size < SEND_MTU - sizeof(data)); @@ -100,6 +112,10 @@ void Packet::Send_uint16(uint16 data) this->buffer[this->size++] = GB(data, 8, 8); } +/** + * Package a 32 bits integer in the packet. + * @param data The data to send. + */ void Packet::Send_uint32(uint32 data) { assert(this->size < SEND_MTU - sizeof(data)); @@ -109,6 +125,10 @@ void Packet::Send_uint32(uint32 data) this->buffer[this->size++] = GB(data, 24, 8); } +/** + * Package a 64 bits integer in the packet. + * @param data The data to send. + */ void Packet::Send_uint64(uint64 data) { assert(this->size < SEND_MTU - sizeof(data)); @@ -123,9 +143,9 @@ void Packet::Send_uint64(uint64 data) } /** - * Sends a string over the network. It sends out - * the string + '\0'. No size-byte or something. - * @param data the string to send + * Sends a string over the network. It sends out + * the string + '\0'. No size-byte or something. + * @param data The string to send */ void Packet::Send_string(const char *data) { @@ -136,14 +156,18 @@ void Packet::Send_string(const char *data) } -/** +/* * Receiving commands * Again, the next couple of functions are endian-safe * see the comment before Send_bool for more info. */ -/** Is it safe to read from the packet, i.e. didn't we run over the buffer ? */ +/** + * Is it safe to read from the packet, i.e. didn't we run over the buffer ? + * @param bytes_to_read The amount of bytes we want to try to read. + * @return True if that is safe, otherwise false. + */ bool Packet::CanReadFromPacket(uint bytes_to_read) { /* Don't allow reading from a quit client/client who send bad data */ @@ -179,11 +203,19 @@ void Packet::PrepareToRead() this->pos = sizeof(PacketSize); } +/** + * Read a boolean from the packet. + * @return The read data. + */ bool Packet::Recv_bool() { return this->Recv_uint8() != 0; } +/** + * Read a 8 bits integer from the packet. + * @return The read data. + */ uint8 Packet::Recv_uint8() { uint8 n; @@ -194,6 +226,10 @@ uint8 Packet::Recv_uint8() return n; } +/** + * Read a 16 bits integer from the packet. + * @return The read data. + */ uint16 Packet::Recv_uint16() { uint16 n; @@ -205,6 +241,10 @@ uint16 Packet::Recv_uint16() return n; } +/** + * Read a 32 bits integer from the packet. + * @return The read data. + */ uint32 Packet::Recv_uint32() { uint32 n; @@ -218,6 +258,10 @@ uint32 Packet::Recv_uint32() return n; } +/** + * Read a 64 bits integer from the packet. + * @return The read data. + */ uint64 Packet::Recv_uint64() { uint64 n; @@ -235,7 +279,12 @@ uint64 Packet::Recv_uint64() return n; } -/** Reads a string till it finds a '\0' in the stream */ +/** + * Reads a string till it finds a '\0' in the stream. + * @param buffer The buffer to put the data into. + * @param size The size of the buffer. + * @param allow_newlines Whether the string validation should remove newlines. + */ void Packet::Recv_string(char *buffer, size_t size, bool allow_newlines) { PacketSize pos; diff --git a/src/network/core/tcp.cpp b/src/network/core/tcp.cpp index 9a6704006..8cfa2d60e 100644 --- a/src/network/core/tcp.cpp +++ b/src/network/core/tcp.cpp @@ -18,6 +18,10 @@ #include "tcp.h" +/** + * Construct a socket handler for a TCP connection. + * @param s The just opened TCP connection. + */ NetworkTCPSocketHandler::NetworkTCPSocketHandler(SOCKET s) : NetworkSocketHandler(), packet_queue(NULL), packet_recv(NULL), @@ -138,8 +142,7 @@ SendPacketsState NetworkTCPSocketHandler::SendPackets(bool closing_down) /** * Receives a packet for the given client - * @param status the variable to store the status into - * @return the received packet (or NULL when it didn't receive one) + * @return The received packet (or NULL when it didn't receive one) */ Packet *NetworkTCPSocketHandler::ReceivePacket() { @@ -219,7 +222,7 @@ Packet *NetworkTCPSocketHandler::ReceivePacket() /** * Check whether this socket can send or receive something. * @return \c true when there is something to receive. - * @note Sets #writeable if more data can be sent. + * @note Sets #writable if more data can be sent. */ bool NetworkTCPSocketHandler::CanSendReceive() { diff --git a/src/network/core/tcp_admin.cpp b/src/network/core/tcp_admin.cpp index f7d982825..077ac3048 100644 --- a/src/network/core/tcp_admin.cpp +++ b/src/network/core/tcp_admin.cpp @@ -19,6 +19,10 @@ #include "tcp_admin.h" #include "../../debug.h" +/** + * Create the admin handler for the given socket. + * @param s The socket to communicate over. + */ NetworkAdminSocketHandler::NetworkAdminSocketHandler(SOCKET s) { this->sock = s; diff --git a/src/network/core/tcp_admin.h b/src/network/core/tcp_admin.h index cb3ff8e5b..0e0206644 100644 --- a/src/network/core/tcp_admin.h +++ b/src/network/core/tcp_admin.h @@ -448,9 +448,6 @@ public: ~NetworkAdminSocketHandler(); NetworkRecvStatus ReceivePackets(); - - const char *ReceiveCommand(Packet *p, struct CommandPacket *cp); - void SendCommand(Packet *p, const struct CommandPacket *cp); }; #endif /* ENABLE_NETWORK */ diff --git a/src/network/core/tcp_content.h b/src/network/core/tcp_content.h index 120324d48..396202f23 100644 --- a/src/network/core/tcp_content.h +++ b/src/network/core/tcp_content.h @@ -47,12 +47,14 @@ enum PacketContentType { PACKET_CONTENT_END ///< Must ALWAYS be on the end of this list!! (period) }; +/** Unique identifier for the content. */ enum ContentID { - INVALID_CONTENT_ID = UINT32_MAX + INVALID_CONTENT_ID = UINT32_MAX ///< Sentinel for invalid content. }; /** Container for all important information about a piece of content. */ struct ContentInfo { + /** The state the content can be in. */ enum State { UNSELECTED, ///< The content has not been selected SELECTED, ///< The content has been manually selected diff --git a/src/network/core/tcp_game.h b/src/network/core/tcp_game.h index afa2879cb..53d6df892 100644 --- a/src/network/core/tcp_game.h +++ b/src/network/core/tcp_game.h @@ -525,11 +525,32 @@ public: uint last_packet; ///< Time we received the last frame. NetworkRecvStatus CloseConnection(bool error = true); + + /** + * Close the network connection due to the given status. + * @param status The reason the connection got closed. + */ virtual NetworkRecvStatus CloseConnection(NetworkRecvStatus status) = 0; virtual ~NetworkGameSocketHandler() {} - inline void SetInfo(NetworkClientInfo *info) { assert(info != NULL && this->info == NULL); this->info = info; } - inline NetworkClientInfo *GetInfo() const { return this->info; } + /** + * Sets the client info for this socket handler. + * @param info The new client info. + */ + inline void SetInfo(NetworkClientInfo *info) + { + assert(info != NULL && this->info == NULL); + this->info = info; + } + + /** + * Gets the client info of this socket handler. + * @return The client info. + */ + inline NetworkClientInfo *GetInfo() const + { + return this->info; + } NetworkRecvStatus ReceivePackets(); diff --git a/src/network/core/tcp_http.cpp b/src/network/core/tcp_http.cpp index a29d6a56e..0bf733462 100644 --- a/src/network/core/tcp_http.cpp +++ b/src/network/core/tcp_http.cpp @@ -25,8 +25,9 @@ static SmallVector _http_connections; /** * Start the querying - * @param sock the socket of this connection + * @param s the socket of this connection * @param callback the callback for HTTP retrieval + * @param host the hostname of the server to connect to * @param url the url at the server * @param data the data to send * @param depth the depth (redirect recursion) of the queries -- cgit v1.2.3-70-g09d2