peerAscii.h

 /*
GameSpy Peer SDK 
Dan "Mr. Pants" Schoenblum
dan@gamespy.com
 
Copyright 1999-2007 GameSpy Industries, Inc
 
devsupport@gamespy.com
*/
 
#ifndef _PEERASCII_H_
#define _PEERASCII_H_
 
// PROTOTYPES OF ASCII FUNCTIONS
// The only purpose of this file is to silence the CodeWarrior
// "function not prototyped" warnings when using GSI_UNICODE mode
 
#ifdef __cplusplus
extern "C" {
#endif
 
 
/************
** GENERAL **
************/
// 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 peerConnectA
(
    PEER peer,  // The peer object.
    const 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 peerConnectLoginA
(
    PEER peer,  // The peer object.
    int namespaceID,  // The namespace in which to login.
    const char * email,  // The email to login with.
    const char * profilenick,  // The profile to login with.
    const char * uniquenick,  // The uniquenick to login with.
    const 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 peerConnectPreAuthA
(
    PEER peer,  // The peer object.
    const char * authtoken,  // The authtoken for this login.
    const 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 peerRetryWithNickA
(
    PEER peer,
    const 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 peerRegisterUniqueNickA
(
    PEER peer,
    int namespaceID,
    const char * uniquenick,
    const char * cdkey
);
 
// 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 peerSetTitleA
(
    PEER peer,  // The peer object.
    const char * title,  // The title to make current (ie., ut, gmtest).
    const char * qrSecretKey,  // The queryreporting secret key.
    const char * sbName,  // The serverbrowsing name.
    const 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.
);
 
// Gets the currently set title.
// Returns NULL if no title is set.
const char * peerGetTitleA(PEER peer);
 
// Get the local user's nickname.
const char * peerGetNickA(PEER peer);
 
// Replaces any invalid characters in nick with underscores.
void peerFixNickA
(
    char * newNick,
    const char * oldNick
);
 
// Removes the namespace extension from a chat unique nick.
// Returns the nick if it ended with the extension.
// Otherwise returns NULL.
const char * peerTranslateNickA
(
    char * nick,  // The nick to translate
    const char * extension  // The extension to be removed.
);
 
// Changes the user's nickname.
void peerChangeNickA
(
    PEER peer,  // The peer object.
    const 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.
);
 
// Sets the away mode.
// If an empty string or NULL, away mode is off.
// If a valid string, away mode is on.
void peerSetAwayModeA
(
    PEER peer,  // The peer object.
    const 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 peerParseQueryA
(
    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.
);
 
// 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 peerAuthenticateCDKeyA
(
    PEER peer,  // The peer object.
    const 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.
);
 
/**********
** ROOMS **
**********/
// Joins the currently selected title's title room.
void peerJoinTitleRoomA
(
    PEER peer,  // The peer object.
    const 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 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 peerJoinStagingRoomA
(
    PEER peer,  // The peer object.
    SBServer server,  // The server passed into peerlistingGamesCallback().
    const 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 peerJoinStagingRoomByChannelA
(
    PEER peer,  // The peer object.
    const char * channel,  // The channel to join.
    const 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 peerCreateStagingRoomA
(
    PEER peer,  // The peer object.
    const char * name,  // The name of the room.
    int maxPlayers,  // The max number of players allowed in the room.
    const 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 peerCreateStagingRoomWithSocketA
(
    PEER peer,  // The peer object.
    const char * name,  // The name of the room.
    int maxPlayers,  // The max number of players allowed in the room.
    const 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 peerLeaveRoomA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room you want to leave (TitleRoom, GroupRoom, or StagingRoom).
    const char * reason  // The reason the player is leaving (can be NULL).  PANTS|03.13.01
);
 
// List all the groups rooms for the currently set title.
// The fields parameter allows you to request extra info
//   on each group room.
void peerListGroupRoomsA
(
    PEER peer,  // The peer object.
    const 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.
);
 
// 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 peerStartListingGamesA
(
    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 char * filter,  // A SQL-like rule filter.
    peerListingGamesCallback callback,  // Called when finished.
    void * param  // Passed to the callback.
);
 
// Send a message to a room.
void peerMessageRoomA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room to send the message to.
    const char * message,  // The message.
    MessageType messageType  // The type of message.
);
 
// Send a UTM to a room.
void peerUTMRoomA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room to send the UTM to.
    const char * command,  // The command.
    const 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 peerSetPasswordA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room in which to set the password.
    const 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 peerSetRoomNameA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room in which to set the name.
    const char * name  // The new name
);
 
// Get a room's name (the channel's title).
// Returns NULL if not in the room.
const char * peerGetRoomNameA
(
    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 char * peerGetRoomChannelA
(
    PEER peer,  // The peer object.
    RoomType roomType  // The room to get the channel for.
);
 
// Use this channel for the title room for the currently set title.
// This function is normally not needed.
void peerSetTitleRoomChannelA
(
    PEER peer,  // The peer object.
    const char * channel  // The channel to use for the title room.
);
 
 
/************
** PLAYERS **
************/
// Send a message to a player.
void peerMessagePlayerA
(
    PEER peer,  // The peer object.
    const char * nick,  // The nick of the player to send the message to.
    const char * message,  // The message to send.
    MessageType messageType  // The type of message.
);
 
// Send a UTM to a player.
void peerUTMPlayerA
(
    PEER peer,  // The peer object.
    const char * nick,  // The nick of the player to send the UTM to.
    const char * command,  // The command.
    const 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 peerKickPlayerA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room to kick the player from.
    const char * nick,  // The nick of the player to kick.
    const 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 peerGetPlayerPingA
(
    PEER peer,  // The peer object.
    const 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 peerGetPlayersCrossPingA
(
    PEER peer,  // The peer object.
    const char * nick1,  // The first player.
    const 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 peerPingPlayerA
(
    PEER peer,  // The peer object.
    const char * nick  // The player to ping.
);
 
// Gets a player's info immediately.
// Returns PEERFalse if the info is no available.
PEERBool peerGetPlayerInfoNoWaitA
(
    PEER peer,
    const char * nick,
    unsigned int * IP,
    int * profileID
);
 
// Called to get a player's IP and profile ID.
void peerGetPlayerInfoA
(
    PEER peer,  // The peer object.
    const 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 to get a player's profile ID.
// DEPRECATED - Use peerGetPlayerInfo.
void peerGetPlayerProfileIDA
(
    PEER peer,  // The peer object.
    const 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 to get a player's IP.
// DEPRECATED - Use peerGetPlayerInfo.
void peerGetPlayerIPA
(
    PEER peer,  // The peer object.
    const 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 peerIsPlayerHostA
(
    PEER peer,  // The peer object.
    const 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 peerGetPlayerFlagsA
(
    PEER peer,
    const char * nick,
    RoomType roomType,
    int * flags
);
 
/*********
** GAME **
*********/
// Gets a player's ready state.
PEERBool peerGetReadyA
(
    PEER peer,  // The peer object.
    const char * nick, // The player's nick.
    PEERBool * ready  // The player's ready state gets stored in here.
);
 
// 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 peerStartGameA
(
    PEER peer,  // The peer object.
    const char * message,  // A message to send to everyone.
    int reportingOptions  // Bitfield flags used to set reporting options.
);
 
/*********
** KEYS **
*********/
// Set global keys on the local player.
void peerSetGlobalKeysA
(
    PEER peer,  // The peer object.
    int num,  // The number of keys to set.
    const char ** keys,  // The keys to set.
    const char ** values  // The values for the keys.
);
 
 
// Get a player's global keys.
void peerGetPlayerGlobalKeysA
(
    PEER peer,  // The peer object.
    const char * nick,  // The player to get the keys for.
    int num,  // The number of keys.
    const 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 peerGetRoomGlobalKeysA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room to get the keys in.
    int num,  // The number of keys.
    const 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 peerSetRoomKeysA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room to set the keys in.
    const char * nick,  // The player to set the keys on (NULL or "" for the room).
    int num,  // The number of keys.
    const char ** keys,  // The keys to set.
    const char ** values  // The values to set.
);
 
// 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 peerGetRoomKeysA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room to get the keys in.
    const char * nick,  // The player to get the keys for.
    int num,  // The number of keys.
    const 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 peerSetGlobalWatchKeysA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The type of room to set the watch keys for.
    int num,  // The number of keys.
    const 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 peerSetRoomWatchKeysA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The type of room to set the watch keys for.
    int num,  // The number of keys.
    const 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 char * peerGetGlobalWatchKeyA
(
    PEER peer,  // The peer object.
    const char * nick,  // The player to get the key for.
    const 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 char * peerGetRoomWatchKeyA
(
    PEER peer,  // The peer object.
    RoomType roomType,  // The room to get the key in.
    const char * nick,  // The player to get the key for.
    const char * key  // The key to get.
);
 
/**************
** AUTOMATCH **
**************/
 
// 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 peerStartAutoMatchA
(
    PEER peer,  // The peer object.
    int maxPlayers,  // The total number of players to match (including the local player).
    const 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 peerStartAutoMatchWithSocketA
(
    PEER peer,  // The peer object.
    int maxPlayers,  // The total number of players to match (including the local player).
    const 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.
);
 
 
#ifdef __cplusplus
}
#endif
 
#endif