From 64881d2eca1687e7b5965008bad384e6fb5dbfb8 Mon Sep 17 00:00:00 2001 From: Bill Currie Date: Tue, 26 Jul 2011 11:29:41 +0900 Subject: [PATCH] Finish the docs for netchan. Also clean out some unnecessary declarations. --- include/netchan.h | 84 +++++++++++++++++++++++++++++++++++++++------ libs/net/net_chan.c | 42 ++++++++--------------- 2 files changed, 88 insertions(+), 38 deletions(-) diff --git a/include/netchan.h b/include/netchan.h index 5fa7e97c5..3ed79c4a6 100644 --- a/include/netchan.h +++ b/include/netchan.h @@ -41,8 +41,8 @@ \ingroup network */ //{ -#define MAX_MSGLEN 1450 // max length of a reliable message -#define MAX_DATAGRAM 1450 // max length of unreliable message +#define MAX_MSGLEN 1450 ///< max length of a reliable message +#define MAX_DATAGRAM 1450 ///< max length of unreliable message #define PORT_ANY -1 @@ -54,19 +54,17 @@ typedef struct byte ip[4]; #endif unsigned short port; - unsigned short family; // used to be pad, before IPV6 + unsigned short family; } netadr_t; +extern int net_socket; extern netadr_t net_local_adr; extern netadr_t net_loopback_adr; extern netadr_t net_from; // address of who sent the packet extern struct msg_s *net_message; -extern struct cvar_s *hostname; extern struct cvar_s *qport; -extern int net_socket; - int Net_Log_Init (const char **sound_precache); void Net_LogPrintf (const char *fmt, ...) __attribute__ ((format (printf, 1, 2))); void Log_Incoming_Packet (const byte *p, int len, int has_sequence); @@ -78,7 +76,6 @@ void Analyze_Server_Packet (const byte * data, int len, int has_sequence); extern struct cvar_s *net_packetlog; extern qboolean is_server; -qboolean ServerPaused (void); //@} /** \defgroup qw-udp QuakeWorld udp support. @@ -194,7 +191,8 @@ qboolean NET_StringToAdr (const char *s, netadr_t *a); after the retransmit has been acknowledged and the reliable still failed to get there. - If the sequence number is -1, the packet should be handled without a + If the sequence number and reliable payload bits are all 1 (32bit -1), + the packet is an out-of-band packet and should be handled without a netcon. The reliable message can be added to at any time by doing @@ -292,30 +290,96 @@ typedef struct netchan_s { /** Disable packet choking. */ -extern int net_nochoke; // don't choke packets +extern int net_nochoke; /** Disable packet sending. Used by clients in demo playback mode. */ -extern int net_blocksend; // don't send packets (used by client for demos) +extern int net_blocksend; /** Pointer to variable holding the current time in seconds. */ extern double *net_realtime; +/** Initialize the netchan system. + + Currently only sets the qport cvar default to a random value. +*/ void Netchan_Init (void); + +/** Initialize the netchan cvars. +*/ void Netchan_Init_Cvars (void); + +/** Try to send an unreliable packet to a connection. + + Handles transmission or retransmission of the reliable packet. + + 0 length will still generate a packet and deal with the reliable messages. + + \param chan The netchan representing the connection. + \param length The size of the unreliable packet. + \param data The data of the unreliable packet. +*/ void Netchan_Transmit (netchan_t *chan, int length, byte *data); + +/** Send an out-of-band packet. + + \param adr The address to which the data will be sent. + \param length The length of the data to be sent. + \param data The data to be sent. +*/ void Netchan_OutOfBand (netadr_t adr, int length, byte *data); +/** Send a formatted string as an out-of-band packet. + + \param adr The address to which the data will be sent. + \param format The printf style format string. +*/ void Netchan_OutOfBandPrint (netadr_t adr, const char *format, ...) __attribute__ ((format (printf,2,3))); + +/** Process a packet for the specifiied connection. + + Called when the current net_message is from remote_address. + Modifies net_message so that it points to the packet payload. + + \param chan The netchan representing the connection. +*/ qboolean Netchan_Process (netchan_t *chan); + +/** Initialize a new connection. + + \param chan The netchan representing the connection. + \param adr The address of the remote end of the connection. + \param qport The qport associated with the connection. + \param flags Control of the sending/reading of the qport on this + connection. +*/ void Netchan_Setup (netchan_t *chan, netadr_t adr, int qport, ncqport_e flags); +/** Check if a packet can be sent to the connection. + + \param chan The netchan representing the connection. + \return True if the connection isn't chocked. +*/ qboolean Netchan_CanPacket (netchan_t *chan); + +/** Check if a reliable packet can be sent to the connection. + + \param chan The netchan representing the connection. + \return True if there is no outstanding reliable packet and the + connection isn't chocked. +*/ qboolean Netchan_CanReliable (netchan_t *chan); +/** Send a packet. + + Very raw. Just calls NET_SendPacket(). + \param length The length of the data to be sent. + \param data The data to be sent. + \param to The address to which the data will be sent. +*/ void Netchan_SendPacket (int length, const void *data, netadr_t to); //@} diff --git a/libs/net/net_chan.c b/libs/net/net_chan.c index c50651913..e6a19b583 100644 --- a/libs/net/net_chan.c +++ b/libs/net/net_chan.c @@ -187,14 +187,6 @@ Netchan_CanReliable (netchan_t *chan) return Netchan_CanPacket (chan); } -/* - Netchan_Transmit - - tries to send an unreliable message to a connection, and handles the - transmition / retransmition of the reliable messages. - - 0 length will still generate a packet and deal with the reliable messages. -*/ void Netchan_Transmit (netchan_t *chan, int length, byte *data) { @@ -239,20 +231,20 @@ Netchan_Transmit (netchan_t *chan, int length, byte *data) MSG_WriteLong (&send, w1); MSG_WriteLong (&send, w2); - // send the qport if we are a client + /// Send the qport if appropriate (we are a client). if (chan->flags & NC_QPORT_SEND) MSG_WriteShort (&send, chan->qport); - // copy the reliable message to the packet first + /// First copy the reliable message to the packet. if (send_reliable) { SZ_Write (&send, chan->reliable_buf, chan->reliable_length); chan->last_reliable_sequence = chan->outgoing_sequence; } - // add the unreliable part if space is available + /// Then add the unreliable part if space is available. if (send.maxsize - send.cursize >= length) SZ_Write (&send, data, length); - // send the datagram + /// Send the datagram if not blocked (in demo playback mode) i = chan->outgoing_sequence & (MAX_LATENT - 1); chan->outgoing_size[i] = send.cursize; chan->outgoing_time[i] = *net_realtime; @@ -276,12 +268,6 @@ Netchan_Transmit (netchan_t *chan, int length, byte *data) chan->outgoing_sequence - chan->incoming_sequence); } -/* - Netchan_Process - - called when the current net_message is from remote_address - modifies net_message so that it points to the packet payload -*/ qboolean Netchan_Process (netchan_t *chan) { @@ -291,12 +277,12 @@ Netchan_Process (netchan_t *chan) if (!NET_CompareAdr (net_from, chan->remote_address)) return false; - // get sequence numbers + /// Get the sequence numbers. MSG_BeginReading (net_message); sequence = MSG_ReadLong (net_message); sequence_ack = MSG_ReadLong (net_message); - // read the qport if we are a server, but drop it + /// Read the qport if appropriate (we are a server), but ignore it. if (chan->flags & NC_QPORT_READ) MSG_ReadShort (net_message); @@ -337,7 +323,7 @@ Netchan_Process (netchan_t *chan) } #endif - // discard stale or duplicated packets + /// Discard stale or duplicated packets. if (sequence < (unsigned int) chan->incoming_sequence + 1) { if (showdrop->int_val) Sys_Printf ("%s:Out of order packet %i at %i\n", @@ -346,7 +332,7 @@ Netchan_Process (netchan_t *chan) return false; } - // dropped packets don't keep the message from being used + /// Dropped packets don't keep the message from being used. chan->net_drop = sequence - (chan->incoming_sequence + 1); if (chan->net_drop > 0) { chan->drop_count += 1; @@ -357,21 +343,21 @@ Netchan_Process (netchan_t *chan) sequence - (chan->incoming_sequence + 1), sequence); } - // if the current outgoing reliable message has been acknowledged - // clear the buffer to make way for the next + /// If the current outgoing reliable message has been acknowledged, + /// clear the buffer to make way for the next. if (reliable_ack == (unsigned int) chan->reliable_sequence) chan->reliable_length = 0; // it has been received - // if this message contains a reliable message, bump - // incoming_reliable_sequence + /// If this message contains a reliable message, bump + /// incoming_reliable_sequence chan->incoming_sequence = sequence; chan->incoming_acknowledged = sequence_ack; chan->incoming_reliable_acknowledged = reliable_ack; if (reliable_message) chan->incoming_reliable_sequence ^= 1; - // the message can now be read from the current message pointer - // update statistics counters + // The message can now be read from the current message pointer. + /// Update statistics counters. chan->frame_latency = chan->frame_latency * OLD_AVG + (chan->outgoing_sequence - sequence_ack) * (1.0 - OLD_AVG); chan->frame_rate = chan->frame_rate * OLD_AVG