gsUdpEngine.h

#ifndef __GS_UDP_ENGINE_H__
#define __GS_UDP_ENGINE_H__

// UDP Communication Engine
//
#include "gsCommon.h"
#include "../gt2/gt2.h"
#include "../darray.h"

// Constants
 
// The UDP Engine should try the MSS (Maximum Segment Size = IP Packet size - IP Header)
// as a default size to keep the packets from being fragmented.  Currently 1460 is the
// MSS for windows.  Consoles may have a different size.
#define GS_UDP_DEFAULT_OUT_BUFFSIZE  1460
#define GS_UDP_DEFAULT_IN_BUFFSIZE 1500
 
// a default size for address strings
#define GS_IP_ADDR_AND_PORT          22
 
// A fixed header len. unless we require a bigger size, it will stay this size.
// These need to be used for calculating the free space available on
// the outgoing buffers for an IP and Port which represent the peer.
#define GS_UDP_MSG_HEADER_LEN        16
#define GS_UDP_RELIABLE_MSG_HEADER   7
 
// The following error codes will be given back to the higher level app 
// or message handler.
typedef enum _GSUdpErrorCode
{
    GS_UDP_NO_ERROR,
    GS_UDP_NO_MEMORY,
    GS_UDP_REJECTED,
    GS_UDP_NETWORK_ERROR,
    GS_UDP_ADDRESS_ERROR,
    GS_UDP_ADDRESS_ALREADY_IN_USE,
    GS_UDP_TIMED_OUT,
    GS_UDP_REMOTE_ERROR,
    GS_UDP_SEND_FAILED,
    GS_UDP_INVALID_MESSAGE,
    GS_UDP_PARAMETER_ERROR,
    GS_UDP_NOT_INITIALIZED,
    GS_UDP_MSG_TOO_BIG,
    GS_UDP_UNKNOWN_ERROR,
    // Add new errors before here
    GS_UDP_NUM_ERROR_CODES
} GSUdpErrorCode;
 
// Used so that an app or message handler does 
// not need to request to start talking to a peer twice
// Also lets higher level app or message handlers know about
// if a communication channel to a peer has been broken.
typedef enum _GSUdpPeerState
{
    GS_UDP_PEER_CONNECTING,
    GS_UDP_PEER_CONNECTED,
    GS_UDP_PEER_CLOSING,
    GS_UDP_PEER_CLOSED,
    // Add new connection state before here
    GS_UDP_PEER_STATE_NUM
} GSUdpPeerState;
 
// When a communication channel to a peer is closed
// the closed callback will let us know why it was closed
typedef enum _GSUdpCloseReason
{
    GS_UDP_CLOSED_LOCALLY,
    GS_UDP_CLOSED_REMOTELY,
    // errors:
    GS_UDP_CLOSED_BY_COMM_ERROR, // An invalid message was received (it was either unexpected or wrongly formatted).
    GS_UDP_CLOSED_BY_LOW_MEM,
    // Add new reasons before here
    GS_UDP_CLOSED_NUM
} GSUdpCloseReason;

// Callbacks
 
// Errors to give higher layers feedback
typedef void (*gsUdpErrorCallback)(GSUdpErrorCode theCode, void *theUserData);
 
 
// app Request attempt callback used to tell registered listeners about connection attempts
typedef void (*gsUdpAppConnectAttemptCallback)(unsigned int theIp, unsigned short thePort, 
                                               int theLatency, unsigned char *theInitMsg, 
                                               unsigned int theInitMsgLen, void *theUserData);
 
 
// peer communication channel callback types
typedef void (*gsUdpConnClosedCallback)(unsigned int ip, unsigned short port, GSUdpCloseReason reason, 
                                        void *theUserData);
typedef void (*gsUdpConnReceivedDataCallback)(unsigned int ip, unsigned short port, 
                                              unsigned char *message, unsigned int messageLength, 
                                              gsi_bool reliable, void *theUserData);
typedef void (*gsUdpConnConnectedCallback)(unsigned int ip, unsigned short port, 
                                           GSUdpErrorCode error, gsi_bool rejected, 
                                           void *theUserData);
typedef void (*gsUdpConnPingCallback)(unsigned int ip, unsigned short port, unsigned int latency, 
                                      void *theUserData);
 
 
// Messages that cannot be interpreted are passed on to the higher level app
typedef gsi_bool (*gsUdpUnknownMsgCallback)(unsigned int ip, unsigned short port, 
                                        unsigned char *message, unsigned int messageLength, 
                                        void *theUserData);

// Public Functionality
// Initialization and test functions
gsi_bool gsUdpEngineIsInitialized();
GSUdpErrorCode gsUdpEngineInitialize(unsigned short thePort, int theIncomingBufSize, 
                                     int theOutgoingBufSize, gsUdpErrorCallback theAppNetworkError, 
                                     gsUdpConnConnectedCallback theAppConnected,
                                     gsUdpConnClosedCallback theAppClosed,
                                     gsUdpConnPingCallback theAppPing,
                                     gsUdpConnReceivedDataCallback theAppReceive,
                                     gsUdpUnknownMsgCallback theAppUnownMsg,
                                     gsUdpAppConnectAttemptCallback theAppConnectAttempt,
                                     void *theAppUserData);
// update and shutdown 
GSUdpErrorCode gsUdpEngineThink();
GSUdpErrorCode gsUdpEngineShutdown();
 
// Connectivity functions
GSUdpErrorCode gsUdpEngineGetPeerState(unsigned int theIp, unsigned short thePort, 
                                       GSUdpPeerState *thePeerState);
GSUdpErrorCode gsUdpEngineStartTalkingToPeer(unsigned int theIp, unsigned short thePort,
                                             char theInitMsg[GS_UDP_MSG_HEADER_LEN], int timeOut);
GSUdpErrorCode gsUdpEngineAcceptPeer(unsigned int theIp, unsigned short thePort);
GSUdpErrorCode gsUdpEngineRejectPeer(unsigned int theIp, unsigned short thePort);
 
// Sending functionality
// WARNING: Messages should not be greater than the outgoing buffer size minus the header 
// and the 7 byte header for reliable messages (used for internal gt2 operations). Most
// UDP fragmentation occurs if messages are bigger than 1500 bytes.  Also, some routers are 
// known to drop those packets that are larger than 1500 bytes because of set MTU sizes.  
// The recommended outgoing buffer size is the default (1460).  So take that, and subtract 
// 16 for message handler header and reliable message header (if sending data reliably).
// freeSpace = 1460 - 16 - 7
GSUdpErrorCode gsUdpEngineSendMessage(unsigned int theIp, unsigned short thePort, 
                                      char theHeader[GS_UDP_MSG_HEADER_LEN], unsigned char *theMsg, 
                                      unsigned int theMsgLen, gsi_bool theReliable);
 
// This function should be called for those parts of the code that want specific handling of messages
// Any call to send should include the header registered here.  
GSUdpErrorCode gsUdpEngineAddMsgHandler(char theInitMsg[GS_UDP_MSG_HEADER_LEN], 
                                        char theHeader[GS_UDP_MSG_HEADER_LEN], 
                                        gsUdpErrorCallback theMsgHandlerError, 
                                        gsUdpConnConnectedCallback theMsgHandlerConnected, 
                                        gsUdpConnClosedCallback theMsgHandlerClosed, 
                                        gsUdpConnPingCallback theMsgHandlerPing,
                                        gsUdpConnReceivedDataCallback theMsgHandlerRecv,
                                        void *theUserData);
GSUdpErrorCode gsUdpEngineRemoveMsgHandler(char theHeader[GS_UDP_MSG_HEADER_LEN]);
// Public Utility functionality
SOCKET gsUdpEngineGetSocket();
void gsUdpEngineAddrToString(unsigned int theIp, unsigned short thePort, 
                             char addrstring[GS_IP_ADDR_AND_PORT]);
unsigned int gsUdpEngineGetLocalAddr();
unsigned short gsUdpEngineGetLocalPort();
 
// lets the app or message handler know if it is able to shutdown the udp layer
gsi_bool gsUdpEngineNoMoreMsgHandlers();
gsi_bool gsUdpEngineNoApp();
 
// check the remaining free space on the outgoing buffer for the peer based 
// IP and port
int gsUdpEngineGetPeerOutBufferFreeSpace(unsigned int theIp, unsigned short thePort);
 
#endif