/****** gpersist.h GameSpy Persistent Storage SDK Copyright 1999-2007 GameSpy Industries, Inc ****** Please see the GameSpy Persistent Storage SDK for more info *****/ //todo: get/set @ offset / length #ifndef _GPERSIST_H_ #define _GPERSIST_H_ #include "gstats.h" #ifdef __cplusplus extern "C" { #endif /************************* The following defines and prototypes are included inside the "gstats.h" file, but listed here as well for easy reference since they are also used by the Persistent Storage SDK. The comments for them have also been changed to reflect their specific use inside the Persistent Storage SDK. **************************/ #if 0 /* Error codes */ #define GE_NOERROR 0 #define GE_NOSOCKET 1 /* Unable to create a socket */ #define GE_NODNS 2 /* Unable to resolve a DNS name */ #define GE_NOCONNECT 3 /* Unable to connect to stats server, or connection lost */ #define GE_BUSY 4 /* Not used */ #define GE_DATAERROR 5 /* Bad data from the stats server */ /* You need to fill these in with your game-specific info */ extern char gcd_secret_key[256]; extern char gcd_gamename[256]; /******** InitStatsConnection DESCRIPTION Opens a connection to the stats / persistent storage server. Should be done before calling any of the other persistent storage functions. May block for 1-2 secs while the connection is established so you will want to do this before gameplay starts or in another thread. PARAMETERS gameport: integer port associated with your server (may be the same as your developer spec query port). If not appropriate for your game, pass in 0. RETURNS GE_NODNS: Unable to resolve stats server DNS GE_NOSOCKET: Unable to create data socket GE_NOCONNECT: Unable to connect to stats server GE_DATAERROR: Unable to receive challenge from stats server, or bad challenge GE_NOERROR: Connected to stats server and ready to send data Note: If the connection fails, all Persistent Storage functions will fail. *********/ int InitStatsConnection(int gameport); /******** IsStatsConnected DESCRIPTION Returns whether or not you are currently connected to the stats server. Even if your initial connection was successful, you may lose connection later and want to try to reconnnect. If a callback returns unsuccessfully, check this function to see if it was because of a disconnection. RETURNS 1 if connected, 0 otherwise *********/ int IsStatsConnected(); /******** CloseStatsConnection DESCRIPTION Closes the connection to the stats server. You should do this when done with the connection. *********/ void CloseStatsConnection(void); /******** GetChallenge DESCRIPTION Returns the string to pass as the challenge to the GenerateAuth function. PARAMETERS game: Pass in NULL (or your current game, if you are also using the Stats SDK) RETURNS A string to pass to GenerateAuth to create the authentication hash *********/ char *GetChallenge(statsgame_t game); /******** GenerateAuth DESCRIPTION Used to generate on the "challengeresponse" parameter for the PreAuthenticatePlayer functions. PARAMETERS challenge: The challenge string generated by GetChallange. password: The CD Key (un-hashed) or profile password response: The output authentication string RETURNS A pointer to response *********/ char *GenerateAuth(char *challenge, gsi_char *password,/*[out]*/char response[33]); #endif //#ifdef 0 section from gstats.h /************************* The rest of the prototypes in this file are specific to the Persistent Storage SDK **************************/ #ifndef GSI_UNICODE #define GenerateAuth GenerateAuthA #define PreAuthenticatePlayerCD PreAuthenticatePlayerCDA #define GetProfileIDFromCD GetProfileIDFromCDA #define GetPersistDataValues GetPersistDataValuesA #define GetPersistDataValuesModified GetPersistDataValuesModifiedA #define SetPersistDataValues SetPersistDataValuesA #else #define GenerateAuth GenerateAuthW #define PreAuthenticatePlayerCD PreAuthenticatePlayerCDW #define GetProfileIDFromCD GetProfileIDFromCDW #define GetPersistDataValues GetPersistDataValuesW #define GetPersistDataValuesModified GetPersistDataValuesModifiedW #define SetPersistDataValues SetPersistDataValuesW #endif /******** persisttype_t There are 4 types of persistent data stored for each player: pd_private_ro: Readable only by the authenticated client it belongs to, can only by set on the server pd_private_rw: Readable only by the authenticated client it belongs to, set by the authenticated client it belongs to pd_public_ro: Readable by any client, can only be set on the server pd_public_rw: Readable by any client, set by the authenicated client is belongs to *********/ typedef enum {pd_private_ro, pd_private_rw, pd_public_ro, pd_public_rw} persisttype_t; /***************** CALLBACK FUNCTIONS *****************/ /**************** PersAuthCallbackFn DESCRIPTION This type of function is passed to the two PreAuthentication functions. It returns the result of the Authentication request. PARAMETERS localid: The localid number passed into the PreAuthenticate function profileid: If authentication was successful, the profileid for this user authenticated: 1 if the player was authenticated < 1 otherwise errmsg: Error returned by the server to indicate why the player was not authenticated instance: Opaque value passed into the PreAuthenticate function (for your use) *****************/ typedef void (*PersAuthCallbackFn)(int localid, int profileid, int authenticated, gsi_char *errmsg, void *instance); /**************** PersDataCallbackFn DESCRIPTION This type of function is passed to the two GetPersistData functions. It returns the result of the data request. localid PARAMETERS localid: The localid number passed into the GetPersistData function profileid: The profileid of the user who the data was requested for type: The type of persistent data being returned index: The persistent data index success: 1 if the data was retrieved successfully 2 if the data had not been modified since the time requested < 1 if there was an error modified: The last time the data for this index was modified (any persist type) Only returned if success is 1 data: Pointer to the data being returned. Note: you must use or copy off the data before returning from the callback, as it may be freed or overwritten once the callback is complete. len: Length of the data being returned. 0 indicates that no data was stored on the server (if success was 1) instance: Opaque value passed into the GetPersistData function (for your use) *****************/ typedef void (*PersDataCallbackFn)(int localid, int profileid, persisttype_t type, int index, int success, time_t modified, char *data, int len, void *instance); /**************** PersDataSaveCallbackFn DESCRIPTION This type of function is passed to the two SetPersistData functions. It returns the result of the set data request. PARAMETERS localid: The localid number passed into the SetPersistData function profileid: The profileid of the user who the data is being saved for success: 1 if the data was saved successfully, < 1 otherwise modified: The time recorded on the backend for last modification instance: Opaque value passed into the SetPersistData function (for your use) *****************/ typedef void (*PersDataSaveCallbackFn)(int localid, int profileid, persisttype_t type, int index, int success, time_t modified, void *instance); /**************** ProfileCallbackFn DESCRIPTION This type of function is passed to the GetProfileIDFromCD function. It returns the result of the lookup request. PARAMETERS localid: The localid number passed into the GetProfileIDFromCD function profileid: The profileid of the requested user, if the lookup was successful success: 1 if the lookup was successful, < 1 otherwise instance: Opaque value passed into the GetProfileIDFromCD function (for your use) *****************/ typedef void (*ProfileCallbackFn)(int localid, int profileid, int success, void *instance); /*************************** PERSISTENT STORAGE FUNCTIONS ****************************/ /**************** PreAuthenticatePlayerPM PreAuthenticatePlayerCD DESCRIPTION These two functions are used to authenticate a player on the Stats server. A player MUST be authenticated before getting private persistent data, or setting public or private data. If the StatsServer connection is ever lost and reconnected (using InitStatsConnection) the player must be reauthenticated before reading / writing their data. PreAuthenticatePlayerPM authenticates players using the Presence & Messaging SDK account info PreAuthenticatePlayerCD authenticates players using the CDKey SDK CD Key. Typically you will only use one of these in your game (depending on whether you use the Presence & Messaging SDK, or the CD Key SDK), however they can both be used in the same game if needed. PARAMETERS localid: Your game-specific reference number for this player, returned in the callback to allow you to identify which player it is referring to. profileid: (PreAuthenticatePlayerPM) The profileid of the player being authenicated. This can be obtained in the Presence & Messaging SDK through gpIDFromProfile() nick: (PreAuthenticatePlayerCD) Nickname of the player to authenticate. Note that the nickname is not actually authenticated, it is simply used to determine which profile under the authenticated CD Key to use. Each CD Key can have mutiple profiles, each using a different nick. keyhash: (PreAuthenticatePlayerCD) Hash of the player's CD Key. If used on the server, this can be obtained from gcd_getkeyhash On the client, you can easily get the hash by calling GenerateAuth() with challenge as an empty string ("") and the CD Key has the password parameter. challengeresponse: Result of the GenerateAuth() call, after passing in the challenge and the client's password or CD Key PersAuthCallbackFn: Callback to be called after the authentication is complete instance: Pointer that will be passed to the callback function (for your use) Typically used for passing an object or structure pointer into the callback. *****************/ void PreAuthenticatePlayerPartner(int localid, const char* authtoken, const char *challengeresponse, PersAuthCallbackFn callback, void *instance); void PreAuthenticatePlayerPM(int localid, int profileid, const char *challengeresponse, PersAuthCallbackFn callback, void *instance); void PreAuthenticatePlayerCD(int localid, const gsi_char *nick, const char *keyhash, const char *challengeresponse, PersAuthCallbackFn callback, void *instance); /**************** GetProfileIDFromCD DESCRIPTION Given a nickname and CD Key hash, this will lookup the profileid for the user. If the user has never authenticated (and has no persistent data associated with them), the callback will indicate a failure. No persistent data can be retreived for the user, since they don't have any stored. Persistent data can be stored, but only after authenticating with PreAuthenticatePlayerCD. PARAMETERS localid: Your game-specific reference number for this player, returned in the callback to allow you to identify which player it is referring to. nick: The nick of the user whose profileid you are looking up keyhash: The CD Key Hash of the user whose profileid you are looking up ProfileCallbackFn: Callback to be called when the lookup is completed instance: Pointer that will be passed to the callback function (for your use) *****************/ void GetProfileIDFromCD(int localid, const gsi_char *nick, const char *keyhash, ProfileCallbackFn callback, void *instance); /**************** GetPersistData[Modified] DESCRIPTION Gets the entire block of persistent data for a user. The data and length are returned in the callback function. Note that only an authenticated player can get their private data. Any player can get any other player's public data. PARAMETERS localid: Your game-specific reference number for this player, returned in the callback to allow you to identify which player it is referring to. profileid: The profileid of the player whose data you are looking up. Returned by gpIDFromProfile() in the Presence & Messaging SDK, or using GetProfileIDFromCD type: The type of persistent data you are looking up index: Each profile can have multiple persistent data records associated with them. Usually you just want to use index 0. modifiedsince: A time value to limit the request for data. Data will only be returned if it has been modified since the time provided. If data has not been modified since that time, the callback will be called with a success value that indicates it is unmodified. Note: modification time is tracked for the given profileid/index, not on a per persisttype basis PersDataCallbackFn: Callback that will be called with the data when it is returned ProfileCallbackFn: Callback to be called when the lookup is completed instance: Pointer that will be passed to the callback function (for your use) *****************/ void GetPersistData(int localid, int profileid, persisttype_t type, int index, PersDataCallbackFn callback, void *instance); void GetPersistDataModified(int localid, int profileid, persisttype_t type, int index, time_t modifiedsince, PersDataCallbackFn callback, void *instance); /**************** GetPersistDataValues[Modified] DESCRIPTION If you store your data in key\value delimited pairs, GetPersistDataValues will allow you to easily retrieve a subset of the stored data. To retrieve the entire data set, use GetPersistData. The data will be returned as a null-terminated string, unless no data is available (in which case len will be 0 in the callback). PARAMETERS localid: Your game-specific reference number for this player, returned in the callback to allow you to identify which player it is referring to. profileid: The profileid of the player whose data you are looking up. Returned by gpIDFromProfile() in the Presence & Messaging SDK, or using GetProfileIDFromCD type: The type of persistent data you are looking up index: Each profile can have multiple persistent data records associated with them. Usually you just want to use index 0. modifiedsince: A time value to limit the request for data. Data will only be returned if it has been modified since the time provided. If data has not been modified since that time, the callback will be called with a success value that indicates it is unmodified. Note: modification time is tracked for the given profileid/index, not on a per-persisttype or per-key basis keys: A "\" delimited list of the keys you want returned (for example: "\clan\color\homepage\birthday") PersDataCallbackFn: Callback that will be called with the data when it is returned instance: Pointer that will be passed to the callback function (for your use) *****************/ void GetPersistDataValues(int localid, int profileid, persisttype_t type, int index, gsi_char *keys, PersDataCallbackFn callback, void *instance); void GetPersistDataValuesModified(int localid, int profileid, persisttype_t type, int index, time_t modifiedsince, gsi_char *keys, PersDataCallbackFn callback, void *instance); /**************** SetPersistData DESCRIPTION Sets the entire block of persistent data for a user. The profileid for whom the data is being set MUST have been authenticated already. PARAMETERS localid: Your game-specific reference number for this player, returned in the callback to allow you to identify which player it is referring to. profileid: The profileid of the player whose data you are setting. The player must have already been authenticated with one of the PreAuthenticatePlayer functions. type: The type of persistent data you are setting. Only rw data is setable. index: Each profile can have multiple persistent data records associated with them. Usually you just want to use index 0. data: The persistent data to be saved len: The length of the data. If you are setting key\value delimited data, make sure the "len" parameter includes length of the null terminator PersDataSaveCallbackFn: Callback that will be called with the data save is complete instance: Pointer that will be passed to the callback function (for your use) *****************/ void SetPersistData(int localid, int profileid, persisttype_t type, int index, const char *data, int len, PersDataSaveCallbackFn callback, void *instance); /**************** SetPersistDataValues DESCRIPTION If you are saving data in key\value delimited format, you can use this function to only set SOME of the key\value pairs. Only the key value pairs you include in they keyvalues parameter will be updated, the other pairs will stay the same. PARAMETERS localid: Your game-specific reference number for this player, returned in the callback to allow you to identify which player it is referring to. profileid: The profileid of the player whose data you are setting. The player must have already been authenticated with one of the PreAuthenticatePlayer functions. type: The type of persistent data you are setting. Only rw data is setable. index: Each profile can have multiple persistent data records associated with them. Usually you just want to use index 0. keyvalues: The key\value pairs to be updated (for example: \clan\The A-Team\homepage\http://www.myclan.net\age\15) PersDataSaveCallbackFn: Callback that will be called with the data save is complete instance: Pointer that will be passed to the callback function (for your use) *****************/ void SetPersistDataValues(int localid, int profileid, persisttype_t type, int index, const gsi_char *keyvalues, PersDataSaveCallbackFn callback, void *instance); /**************** PersistThink DESCRIPTION This function needs to be called any time a asynchronous operation is in progress. It will check for the incoming replies and call the callbacks associated with them as needed. It's recommened that you call this in your main loop at all times while you are connected to the stats server, so that if the stats server disconnects it can be detected immediately. RETURNS 0 if the connection to the stats server is lost, 1 otherwise *****************/ int PersistThink(); #ifdef __cplusplus } #endif #endif