pinger.h

/*
GameSpy Ping SDK 
Dan "Mr. Pants" Schoenblum
dan@gamespy.com
 
Copyright 1999-2007 GameSpy Industries, Inc
 
devsupport@gamespy.com
*/
 
#ifndef _PINGER_H_
#define _PINGER_H_
 
#include "../common/gsCommon.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/************
** DEFINES **
************/
// This controls the size of UDP pings.
// The protocol takes up 8 of these bytes.
// The rest can be used by the app.
#ifndef PINGER_UDP_PING_SIZE
#define PINGER_UDP_PING_SIZE     32
#endif
 
// Value for ping if a ping timed-out.
#define PINGER_TIMEOUT           -1
 
/**********
** TYPES **
**********/
typedef enum { PINGERFalse, PINGERTrue } PINGERBool;
 
/**************
** CALLBACKS **
**************/
// A function of this type is used as:
// a param to pingerInit, gets called when an uninitiated UDP ping is received
// a param to pingerPing, gets called when the ping is completed, or times out
// if the ping times out, ping is PINGER_TIMEOUT
// IP and port are in network byte order
typedef void (* pingerGotPing)(unsigned int IP,
                               unsigned short port,
                               int ping,
                               const char * data,
                               int len,
                               void * param);
 
// When a ping is sent, this callback gets called so that
// the application can use the ping bytes not being used
// by the protocol.
// The application can write up to len bytes to data.
// IP and port are in network byte order.
typedef void (* pingerSetData)(unsigned int IP,
                               unsigned short port,
                               char * data,
                               int len,
                               void * param);
 
/**************
** FUNCTIONS **
**************/
 
// Called once to initialize the pinger library.
// localPort is in host byte order
// localAddress=NULL : don't specify a local interface
// localPort=0 : not doing UDP pings
PINGERBool pingerInit(const char * localAddress,
                      unsigned short localPort,
                      pingerGotPing pinged,
                      void * pingedParam,
                      pingerSetData setData,
                      void * setDataParam);
 
// Called to clean-up when done with pinger.
void pingerShutdown(void);
 
// Called to do processing.
// The more frequently this function is called,
// the more accurate the pings will be.
//
// Example: if this func is called once every 20ms, and a ping
// is returned as 100ms, then the ping is in the range 90-110.
void pingerThink(void);
 
// Does a ping.  If blocking, does not return until the ping is completed.
// timeout specifes how long (in milliseconds) to wait for the ping reply.
// A value of 0 means wait forever.  Note, this is dangerous because pings
// are not reliable.  A blocking ping with a 0 timeout will never return if
// the ping is lost.
// port=0 : ICMP ping (this is NOT currently supported)
// port!=0 : UDP ping
// IP and port are in network byte order
void pingerPing(unsigned int IP,
                unsigned short port,
                pingerGotPing reply,
                void * replyParam,
                PINGERBool blocking,
                gsi_time timeout);
    
#ifdef __cplusplus
}
#endif
 
#endif