openmohaa/code/gamespy/Peer/peer.h

 /*
GameSpy Peer SDK 
Dan "Mr. Pants" Schoenblum
dan@gamespy.com

Copyright 1999-2007 GameSpy Industries, Inc

devsupport@gamespy.com
*/

#ifndef _PEER_H_
#define _PEER_H_

/*************
** INCLUDES **
*************/
#include "../common/gsCommon.h"
#include "../Chat/chat.h"
#include "../qr2/qr2.h"
#include "../serverbrowsing/sb_internal.h"

#ifdef __cplusplus
extern "C" {
#endif

/************
** DEFINES **
************/
// Defines for the msg param that's passed into peerListingGamesCallback().
// PANTS-04.20.00-changed from PI_* to PEER_*
// PANTS-09.26.02-added PEER_COMPLETE
///////////////////////////////////////////////////////////////////////////
#define PEER_ADD        0  // a server is being added
#define PEER_UPDATE     1  // a server has been updated
#define PEER_REMOVE     2  // a server has been removed
#define PEER_CLEAR      3  // all the servers have been cleared
#define PEER_COMPLETE   4  // the initial listing of servers is complete

// Nick errors, for peerNickErrorCallback.
//////////////////////////////////////////
#define PEER_NICK_OK                0
#define PEER_IN_USE                 1  // the nick is already being used
#define PEER_INVALID                2  // the nick contains invalid characters
#define PEER_UNIQUENICK_EXPIRED     3  // the uniquenick for this account has expired
#define PEER_NO_UNIQUENICK          4  // there is no uniquenick for this account
#define PEER_INVALID_UNIQUENICK     5  // the uniquenick to associate with the account is invalid or in use
#define PEER_NICK_TOO_LONG          6  // the nick was too long 
	
// Possible values for the failureReason passed to the peerConnectCallback.
///////////////////////////////////////////////////////////////////////////
#define PEER_DISCONNECTED           0  // disconnected from, or unable to connect to, the server
#define PEER_NICK_ERROR             1  // a nick error was either ignored or not handled
#define PEER_LOGIN_FAILED           2  // the login info passed to peerConnectLogin was not valid

// Maximum length of a room password, including the terminating NUL.
////////////////////////////////////////////////////////////////////
#define PEER_PASSWORD_LEN     24

// Each player can have various flags set for each room they are in.
////////////////////////////////////////////////////////////////////
#define PEER_FLAG_STAGING     0x01  // s
#define PEER_FLAG_READY       0x02  // r
#define PEER_FLAG_PLAYING     0x04  // g
#define PEER_FLAG_AWAY        0x08  // a
#define PEER_FLAG_HOST        0x10  // h
#define PEER_FLAG_OP          0x20
#define PEER_FLAG_VOICE       0x40

// Bitfield reporting options for peerStartGame.
////////////////////////////////////////////////
#define PEER_KEEP_REPORTING      0  // Continue reporting.
#define PEER_STOP_REPORTING      1  // Stop reporting.  Cannot be used with other options.
#define PEER_REPORT_INFO         2  // Continue reporting server keys (as if it were not playing).
#define PEER_REPORT_PLAYERS      4  // Continue reporting player keys (as if it were not playing).

/**********
** TYPES **
**********/
// The peer object.
///////////////////
typedef void * PEER;

// Boolean.
///////////
typedef enum
{
	PEERFalse,
	PEERTrue
} PEERBool;

// Types of rooms.
//////////////////
typedef enum
{
	TitleRoom,  // The main room for a game.
	GroupRoom,  // A room which is, in general, for a particular type of gameplay (team, dm, etc.).
	StagingRoom,  // A room where players meet before starting a game.
	NumRooms
} RoomType;

// Types of messages. These have the same
// values as their CHAT SDK counterparts.
// PANTS-01.08.01
/////////////////////////////////////////
typedef enum
{
	NormalMessage,
	ActionMessage,
	NoticeMessage
} MessageType;

// Possible results when attempting to join a room.
// Passed into peerJoinRoomCallback().
///////////////////////////////////////////////////
typedef enum
{
	PEERJoinSuccess,     // The room was joined.

	PEERFullRoom,        // The room is full.
	PEERInviteOnlyRoom,  // The room is invite only.
	PEERBannedFromRoom,  // The local user is banned from the room.
	PEERBadPassword,     // An incorrect password (or none) was given for a passworded room.

	PEERAlreadyInRoom,   // The local user is already in or entering a room of the same type.
	PEERNoTitleSet,      // Can't join a room if no title is set.
	PEERNoConnection,    // Can't join a room if there's no chat connection.
	PEERAutoMatching,    // The user can't join a staging room during an auto match attempt.

	PEERJoinFailed       // Generic failure.
} PEERJoinResult;

// Possible status values passed to the peerAutoMatchStatusCallback.
// If PEERFailed, the match failed, otherwise this is the current status
// of the automatch attempt.
////////////////////////////////////////////////////////////////////////
typedef enum
{
	PEERFailed,      // The automatch attempt failed.

	PEERSearching,   // Searching for a match (active).
	PEERWaiting,     // Waiting for a match (passive).
	PEERStaging,     // In a staging room with at least one other player, possibly waiting for more.
	PEERReady,       // All players are in the staging room, the game is ready to be launched.
	PEERComplete     // The game is launching, the automatch attempt is now complete.
	                 // The player is still in the staging room.
} PEERAutoMatchStatus;

/**************
** CALLBACKS **
**************/
// Called when the connection to the server gets disconnected.
//////////////////////////////////////////////////////////////
typedef void (* peerDisconnectedCallback)
(
	PEER peer,  // The peer object.
	const gsi_char * reason,  // The reason for the disconnection.
	void * param  // User-data.
);

// Called when a message is sent to a room the local player is in.
//////////////////////////////////////////////////////////////////
typedef void (* peerRoomMessageCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room that the message was in.
	const gsi_char * nick,  // The nick of the player who sent the message.
	const gsi_char * message,  // The text of the message.
	MessageType messageType,  // The type of message.
	void * param  // User-data.
);

// Called when a UTM is sent to a room the local player is in.
//////////////////////////////////////////////////////////////
typedef void (* peerRoomUTMCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room that the UTM was in.
	const gsi_char * nick,  // The nick of the player who sent the UTM.
	const gsi_char * command, // The UTM command for this message.
	const gsi_char * parameters,  // Any parameters for this UTM.
	PEERBool authenticated,  // True if this has been authenticated by the server.
	void * param  // User-data.
);

// Called when the name of a room the player is in changes.
// The new name can be checked with peerGetRoomName.
// PANTS|09.11.00
///////////////////////////////////////////////////////////
typedef void (* peerRoomNameChangedCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room that the name changed in.
	void * param  // User-data
);

// Called when a room's mode changes.
// PANTS|04.17.00
///////////////////////////////////////////////////////////
typedef void (* peerRoomModeChangedCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room that the name changed in.
	CHATChannelMode * mode,  // The current mode for this room.
	void * param  // User-data
);

// Called when a private message is received from another player.
/////////////////////////////////////////////////////////////////
typedef void (* peerPlayerMessageCallback)
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The nick of the player who sent the message.
	const gsi_char * message,  // The text of the message.
	MessageType messageType,  // The type of message.
	void * param  // User-data
);

// Called when a private UTM is received from another player.
/////////////////////////////////////////////////////////////
typedef void (* peerPlayerUTMCallback)
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The nick of the player who sent the UTM.
	const gsi_char * command, // The UTM command for this message.
	const gsi_char * parameters,  // Any parameters for this UTM.
	PEERBool authenticated,  // True if this has been authenticated by the server.
	void * param  // User-data
);

// Called when a player's ready state changes,
// from a call to peerSetReady().
//////////////////////////////////////////////
typedef void (* peerReadyChangedCallback)
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The nick of the player who's ready state changed.
	PEERBool ready,  // The player's new ready state.
	void * param  // User-data.
);

// Called when the host of a staging room launches the game,
// with a call to peerStartGame().
// The public and private IPs and ports of the server can
// be obtained from the server object.
////////////////////////////////////////////////////////////
typedef void (* peerGameStartedCallback)
(
	PEER peer,  // The peer object.
	SBServer server,  // A server object representing this host.
	const gsi_char * message,  // A message that was passed into peerStartGame().
	void * param  // User-data.
);

// A player joined a room.
//////////////////////////
typedef void (* peerPlayerJoinedCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room that the player joined.
	const gsi_char * nick,  // The nick of the player that joined.
	void * param  // User-data.
);

// A player left a room.
////////////////////////
typedef void (* peerPlayerLeftCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room that the player left.
	const gsi_char * nick,  // The nick of the player that left.
	const gsi_char * reason,  // The reason the player left.
	void * param  // User-data.
);

// The local player was kicked from a room.
///////////////////////////////////////////
typedef void (* peerKickedCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room that the player was kicked from.
	const gsi_char * nick,  // The nick of the player that did the kicking.
	const gsi_char * reason,  // An optional reason for the kick.
	void * param  // User-data.
);

// The entire player list for this room has been updated.
/////////////////////////////////////////////////////////
typedef void (* peerNewPlayerListCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room.
	void * param  // User-data
);

// A player in one of the rooms changed his nick.
/////////////////////////////////////////////////
typedef void (* peerPlayerChangedNickCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of the room the nick changed was in.
	const gsi_char * oldNick,  // The player's old nick.
	const gsi_char * newNick,  // The player's new nick.
	void * param  // User-data.
);

// The IP and ProfileID for this player has just been received.
// PANTS|01.08.01
// This gets called for all players (who are using peer) in a room
// shortly after joining.  It will be called with nick==NULL after
// getting info for all the players.
//////////////////////////////////////////////////////////////////
typedef void (* peerPlayerInfoCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room the info was gotten in.
	const gsi_char * nick,  // The nick of the player the info is for.
	unsigned int IP,  // The player's IP.
	int profileID,  // The player's profile ID.
	void * param  // User-data.
);

// This gets called when a player's flags have changed.
///////////////////////////////////////////////////////
typedef void (* peerPlayerFlagsChangedCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room the flags were changed in.
	const gsi_char * nick,  // The player whose flags have changed.
	int oldFlags,  // The player's old flags.
	int newFlags,  // The player's new flags.
	void * param  // User-data
);

// An updated ping for a player, who may be in any room(s).
///////////////////////////////////////////////////////////
typedef void (* peerPingCallback)
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The other player's nick.
	int ping,  // The ping.
	void * param  // User-data.
);

// An updated cross-ping between two players in the staging room.
/////////////////////////////////////////////////////////////////
typedef void (* peerCrossPingCallback)
(
	PEER peer,  // The peer object.
	const gsi_char * nick1,  // The first player's nick.
	const gsi_char * nick2,  // The second player's nick.
	int crossPing,  // The cross-ping.
	void * param  // User-data.
);

// This is called for watch keys when a room is joined, for
// watch keys when another player joins, and for any newly 
// set watch keys.
///////////////////////////////////////////////////////////
typedef void (* peerGlobalKeyChangedCallback)
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The player whose key changed.
	const gsi_char * key,  // The key.
	const gsi_char * value,  // The value.
	void * param  // User-data.
);

// This is called for watch keys when a room is joined, for
// watch keys when another player joins, for any newly 
// set watch keys, and when a broadcast key is changed.
///////////////////////////////////////////////////////////
typedef void (* peerRoomKeyChangedCallback)
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room the player is in.
	const gsi_char * nick,  // The player whose key changed.
	const gsi_char * key,  // The key.
	const gsi_char * value,  // The value.
	void * param  // User-data.
);

// Called to report QR server keys.
// Use qr2_buffer_add or qr2_buffer_add_int to
// add this key's information to the buffer.
//////////////////////////////////////////////
typedef void (* peerQRServerKeyCallback)
(
	PEER peer,  // The peer object.
	int key,  // The key for which to report information.
	qr2_buffer_t buffer,  // Fill in the information using this buffer.
	void * param  // User-data.
);

// Called to report QR player keys.
// Use qr2_buffer_add or qr2_buffer_add_int to
// add this key's information to the buffer.
//////////////////////////////////////////////
typedef void (* peerQRPlayerKeyCallback)
(
	PEER peer,  // The peer object.
	int key,  // The key for which to report information.
	int index,  // The index of the player for which to report info.
	qr2_buffer_t buffer,  // Fill in the information using this buffer.
	void * param  // User-data.
);

// Called to report QR team keys.
// Use qr2_buffer_add or qr2_buffer_add_int to
// add this key's information to the buffer.
//////////////////////////////////////////////
typedef void (* peerQRTeamKeyCallback)
(
	PEER peer,  // The peer object.
	int key,  // The key for which to report information.
	int index,  // The index of the team for which to report info.
	qr2_buffer_t buffer,  // Fill in the information using this buffer.
	void * param  // User-data.
);

// Called to get a list of keys to be reported.
// Use qr2_keybuffer_add() to add keys.
// The following keys do not need to be added, as peer already adds them:
// GAMENAME_KEY, HOSTNAME_KEY, NUMPLAYERS_KEY, MAXPLAYERS_KEY,
// GAMEMODE_KEY, PASSWORD_KEY, GROUPID_KEY, PLAYER__KEY, PING__KEY.
/////////////////////////////////////////////////////////////////////////
typedef void (* peerQRKeyListCallback)
(
	PEER peer,  // The peer object.
	qr2_key_type type,  // The type of keys being asked for (key_server, key_player, or key_team).
	qr2_keybuffer_t keyBuffer,  // Fill in the keys using this buffer.
	void * param  // User-data.
);

// Called to get a count of the number of players or teams.
///////////////////////////////////////////////////////////
typedef int (* peerQRCountCallback)
(
	PEER peer,  // The peer object.
	qr2_key_type type,  // The type of count to return (key_player or key_team).
	void * param  // User-data.
);

// Called when there is an error reporting the server.
//////////////////////////////////////////////////////
typedef void (* peerQRAddErrorCallback)
(
	PEER peer,  // The peer object.
	qr2_error_t error,  // The type of error.
	gsi_char * errorString,  // A text string containing the error.
	void * param  // User-data.
);

// Called when hosting a server and a nat-negotiate cookie is received.
///////////////////////////////////////////////////////////////////////
typedef void (* peerQRNatNegotiateCallback)
(
	PEER peer,  // The peer object.
	int cookie,  // A cookie sent from a potential client.
	void * param  // User-data.
);

// Called when hosting a server with the server's public reporting address.
///////////////////////////////////////////////////////////////////////////
typedef void (* peerQRPublicAddressCallback)
(
	PEER peer,  // The peer object.
	unsigned int ip,  // The public reporting IP
	unsigned short port,  // The public reporting port
	void * param  // User-data.
);

// This struct gets passed into peerInitialize().
// param will be passed as the last parameter to each of the callbacks.
///////////////////////////////////////////////////////////////////////
typedef struct PEERCallbacks
{
	peerDisconnectedCallback disconnected;
	peerRoomMessageCallback roomMessage;
	peerRoomUTMCallback roomUTM;
	peerRoomNameChangedCallback roomNameChanged;  // PANTS|09.11.00
	peerRoomModeChangedCallback roomModeChanged;  // PANTS|04.17.01
	peerPlayerMessageCallback playerMessage;
	peerPlayerUTMCallback playerUTM;
	peerReadyChangedCallback readyChanged;
	peerGameStartedCallback gameStarted;
	peerPlayerJoinedCallback playerJoined;
	peerPlayerLeftCallback playerLeft;
	peerKickedCallback kicked;
	peerNewPlayerListCallback newPlayerList;
	peerPlayerChangedNickCallback playerChangedNick;
	peerPlayerInfoCallback playerInfo;  // PANTS|01.08.01
	peerPlayerFlagsChangedCallback playerFlagsChanged;  // PANTS|03.12.01
	peerPingCallback ping;
	peerCrossPingCallback crossPing;
	peerGlobalKeyChangedCallback globalKeyChanged;
	peerRoomKeyChangedCallback roomKeyChanged;
	peerQRServerKeyCallback qrServerKey;
	peerQRPlayerKeyCallback qrPlayerKey;
	peerQRTeamKeyCallback qrTeamKey;
	peerQRKeyListCallback qrKeyList;
	peerQRCountCallback qrCount;
	peerQRAddErrorCallback qrAddError;
	peerQRNatNegotiateCallback qrNatNegotiateCallback;
	peerQRPublicAddressCallback qrPublicAddressCallback;
	void * param;
} PEERCallbacks;

/************
** UNICODE **
************/
#ifndef GSI_UNICODE
#define peerConnect					peerConnectA
#define peerConnectLogin            peerConnectLoginA
#define peerConnectPreAuth          peerConnectPreAuthA
#define peerRetryWithNick			peerRetryWithNickA
#define peerRegisterUniqueNick      peerRegisterUniqueNickA
#define peerSetTitle				peerSetTitleA
#define peerGetTitle				peerGetTitleA
#define peerGetNick					peerGetNickA
#define peerFixNick                 peerFixNickA
#define peerTranslateNick           peerTranslateNickA
#define peerChangeNick				peerChangeNickA
#define peerSetAwayMode				peerSetAwayModeA
#define peerParseQuery				peerParseQueryA
#define peerAuthenticateCDKey		peerAuthenticateCDKeyA
#define peerJoinTitleRoom			peerJoinTitleRoomA
#define peerJoinStagingRoom			peerJoinStagingRoomA
#define peerJoinStagingRoomByChannel	peerJoinStagingRoomByChannelA
#define peerCreateStagingRoom		peerCreateStagingRoomA
#define peerCreateStagingRoomWithSocket	peerCreateStagingRoomWithSocketA
#define peerLeaveRoom				peerLeaveRoomA
#define peerListGroupRooms			peerListGroupRoomsA
#define peerStartListingGames		peerStartListingGamesA
#define peerMessageRoom				peerMessageRoomA
#define peerUTMRoom					peerUTMRoomA
#define peerSetPassword				peerSetPasswordA
#define peerSetRoomName				peerSetRoomNameA
#define peerGetRoomName				peerGetRoomNameA
#define peerGetRoomChannel			peerGetRoomChannelA
#define peerSetTitleRoomChannel		peerSetTitleRoomChannelA
#define peerMessagePlayer			peerMessagePlayerA
#define peerUTMPlayer				peerUTMPlayerA
#define peerKickPlayer				peerKickPlayerA
#define peerGetPlayerPing			peerGetPlayerPingA
#define peerGetPlayersCrossPing		peerGetPlayersCrossPingA
#define peerPingPlayer				peerPingPlayerA 
#define peerGetPlayerInfoNoWait		peerGetPlayerInfoNoWaitA
#define peerGetPlayerInfo			peerGetPlayerInfoA
#define peerGetPlayerProfileID		peerGetPlayerProfileIDA
#define peerGetPlayerIP				peerGetPlayerIPA
#define peerIsPlayerHost			peerIsPlayerHostA
#define peerGetPlayerFlags			peerGetPlayerFlagsA
#define peerGetReady				peerGetReadyA
#define peerStartGame				peerStartGameA
#define peerSetGlobalKeys			peerSetGlobalKeysA
#define peerGetPlayerGlobalKeys		peerGetPlayerGlobalKeysA
#define peerGetRoomGlobalKeys		peerGetRoomGlobalKeysA
#define peerSetRoomKeys				peerSetRoomKeysA
#define peerGetRoomKeys				peerGetRoomKeysA
#define peerSetGlobalWatchKeys		peerSetGlobalWatchKeysA
#define peerSetRoomWatchKeys		peerSetRoomWatchKeysA
#define peerGetGlobalWatchKey		peerGetGlobalWatchKeyA
#define peerGetRoomWatchKey			peerGetRoomWatchKeyA
#define peerStartAutoMatch			peerStartAutoMatchA
#define peerStartAutoMatchWithSocket	peerStartAutoMatchWithSocketA
#else
#define peerConnect					peerConnectW
#define peerConnectLogin            peerConnectLoginW
#define peerConnectPreAuth          peerConnectPreAuthW
#define peerRetryWithNick			peerRetryWithNickW
#define peerRegisterUniqueNick      peerRegisterUniqueNickW
#define peerSetTitle				peerSetTitleW
#define peerGetTitle				peerGetTitleW
#define peerGetNick					peerGetNickW
#define peerFixNick                 peerFixNickW
#define peerTranslateNick           peerTranslateNickW
#define peerChangeNick				peerChangeNickW
#define peerSetAwayMode				peerSetAwayModeW
#define peerParseQuery				peerParseQueryA
#define peerAuthenticateCDKey		peerAuthenticateCDKeyW
#define peerJoinTitleRoom			peerJoinTitleRoomW
#define peerJoinStagingRoom			peerJoinStagingRoomW
#define peerJoinStagingRoomByChannel	peerJoinStagingRoomByChannelW
#define peerCreateStagingRoom		peerCreateStagingRoomW
#define peerCreateStagingRoomWithSocket	peerCreateStagingRoomWithSocketW
#define peerLeaveRoom				peerLeaveRoomW
#define peerListGroupRooms			peerListGroupRoomsW
#define peerStartListingGames		peerStartListingGamesW
#define peerMessageRoom				peerMessageRoomW
#define peerUTMRoom					peerUTMRoomW
#define peerSetPassword				peerSetPasswordW
#define peerSetRoomName				peerSetRoomNameW
#define peerGetRoomName				peerGetRoomNameW
#define peerGetRoomChannel			peerGetRoomChannelW
#define peerSetTitleRoomChannel		peerSetTitleRoomChannelW
#define peerMessagePlayer			peerMessagePlayerW
#define peerUTMPlayer				peerUTMPlayerW
#define peerKickPlayer				peerKickPlayerW
#define peerGetPlayerPing			peerGetPlayerPingW
#define peerGetPlayersCrossPing		peerGetPlayersCrossPingW
#define peerPingPlayer				peerPingPlayerW
#define peerGetPlayerInfoNoWait		peerGetPlayerInfoNoWaitW
#define peerGetPlayerInfo			peerGetPlayerInfoW
#define peerGetPlayerProfileID		peerGetPlayerProfileIDW
#define peerGetPlayerIP				peerGetPlayerIPW
#define peerIsPlayerHost			peerIsPlayerHostW
#define peerGetPlayerFlags			peerGetPlayerFlagsW
#define peerGetReady				peerGetReadyW
#define peerStartGame				peerStartGameW
#define peerSetGlobalKeys			peerSetGlobalKeysW
#define peerGetPlayerGlobalKeys		peerGetPlayerGlobalKeysW
#define peerGetRoomGlobalKeys		peerGetRoomGlobalKeysW
#define peerSetRoomKeys				peerSetRoomKeysW
#define peerGetRoomKeys				peerGetRoomKeysW
#define peerSetGlobalWatchKeys		peerSetGlobalWatchKeysW
#define peerSetRoomWatchKeys		peerSetRoomWatchKeysW
#define peerGetGlobalWatchKey		peerGetGlobalWatchKeyW
#define peerGetRoomWatchKey			peerGetRoomWatchKeyW
#define peerStartAutoMatch			peerStartAutoMatchW
#define peerStartAutoMatchWithSocket	peerStartAutoMatchWithSocketW
#endif

/************
** GENERAL **
************/
// This creates and intializes a peer object.
// NULL is returned in case of an error, otherwise a peer
// object is returned.
// If a peer object is returned, peerShutdown() must be called
// to cleanup the object
///////////////////////////////////////////////////////////////
PEER peerInitialize
(
	PEERCallbacks * callbacks  // Global callbacks.
);

// This gets called when the connection attempt finishes.
/////////////////////////////////////////////////////////
typedef void (* peerConnectCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // PEERTrue if success, PEERFalse if failure.
	int failureReason,  // If failure, the reason for it (PEER_DISCONNECTED, etc.)
	void * param  // User-data.
);

// This gets called if there is an error with
//   the nickname while connecting.
// Call peerRetryWithNick() to try another nick.  If it
//   is called with a NULL nick, then the connect will be
//   stopped, and peerConnectCallback will be called with
//   failure.
// The suggested nicks are only provided if type
//   is PEER_INVALID_UNIQUENICK.
/////////////////////////////////////////////////////////
typedef void (* peerNickErrorCallback)
(
	PEER peer,  // The peer object.
	int type,  // The type of nick error (PEER_IN_USE, PEER_INVALID, etc.)
	const gsi_char * nick,  // The bad nick.
	int numSuggestedNicks,  // The number of suggested nicks.
	const gsi_char ** suggestedNicks,  // The array of nicks.
	void * param  // User-data.
);

// This connects a peer object to a chat server.
// Call peerDisconnect() to close the connection.
// A title must be set with peerSetTitle before connecting.
///////////////////////////////////////////////////////////
void peerConnect
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The nick to connect with.
	int profileID,  // The profileID, or 0 if no profileID.
	peerNickErrorCallback nickErrorCallback,  // Called if nick error.
	peerConnectCallback connectCallback,  // Called on complete.
	void * param,  // User-data.
	PEERBool blocking   // If PEERTrue, don't return until finished.
);

// Same as peerConnect, but also authenticates using a uniquenick
// and password or an email, profilenick, and password.
/////////////////////////////////////////////////////////////////
void peerConnectLogin
(
	PEER peer,  // The peer object.
	int namespaceID,  // The namespace in which to login.
	const gsi_char * email,  // The email to login with.
	const gsi_char * profilenick,  // The profile to login with.
	const gsi_char * uniquenick,  // The uniquenick to login with.
	const gsi_char * password,  // The password for the login account.
	peerNickErrorCallback nickErrorCallback,  // Called if nick error.
	peerConnectCallback connectCallback,  // Called on complete.
	void * param,  // User-data.
	PEERBool blocking   // If PEERTrue, don't return until finished.
);

// Same as peerConnect, but also authenticates using an authtoken
// and partnerchallenge from a partner account system.
/////////////////////////////////////////////////////////////////
void peerConnectPreAuth
(
	PEER peer,  // The peer object.
	const gsi_char * authtoken,  // The authtoken for this login.
	const gsi_char * partnerchallenge,  // The partner challenge for this login.
	peerNickErrorCallback nickErrorCallback,  // Called if nick error.
	peerConnectCallback connectCallback,  // Called on complete.
	void * param,  // User-data.
	PEERBool blocking   // If PEERTrue, don't return until finished.
);

// If peerNickErrorCallback is called, call this to
// try and continue the connection with a new nickname.
// If there is an error with this nick, the
// peerNickErrCallback will be called again.
///////////////////////////////////////////////////////
void peerRetryWithNick
(
	PEER peer,
	const gsi_char * nick
);

// Register a uniquenick.
// Should be called in response to the peerNickErrorCallback being called
// with a type of PEER_UNIQUENICK_EXPIRED or PEER_NO_UNIQUENICK.
// If the uniquenick cannot be registered, the peerNickErrorCallback will
// be called again with a type of PEER_IN_USE or PEER_INVALID.
/////////////////////////////////////////////////////////////////////////
void peerRegisterUniqueNick
(
	PEER peer,
	int namespaceID,
	const gsi_char * uniquenick,
	const gsi_char * cdkey
);

// Returns true if peer is connected.
// PANTS|09.11.00
/////////////////////////////////////
PEERBool peerIsConnected(PEER peer);

// Sets the current title.
// A title must be set before connecting.
// Returns PEERFalse if an error, or PEERTrue if success.
// For most games the title/qrSecretKey and
// sbName/sbSecretKey pairs will be the same.
/////////////////////////////////////////////////////////
PEERBool peerSetTitle
(
	PEER peer,  // The peer object.
	const gsi_char * title,  // The title to make current (ie., ut, gmtest).
	const gsi_char * qrSecretKey,  // The queryreporting secret key.
	const gsi_char * sbName,  // The serverbrowsing name.
	const gsi_char * sbSecretKey,  // The serverbrowsing secret key.
	int sbGameVersion,  // The version of the game doing the browsing.
	int sbMaxUpdates,  // The maximum number of concurent updates (10-15 for modem users, 20-30 for high-bandwidth).
	PEERBool natNegotiate,  // PEERTrue if the title supports GameSpy's NAT-negotiation technology (or another similar technology).
	PEERBool pingRooms[NumRooms],  // To do pings int a room, set it to PEERTrue.
	PEERBool crossPingRooms[NumRooms]  // To do cross-pings in a room, set it to PEERTrue.
);

// Resets peer to no title.
///////////////////////////
void peerClearTitle(PEER peer);

// Gets the currently set title.
// Returns NULL if no title is set.
///////////////////////////////////
const gsi_char * peerGetTitle(PEER peer);

// Disconnect peer from the chat server.
////////////////////////////////////////
void peerDisconnect(PEER peer);

// Shutdown peer.
// The peer object should not be used again after this call.
////////////////////////////////////////////////////////////
void peerShutdown(PEER peer);

// Let's peer think.
// This should be called at least every ~10ms,
// typically, within the program's main loop.
//////////////////////////////////////////////
void peerThink(PEER peer);

// Get the chat object associated with this peer object.
// This returns NULL if peer isn't connected.
////////////////////////////////////////////////////////
CHAT peerGetChat(PEER peer);

// Get the local user's nickname.
/////////////////////////////////
const gsi_char * peerGetNick(PEER peer);

// Replaces any invalid characters in nick with underscores.
////////////////////////////////////////////////////////////
void peerFixNick
(
	gsi_char * newNick,
	const gsi_char * oldNick
);

// Removes the namespace extension from a chat unique nick.
// Returns the nick if it ended with the extension.
// Otherwise returns NULL.
///////////////////////////////////////////////////////////
const gsi_char * peerTranslateNick
(
	gsi_char * nick,  // The nick to translate
	const gsi_char * extension  // The extension to be removed.
);

// Gets the local IP address.  If called before
// the peer object is connected, will return 0.
// DEPRECATED - Use peerGetPublicIP.
///////////////////////////////////////////////
#define peerGetLocalIP  peerGetPublicIP

// Gets the local public IP address.  If called before
// the peer object is connected, will return 0.
//////////////////////////////////////////////////////
unsigned int peerGetPublicIP(PEER peer);

// Gets the local private IP address.
/////////////////////////////////////
unsigned int peerGetPrivateIP(PEER peer);

// Gets the local userID.
// Only valid if connected with peerConnectLogin or peerConnectPreAuth.
///////////////////////////////////////////////////////////////////////
int peerGetUserID(PEER peer);

// Gets the local profileID.
// Only valid if connected with peerConnectLogin or peerConnectPreAuth.
///////////////////////////////////////////////////////////////////////
int peerGetProfileID(PEER peer);

// This gets called when an attempt to change nicks is finished.
////////////////////////////////////////////////////////////////
typedef void (* peerChangeNickCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // PEERTrue if success, PEERFalse if failure.
	const gsi_char * oldNick,  // The old nickname.
	const gsi_char * newNick,  // The new nickname.
	void * param  // User-data.
);

// Changes the user's nickname.
///////////////////////////////
void peerChangeNick
(
	PEER peer,  // The peer object.
	const gsi_char * newNick,  // The nickname to which to change.
	peerChangeNickCallback callback,  // Called when finished.
	void * param,  // Passed to the callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Causes Peer to not automatically leave the
// room the next time peerSetTitle or peerClearTitle
// is called.  No effect if a title isn't set.  When
// the next title is set, the flag is cleared.
// Only TitleRoom is currently supported.
// This function is normally not needed.
////////////////////////////////////////////////////
void peerStayInRoom
(
	PEER peer,  // The peer object.
	RoomType roomType  // Only TitleRoom is currently supproted.
);

// Turns quiet mode on/off.
///////////////////////////
void peerSetQuietMode
(
	PEER peer,  // The peer object.
	PEERBool quiet  // If PEERTrue, enable quiet mode.
);

// Sets the away mode.
// If an empty string or NULL, away mode is off.
// If a valid string, away mode is on.
////////////////////////////////////////////////
void peerSetAwayMode
(
	PEER peer,  // The peer object.
	const gsi_char * reason  // The away reason.  If NULL or "", not away.
);

// When using peerStartReportingWithSocket or peerCreateStagingRoomWithSocket,
// any qureries received on the sockets need to be passed to the SDK.  Pass
// the data using this function.
//////////////////////////////////////////////////////////////////////////////
void peerParseQuery
(
	PEER peer,  // The peer object.
	char * query,  // String of query data.
	int len,  // The length of the string, not including the NUL.
	struct sockaddr * sender  // The address the query was received from.
);

// This gets called when an attempt to authenticate a CD key is finished.
// If the result is 1, the CD key was authenticated.  Otherwise, the CD
// key was not authenticated.
/////////////////////////////////////////////////////////////////////////
typedef void (* peerAuthenticateCDKeyCallback)
(
	PEER peer,  // The peer object.
	int result,  // 1 if authenticated, otherwise not authenticated.
	const gsi_char * message,  // A string representing the result.
	void * param  // User-data.
);

// Sends a CD Key to the chat server for authentication.
// The callback gets called when the chat server responds.
// This call is required by some games to enter chat rooms.
// It must be called after connecting to the chat server, but
// before entering a room.
/////////////////////////////////////////////////////////////
void peerAuthenticateCDKey
(
	PEER peer,  // The peer object.
	const gsi_char * cdkey,  // The CD key to authenticate.
	peerAuthenticateCDKeyCallback callback,  // Called when finished.
	void * param,  // Passed to the callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Sends a nat-negotiate cookie to a server.
////////////////////////////////////////////
void peerSendNatNegotiateCookie
(
	PEER peer,  // The peer object.
	unsigned int ip,  // IP (network byte order) of the server to send the cookie to.
	unsigned short port,  // Port (host byte order) of the server to send the cookie to.
	int cookie  // The cookie to send.
);

// Sends a client message to a QR2 server.
//////////////////////////////////////////
void peerSendMessageToServer
(
	PEER peer,
	unsigned int ip,
	unsigned short port,
	const char * data,
	int len
);

// If always is PEERTrue, then players' IP and profile ID will
// always be requested when joining a room.  This info is normally
// only requested if pings are set in a room.  Use this function
// to always request the information.
//////////////////////////////////////////////////////////////////
void peerAlwaysGetPlayerInfo
(
	PEER peer,  // The peer object.
	PEERBool always  // If true, always get player info.
);

/**********
** ROOMS **
**********/
// This gets called when an attempt to join or create a room has finished.
//////////////////////////////////////////////////////////////////////////
typedef void (* peerJoinRoomCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // PEERTrue if success, PEERFalse if failure.
	PEERJoinResult result,  // The result of the attempt.
	RoomType roomType,  // The type of room joined/created.
	void * param  // User-data.
);

// Joins the currently selected title's title room.
///////////////////////////////////////////////////
void peerJoinTitleRoom
(
	PEER peer,  // The peer object.
	const gsi_char password[PEER_PASSWORD_LEN],  // An optional password, normally NULL.
	peerJoinRoomCallback callback,  // Called when finished.
	void * param,  // Passed to the callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Joins a group room.
// The groupID comes from the peerListGroupRoomsCallback.
/////////////////////////////////////////////////////////
void peerJoinGroupRoom
(
	PEER peer,  // The peer object.
	int groupID,  // The ID for the group to join.
	peerJoinRoomCallback callback,  // Called when finished.
	void * param,  // Passed to the callback.
	PEERBool blocking // If PEERTrue, don't return until finished.
);

// Sets the group ID.
// Used to get a list of games in a group room and/or report or create a game
// in a particular group, without actually being in that group room.  This is
// not needed if already using peerJoinGroupRoom.
// Setting a group ID of 0 is equivalent to leaving the group room.
/////////////////////////////////////////////////////////////////////////////
void peerSetGroupID
(
	PEER peer,  // The peer object.
	int groupID  // The group ID to set
);

// Returns the current group ID.
// The group ID is set with either peerJoinGroupRoom or peerSetGroupID.
///////////////////////////////////////////////////////////////////////
int peerGetGroupID
(
	PEER peer  // The peer object.
);

// Joins a staging room.
// server is one of the server objects passed to peerListingGamesCallback().
// This call will only work if staging==PEERTrue for the server.
// PANTS|09.11.00 - The password is only needed for passworded rooms.
// PANTS|03.15.01 - No longer requires you to be actively listing games.
////////////////////////////////////////////////////////////////////////////
void peerJoinStagingRoom
(
	PEER peer,  // The peer object.
	SBServer server,  // The server passed into peerlistingGamesCallback().
	const gsi_char password[PEER_PASSWORD_LEN],  // The password of the room being joined.  Can be NULL or "".
	peerJoinRoomCallback callback,  // Called when finished.
	void * param,  // Passed to the callback.
	PEERBool blocking   // If PEERTrue, don't return until finished.
);

// Joins a staging room by its channel name.
// Same as peerJoinStagingRoom, except it takes the staging room's
// channel name instead of an SBServer object.  Also, when the
// peerGameStartedCallback is called, the server paramter passed to
// it will be NULL.
///////////////////////////////////////////////////////////////////
void peerJoinStagingRoomByChannel
(
	PEER peer,  // The peer object.
	const gsi_char * channel,  // The channel to join.
	const gsi_char password[PEER_PASSWORD_LEN],  // The password of the room being joined.  Can be NULL or "".
	peerJoinRoomCallback callback,  // Called when finished.
	void * param,  // Passed to the callback.
	PEERBool blocking   // If PEERTrue, don't return until finished.
);

// Creates a new staging room, with the local player hosting.
// PANTS|09.11.00 - If the password parameter is not NULL
// or "", this will create a passworded room.  The same
// case-sensitive password needs to be passed into
// peerJoinStagingRoom() for other player's to join the room.
// PANTS|09.11.00 - The staging room will be reported as part
// of whatever group room the local player was in when the
// room was created.  Leaving the group room will not affect
// what group the staging room is reported as part of.
/////////////////////////////////////////////////////////////
void peerCreateStagingRoom
(
	PEER peer,  // The peer object.
	const gsi_char * name,  // The name of the room.
	int maxPlayers,  // The max number of players allowed in the room.
	const gsi_char password[PEER_PASSWORD_LEN],  // An optional password for the staging room
	peerJoinRoomCallback callback,  // Called when finished.
	void * param,  // Passed to the callback.
	PEERBool blocking // If PEERTrue, don't return until finished.
);

// Same as peerCreateStagingRoom, but uses the provided socket for
// sending heartbeats and query replies.  This allows the game
// to share a socket with the peer SDK, which can make hosting
// games behind a NAT proxy possible.
//////////////////////////////////////////////////////////////////
void peerCreateStagingRoomWithSocket
(
	PEER peer,  // The peer object.
	const gsi_char * name,  // The name of the room.
	int maxPlayers,  // The max number of players allowed in the room.
	const gsi_char password[PEER_PASSWORD_LEN],  // An optional password for the staging room
	SOCKET socket,  // The socket to be used for reporting.
	unsigned short port,  // The local port to which the socket is bound.
	peerJoinRoomCallback callback,  // Called when finished.
	void * param,  // Passed to the callback.
	PEERBool blocking // If PEERTrue, don't return until finished.
);

// Leave a room.
// PANTS|09.11.00 - You can now leave a group room
// without being forcibly removed from a staging room.
//////////////////////////////////////////////////////
void peerLeaveRoom
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room you want to leave (TitleRoom, GroupRoom, or StagingRoom).
	const gsi_char * reason  // The reason the player is leaving (can be NULL).  PANTS|03.13.01
);

// Gets called once for each group room when listing group rooms.
// After this has been called for each group room, it will be
// called one more time with groupID==0 and name==NULL.
/////////////////////////////////////////////////////////////////
typedef void (* peerListGroupRoomsCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // PEERTrue if success, PEERFalse if failure.
	int groupID,  // A unique ID for this group.
	SBServer server,  // The server object for this group room.
	const gsi_char * name,  // The group room's name.
	int numWaiting,  // The number of players in the room.
	int maxWaiting,  // The maximum number of players allowed in the room.
	int numGames,  // The number of games either staging or running in the group.
	int numPlaying,  // The total number of players in games in the group.
	void * param  // User-data.
);

// List all the groups rooms for the currently set title.
// The fields parameter allows you to request extra info
//   on each group room.
/////////////////////////////////////////////////////////
void peerListGroupRooms
(
	PEER peer,  // The peer object.
	const gsi_char * fields,  // A backslash delimited list of fields.
	peerListGroupRoomsCallback callback,  // Called for each group room.
	void * param,  // Passed to the callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Called with info on games being listed.
// Used to maintain a list of running games and staging rooms.
// The server object is a unique way of identifying each game.
// It can also be used with the calls in the "SBServer Object Functions" section
//   of sb_serverbrowsing.h to find out more info about the server.
// If staging==PEERTrue, the game hasn't started yet, it's still in the staging room
//   use peerJoinStagingRoom() to join the staging room, or if staging==peerfalse
//   use the server object to get the game's IP and port to join with.
// During the _intial_ listing of games, progress is the percentage (0-100) of the
//   games that have been added.  Once the initial listing is completed,
//   progress will always be 100.
// PANTS|09.11.00 - The "password" key will be set to 1 for games that are
// passworded.  This can be checked with ServerGetIntValue(server, "password", 0).
/////////////////////////////////////////////////////////////////////////////////////
typedef void (* peerListingGamesCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // PEERTrue if success, PEERFalse if failure.
	const gsi_char * name,  // The name of the game being listed.
	SBServer server,  // The server object for this game.
	PEERBool staging,  // If PEERTrue, this is a staging room and not a running game.
	int msg,  // The type of message this is.
		// PEER_CLEAR:
		//   Clear the list.  This has the same effect as if this was called
		//   with PEER_REMOVE for every server listed.
		// PEER_ADD:
		//   This is a new server. Add it to the list.
		// PEER_UPDATE:
		//   This server is already on the list, and its been updated.
		// PEER_REMOVE:
		//   Remove this server from the list.  The server object for this server
		//   should not be used again after this callback returns.
	int progress,  // The percent of servers that have been added.
	void * param  // User-data.
);

// Start listing the currently running games and staging rooms.
// This is used to maintain a list that can presented to the user,
//   so they can pick a game (or staging room) to join.
// Games and staging rooms are filtered based on what group the local
//   user is in.  If the local user isn't in a group, then only games
//   and staging rooms that aren't part of any group are listed.
// The fields determine which info to request from the server.  These
//   must be registered QR2 keys (see qr2regkeys.h).  HOSTNAME_KEY and
//   GAMEMODE_KEY are automatically requested by Peer, so do not need
//   to included.
/////////////////////////////////////////////////////////////////////
void peerStartListingGames
(
	PEER peer,  // The peer object.
	const unsigned char * fields,  // An array of registered QR2 keys to request from servers.
	int numFields,  // The number of keys in the fields array.
	const gsi_char * filter,  // A SQL-like rule filter.
	peerListingGamesCallback callback,  // Called when finished.
	void * param  // Passed to the callback.
);

// Stop games from being listed. This does NOT clear the games list.
// So all games listed are still considered valid.  They stay valid
// until either another call to peerStartListingGames or until the
// title is cleared (or a new one set).
////////////////////////////////////////////////////////////////////
void peerStopListingGames
(
	PEER peer  // The peer object.
);

// Queries the game server for the latest information.
// If fullUpdate is PEERTrue, all of the keys will be requested.
// If fullUpdate is PEERFalse, only the keys passed to
// peerStartListingGames as the fields parameter will be requested.
///////////////////////////////////////////////////////////////////
void peerUpdateGame
(
	PEER peer,  // The peer object.
	SBServer server,  // The server object for the game to update.
	PEERBool fullUpdate  // If true, get all of the game's keys.
);

// 08-26-2004 Added by Saad Nader
// Queries the game server for the latest information via the master 
// server.
// If fullUpdate is PEERTrue, all of the keys will be requested.
// If fullUpdate is PEERFalse, only the keys passed to
// peerStartListingGames as the fields parameter will be requested.
///////////////////////////////////////////////////////////////////
void peerUpdateGameByMaster
(
	PEER peer,  // The peer object.
	SBServer server,  // The server object for the game to update.
	PEERBool fullUpdate  // If true, get all of the game's keys.
);

// Send a ping to the server
// ICMP echo reply will be sent as response.  The firewall 
// or NAT between server and internet does not have to accept 
// ICMP echo requests.
///////////////////////////////////////////////////////////////////
void peerUpdateGamePing(PEER peer, SBServer server);

// Send a message to a room.
////////////////////////////
void peerMessageRoom
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room to send the message to.
	const gsi_char * message,  // The message.
	MessageType messageType  // The type of message.
);

// Send a UTM to a room.
////////////////////////
void peerUTMRoom
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room to send the UTM to.
	const gsi_char * command,  // The command.
	const gsi_char * parameters,  // The UTM's parameters.
	PEERBool authenticate  // If true, the server will authenticate this UTM (should normally be false).
);

// Set a password in a room you're hosting.
// The only roomType currently supported is StagingRoom.
// This will only work if the player is hosting the room.
// If password is NULL or "", the password will be cleared.
///////////////////////////////////////////////////////////
void peerSetPassword
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room in which to set the password.
	const gsi_char password[PEER_PASSWORD_LEN]  // The password to set.
);

// Set the name of a room you're hosting.
// The only roomType currently supported is StagingRoom.
// PANTS|09.11.00
////////////////////////////////////////////////////////
void peerSetRoomName
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room in which to set the name.
	const gsi_char * name  // The new name
);

// Get a room's name (the channel's title).
// Returns NULL if not in the room.
///////////////////////////////////////////
const gsi_char * peerGetRoomName
(
	PEER peer,  // The peer object.
	RoomType roomType  // The room to get the name for.
);

// Get's the chat channel associated with the room.
// Returns NULL if not in the room.
///////////////////////////////////////////////////
const gsi_char * peerGetRoomChannel
(
	PEER peer,  // The peer object.
	RoomType roomType  // The room to get the channel for.
);

// Returns PEERTrue if in the room.
///////////////////////////////////
PEERBool peerInRoom
(
	PEER peer,  // The peer object.
	RoomType roomType  // The room to check for.
);

// Use this channel for the title room for the currently set title.
// This function is normally not needed.
///////////////////////////////////////////////////////////////////
void peerSetTitleRoomChannel
(
	PEER peer,  // The peer object.
	const gsi_char * channel  // The channel to use for the title room.
);

// Use this to get the SBServer object for the staging room host.
// This will return NULL if the local player is not in a staging room,
// is the staging room host, or joined using peerJoinStagingRoomByChannel.
//////////////////////////////////////////////////////////////////////////
SBServer peerGetHostServer(PEER peer);

// Update the maximum number of players for a staging room
/////////////////////////////////////////////////////////
void peerSetStagingRoomMaxPlayers
(
	PEER peer,
	int maxPlayers
);

/************
** PLAYERS **
************/
// Called for each player in a room being enumerated, and once
//   when finished, with index==-1 and nick==NULL.
//////////////////////////////////////////////////////////////
typedef void (* peerEnumPlayersCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // PEERTrue if success, PEERFalse if failure.
	RoomType roomType,  // The room whose players are being enumerated.
	int index,  // The index of the player (0 to (N - 1)).  -1 when finished.
	const gsi_char * nick,  // The nick of the player.
	int flags,  // This player's flags (see #define's above).  PANTS|03.12.01
	void * param  // User-data.
);

// Enumerates through the players in a room.
////////////////////////////////////////////
void peerEnumPlayers
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room to enum the players in.
	peerEnumPlayersCallback callback,  // Called when finished.
	void * param  // Passed to callback.
);

// Send a message to a player.
//////////////////////////////
void peerMessagePlayer
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The nick of the player to send the message to.
	const gsi_char * message,  // The message to send.
	MessageType messageType  // The type of message.
);

// Send a UTM to a player.
//////////////////////////
void peerUTMPlayer
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The nick of the player to send the UTM to.
	const gsi_char * command,  // The command.
	const gsi_char * parameters,  // The UTM's parameters.
	PEERBool authenticate  // If true, the server will authenticate this UTM (should normally be false).
);

// Kick a player from a room.
// Can only be called by a player with host privileges.
///////////////////////////////////////////////////////
void peerKickPlayer
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room to kick the player from.
	const gsi_char * nick,  // The nick of the player to kick.
	const gsi_char * reason  // An optional reason for kicking the player
);

// Gets a player's ping (between the local machine and the player's machine).
// Returns PEERFalse if we don't have or can't get the player's ping.
/////////////////////////////////////////////////////////////////////////////
PEERBool peerGetPlayerPing
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The player to get the ping for.
	int * ping  // The player's ping is stored here, if we have it.
);

// Gets the cross-ping between 2 players.
// Returns PEERFalse if we don't have or can't get the player's cross-ping.
///////////////////////////////////////////////////////////////////////////
PEERBool peerGetPlayersCrossPing
(
	PEER peer,  // The peer object.
	const gsi_char * nick1,  // The first player.
	const gsi_char * nick2,  // The second player.
	int * crossPing  // The cross-ping is stored here, if we have it.
);

// Peer already automatically pings all players that are in ping rooms.
// This function does a one-time ping of a remote player in a non-ping room.
// However pings must be enabled in at least one room for this to work,
// otherwise Peer will not open the UDP ping socket.
// Also, peerAlwaysGetPlayerInfo() must be enabled so that Peer has IPs for
// players that are only in non-ping rooms.
////////////////////////////////////////////////////////////////////////////
PEERBool peerPingPlayer
(
	PEER peer,  // The peer object.
	const gsi_char * nick  // The player to ping.
);

// Gets a player's info immediately.
// Returns PEERFalse if the info is no available.
/////////////////////////////////////////////////
PEERBool peerGetPlayerInfoNoWait
(
	PEER peer,
	const gsi_char * nick,
	unsigned int * IP,
	int * profileID
);

// Called as a result of a call to peerGetPlayerInfo().
///////////////////////////////////////////////////////
typedef void (* peerGetPlayerInfoCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // PEERTrue if success, PEERFalse if failure.
	const gsi_char * nick,  // The player's nick.
	unsigned int IP,  // The player's IP, in network byte order.
	int profileID,  // The player's profile ID.
	void * param  // User-data.
);

// Called to get a player's IP and profile ID.
//////////////////////////////////////////////
void peerGetPlayerInfo
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The player's nick.
	peerGetPlayerInfoCallback callback,  // Called when finished.
	void * param,  // Passed to callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Called as a result of a call to peerGetPlayerProfileID().
////////////////////////////////////////////////////////////
typedef void (* peerGetPlayerProfileIDCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // PEERTrue if success, PEERFalse if failure.
	const gsi_char * nick,  // The player's nick.
	int profileID,  // The player's profile ID.
	void * param  // User-data.
);

// Called to get a player's profile ID.
// DEPRECATED - Use peerGetPlayerInfo.
///////////////////////////////////////
void peerGetPlayerProfileID
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The player's nick.
	peerGetPlayerProfileIDCallback callback,  // Called when finished.
	void * param,  // Passed to callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Called as a result of a call to peerGetPlayerIP().
/////////////////////////////////////////////////////
typedef void (* peerGetPlayerIPCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // PEERTrue if success, PEERFalse if failure.
	const gsi_char * nick,  // The player's nick.
	unsigned int IP,  // The player's IP, in network byte order.  PANTS|09.11.00 - was unsigned long
	void * param  // User-data.
);

// Called to get a player's IP.
// DEPRECATED - Use peerGetPlayerInfo.
//////////////////////////////////////
void peerGetPlayerIP
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The player's nick.
	peerGetPlayerIPCallback callback,  // Called when finished.
	void * param,  // Passed to callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Checks if a player is a host (has ops).
// Returns PEERTrue if yes, PEERFalse if no.
////////////////////////////////////////////
PEERBool peerIsPlayerHost
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The player's nick.
	RoomType roomType  // The room to check in.
);

// Gets a player's flags in a room.  Returns PEERFalse if
// the local player or this player is not in the room.
/////////////////////////////////////////////////////////
PEERBool peerGetPlayerFlags
(
	PEER peer,
	const gsi_char * nick,
	RoomType roomType,
	int * flags
);

/*********
** GAME **
*********/
/**************** Disabled *************************/
// Returns the qr2 record used to report
// Primarily used for CD Key integration to prevent
// game intrusion and and post staging hacks
////////////////////////////////////////////////////
//qr2_t peerGetReportingRecord(PEER peer);

// Sets the local player's ready state.
// PEERTrue if ready, PEERFalse if not ready.
/////////////////////////////////////////////
void peerSetReady
(
	PEER peer,  // The peer object.
	PEERBool ready  // Ready or not.
);

// Gets a player's ready state.
///////////////////////////////
PEERBool peerGetReady
(
	PEER peer,  // The peer object.
	const gsi_char * nick, // The player's nick.
	PEERBool * ready  // The player's ready state gets stored in here.
);

// Checks if all the player's in the staging room are ready.
////////////////////////////////////////////////////////////
PEERBool peerAreAllReady
(
	PEER peer  // The peer object.
);

// Called only by a staging room host to start the game.
// All the other people in the staging room will have their
//   peerGameStartedCallback() called.
// The message gets passed to everyone in the peerGameStartedCallback(), and
//   can be used to pass information such as a special port or password.
// If (reportingOptions & PEER_STOP_REPORTING), Peer will stop game reporting,
//   so the program is responsible for any server reporting.
// If !(reportingOptions & PEER_STOP_REPORTING), Peer will continue doing 
//   game reporting, and calling the program-supplied callbacks.  If
//   (reportingOptions & PEER_REPORT_INFO), all server keys will still be
//   reported.  If (reportingOptions & PEER_REPORT_PLAYERS), all player keys
//   will still be reported.
/////////////////////////////////////////////////////////////////////////////
void peerStartGame
(
	PEER peer,  // The peer object.
	const gsi_char * message,  // A message to send to everyone.
	int reportingOptions  // Bitfield flags used to set reporting options.
);

// Starts server reporting, without creating a staging room.
// Call peerStopGame() to stop reporting.
////////////////////////////////////////////////////////////////
PEERBool peerStartReporting
(
	PEER peer  // The peer object.
);

// Same as peerStartReporting, but uses the provided socket for
// sending heartbeats and query replies.  This allows the game
// to share a socket with the peer SDK, , which can make hosting
// games behind a NAT proxy possible.
////////////////////////////////////////////////////////////////
PEERBool peerStartReportingWithSocket
(
	PEER peer,  // The peer object.
	SOCKET socket,  // The socket to be used for reporting.
	unsigned short port  // The local port to which the socket is bound.
);

// Mark the local player as playing.
// Use this if the player is in a game not
// started by peer, but he should be marked as playing.
///////////////////////////////////////////////////////
void peerStartPlaying
(
	PEER peer  // The peer object.
);

// Check to see if the local player is playing.
///////////////////////////////////////////////
PEERBool peerIsPlaying
(
	PEER peer  // The peer object.
);

// Needs to be called by the host when the game has stopped.
////////////////////////////////////////////////////////////
void peerStopGame
(
	PEER peer  // The peer object.
);

// Call this when hosting a staging room or a game to force peer
// to report the game again.  An example of when to call this is
// when a player joins or leaves a game.
// PANTS|09.11.00
///////////////////////////////////////////////////////////////////
void peerStateChanged
(
	PEER peer  // The peer object.
);

/*********
** KEYS **
*********/
// Set global keys on the local player.
///////////////////////////////////////
void peerSetGlobalKeys
(
	PEER peer,  // The peer object.
	int num,  // The number of keys to set.
	const gsi_char ** keys,  // The keys to set.
	const gsi_char ** values  // The values for the keys.
);

// Called with a player's global keys.
//////////////////////////////////////
typedef void (* peerGetGlobalKeysCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // If PEERFalse, unable to get the keys.
	const gsi_char * nick,  // The player the keys are for.
	int num,  // The number of keys.
	const gsi_char ** keys,  // The keys got.
	const gsi_char ** values,  // The values for the keys.
	void * param  // User-data.
);

// Get a player's global keys.
//////////////////////////////
void peerGetPlayerGlobalKeys
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The player to get the keys for.
	int num,  // The number of keys.
	const gsi_char ** keys,  // The keys to get.
	peerGetGlobalKeysCallback callback,  // Called with the keys.
	void * param,  // Passed to callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Get the global keys for all players in a room we're in.
//////////////////////////////////////////////////////////
void peerGetRoomGlobalKeys
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room to get the keys in.
	int num,  // The number of keys.
	const gsi_char ** keys,  // The keys to get.
	peerGetGlobalKeysCallback callback,  // Called with the keys.
	void * param,  // Passed to callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Set the room keys for a player.
// Use NULL or "" to set keys on the room itself.
/////////////////////////////////////////////////
void peerSetRoomKeys
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room to set the keys in.
	const gsi_char * nick,  // The player to set the keys on (NULL or "" for the room).
	int num,  // The number of keys.
	const gsi_char ** keys,  // The keys to set.
	const gsi_char ** values  // The values to set.
);

// Called with a player's room keys.
////////////////////////////////////
typedef void (* peerGetRoomKeysCallback)
(
	PEER peer,  // The peer object.
	PEERBool success,  // If PEERFalse, unable to get the keys.
	RoomType roomType,  // The room the keys are in.
	const gsi_char * nick,  // The player the keys are for, or NULL for the room.
	int num,  // The number of keys.
	gsi_char ** keys,  // The keys.
	gsi_char ** values,  // The values for the keys.
	void * param  // User-data.
);

// Get the room keys for either a single player of an entire room.
// Use "*" for the player to get the keys for the entire room.
// Use NULL or "" for the player to get keys on the room itself.
//////////////////////////////////////////////////////////////////
void peerGetRoomKeys
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room to get the keys in.
	const gsi_char * nick,  // The player to get the keys for.
	int num,  // The number of keys.
	const gsi_char ** keys,  // The keys to get.
	peerGetRoomKeysCallback callback,  // Called with the keys.
	void * param,  // Passed to callback.
	PEERBool blocking  // If PEERTrue, don't return until finished.
);

// Set the global watch keys for a room type.
// If addKeys is set to PEERTrue, the keys will be
// added to the current global watch keys for this room.
// If addKeys is PEERFalse, these will replace any existing
// global watch keys for this room.
// When entering a room of the given type, peer will get and
// cache these keys for all players in the room.
////////////////////////////////////////////////////////////
void peerSetGlobalWatchKeys
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room to set the watch keys for.
	int num,  // The number of keys.
	const gsi_char ** keys,  // The keys to watch for.
	PEERBool addKeys  // If PEERTrue, add these keys to the existing global watch keys for this room.
);

// Set the room watch keys for a room type.
// If addKeys is set to PEERTrue, the keys will be
// added to the current room watch keys for this room.
// If addKeys is PEERFalse, these will replace any existing
// room watch keys for this room.
// When entering a room of the given type, peer will get and
// cache these keys for all players in the room.
////////////////////////////////////////////////////////////
void peerSetRoomWatchKeys
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The type of room to set the watch keys for.
	int num,  // The number of keys.
	const gsi_char ** keys,  // The keys to watch for.
	PEERBool addKeys  // If PEERTrue, add these keys to the existing room watch keys for this room.
);

// Get the global watch key for a particular player.
// If the key isn't cached locally (either because it isn't
// a watch key or just isn't yet known), NULL will be returned.
// If the key is empty, "" will be returned.
///////////////////////////////////////////////////////////////
const gsi_char * peerGetGlobalWatchKey
(
	PEER peer,  // The peer object.
	const gsi_char * nick,  // The player to get the key for.
	const gsi_char * key  // The key to get.
);

// Get the room watch key for a particular player in a room.
// If the key isn't cached locally (either because it isn't
// a watch key or just isn't yet known), NULL will be returned.
// If the key is empty, "" will be returned.
///////////////////////////////////////////////////////////////
const gsi_char * peerGetRoomWatchKey
(
	PEER peer,  // The peer object.
	RoomType roomType,  // The room to get the key in.
	const gsi_char * nick,  // The player to get the key for.
	const gsi_char * key  // The key to get.
);

/**************
** AUTOMATCH **
**************/

// Called during a automatch attempt to inform the app of the status.
/////////////////////////////////////////////////////////////////////
typedef void (* peerAutoMatchStatusCallback)
(
	PEER peer,  // The peer object.
	PEERAutoMatchStatus status,  // The current status.
	void * param  // User-data.
);

// This callback may be called during the automatch attempt.
// Peer uses the callback to ask the application how well a particular
// match fits what the user is looking for.  The application checks the match
// and then returns a rating for it.  If the rating is <=0 the match is
// considered unsuitable and Peer will not attempt that match.  If the rating
// is >0 this match is considered suitable.  The higher the rating, up to a
// maximum of INT_MAX, the more suitable the match.  The exact scheme used
// to generate a rating is entirely up to the application.  The match ratings
// are used by Peer both to check if a particular match meets the user's wishes
// and to compare matches to each other.  Peer will first try to match with the
// highest rated possible match, then the second highest, etc.
///////////////////////////////////////////////////////////////////////////////
typedef int (* peerAutoMatchRateCallback)
(
	PEER peer,  // The peer object.
	SBServer match,  // Possible match to rate.
	void * param  // User-data.
);

// Used to start a automatch attempt.
// The filter contains any hard criteria.  This is used to narrow down the list
// of possible matches to those the user might consider.
// The status callback will be called as the attempt progresses, and the rate
// callback will be used to sort possible matches.
/////////////////////////////////////////////////////////////////////////////////
void peerStartAutoMatch
(
	PEER peer,  // The peer object.
	int maxPlayers,  // The total number of players to match (including the local player).
	const gsi_char * filter,  // Hard criteria - filters out servers.
	peerAutoMatchStatusCallback statusCallback,  // Called as the attempt status changes.
	peerAutoMatchRateCallback rateCallback,  // Used to rate possible matches.
	void * param,  // User-data.
	PEERBool blocking   // If PEERTrue, don't return until finished.
);

// Same as peerStartAutoMatch, but uses the provided socket for
// sending heartbeats and query replies.  This allows the game
// to share a socket with the peer SDK, which can make hosting
// games behind a NAT proxy possible.
////////////////////////////////////////////////////////////////
void peerStartAutoMatchWithSocket
(
	PEER peer,  // The peer object.
	int maxPlayers,  // The total number of players to match (including the local player).
	const gsi_char * filter,  // Hard criteria - filters out servers.
	SOCKET socket,  // The socket to be used for reporting.
	unsigned short port,  // The local port to which the socket is bound.
	peerAutoMatchStatusCallback statusCallback,  // Called as the attempt status changes.
	peerAutoMatchRateCallback rateCallback,  // Used to rate possible matches.
	void * param,  // User-data.
	PEERBool blocking   // If PEERTrue, don't return until finished.
);

// Stops an automatch attempt in progress.
// The user will not automatically be removed from any staging room he is in.
/////////////////////////////////////////////////////////////////////////////
void peerStopAutoMatch(PEER peer);

// Checks if a automatch attempt is in progress.
////////////////////////////////////////////////
PEERBool peerIsAutoMatching(PEER peer);

// Gets the current status of the automatch attempt.
// If no attempt is in progress, PEERFailed will be returned.
/////////////////////////////////////////////////////////////
PEERAutoMatchStatus peerGetAutoMatchStatus(PEER peer);

#ifdef __cplusplus
}
#endif

#endif