summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorrubidium <rubidium@openttd.org>2011-05-01 13:29:40 +0000
committerrubidium <rubidium@openttd.org>2011-05-01 13:29:40 +0000
commit99ec3a044aab32e0fe4aea03a5539cf0e4f129e9 (patch)
tree8d9cdc4b81d2d7c4a9ca505656b837777e38092a /src
parent536c581923e456ed6a0d1a47747b7c9e111d8755 (diff)
downloadopenttd-99ec3a044aab32e0fe4aea03a5539cf0e4f129e9.tar.xz
(svn r22403) -Document: some more network/core code
Diffstat (limited to 'src')
-rw-r--r--src/network/core/address.h16
-rw-r--r--src/network/core/os_abstraction.h14
-rw-r--r--src/network/core/packet.cpp63
-rw-r--r--src/network/core/tcp.cpp9
-rw-r--r--src/network/core/tcp_admin.cpp4
-rw-r--r--src/network/core/tcp_admin.h3
-rw-r--r--src/network/core/tcp_content.h4
-rw-r--r--src/network/core/tcp_game.h25
-rw-r--r--src/network/core/tcp_http.cpp3
9 files changed, 115 insertions, 26 deletions
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<NetworkAddress, 4> NetworkAddressList;
-typedef SmallMap<NetworkAddress, SOCKET, 4> SocketList;
+typedef SmallVector<NetworkAddress, 4> NetworkAddressList; ///< Type for a list of addresses.
+typedef SmallMap<NetworkAddress, SOCKET, 4> 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<NetworkHTTPSocketHandler *, 1> _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