OpenMoHAA 0.82.0
Loading...
Searching...
No Matches
gpersist.h
1/******
2gpersist.h
3GameSpy Persistent Storage SDK
4
5Copyright 1999-2007 GameSpy Industries, Inc
6
7******
8
9Please see the GameSpy Persistent Storage SDK for more info
10
11*****/
12//todo: get/set @ offset / length
13
14#ifndef _GPERSIST_H_
15#define _GPERSIST_H_
16
17#include "gstats.h"
18
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24/*************************
25The following defines and prototypes are included
26inside the "gstats.h" file, but listed here as well for easy reference
27since they are also used by the Persistent Storage SDK.
28The comments for them have also been changed to reflect their
29specific use inside the Persistent Storage SDK.
30**************************/
31#if 0
32 /* Error codes */
33 #define GE_NOERROR 0
34 #define GE_NOSOCKET 1 /* Unable to create a socket */
35 #define GE_NODNS 2 /* Unable to resolve a DNS name */
36 #define GE_NOCONNECT 3 /* Unable to connect to stats server, or connection lost */
37 #define GE_BUSY 4 /* Not used */
38 #define GE_DATAERROR 5 /* Bad data from the stats server */
39
40 /* You need to fill these in with your game-specific info */
41 extern char gcd_secret_key[256];
42 extern char gcd_gamename[256];
43
44 /********
45 InitStatsConnection
46
47 DESCRIPTION
48 Opens a connection to the stats / persistent storage server. Should be done before calling
49 any of the other persistent storage functions. May block for 1-2 secs
50 while the connection is established so you will want to do this before
51 gameplay starts or in another thread.
52
53 PARAMETERS
54 gameport: integer port associated with your server (may be the same as
55 your developer spec query port). If not appropriate for your game, pass in 0.
56
57 RETURNS
58 GE_NODNS: Unable to resolve stats server DNS
59 GE_NOSOCKET: Unable to create data socket
60 GE_NOCONNECT: Unable to connect to stats server
61 GE_DATAERROR: Unable to receive challenge from stats server, or bad challenge
62 GE_NOERROR: Connected to stats server and ready to send data
63
64 Note: If the connection fails, all Persistent Storage functions will fail.
65 *********/
66 int InitStatsConnection(int gameport);
67
68 /********
69 IsStatsConnected
70
71 DESCRIPTION
72 Returns whether or not you are currently connected to the stats server. Even
73 if your initial connection was successful, you may lose connection later and
74 want to try to reconnnect.
75 If a callback returns unsuccessfully, check this function to see if it was
76 because of a disconnection.
77
78 RETURNS
79 1 if connected, 0 otherwise
80 *********/
81 int IsStatsConnected();
82
83 /********
84 CloseStatsConnection
85
86 DESCRIPTION
87 Closes the connection to the stats server. You should do this when done
88 with the connection.
89 *********/
90 void CloseStatsConnection(void);
91
92 /********
93 GetChallenge
94
95 DESCRIPTION
96 Returns the string to pass as the challenge to the GenerateAuth function.
97
98 PARAMETERS
99 game: Pass in NULL (or your current game, if you are also using the Stats SDK)
100
101 RETURNS
102 A string to pass to GenerateAuth to create the authentication hash
103 *********/
104 char *GetChallenge(statsgame_t game);
105
106 /********
107 GenerateAuth
108
109 DESCRIPTION
110 Used to generate on the "challengeresponse" parameter for the PreAuthenticatePlayer
111 functions.
112
113 PARAMETERS
114 challenge: The challenge string generated by GetChallange.
115 password: The CD Key (un-hashed) or profile password
116 response: The output authentication string
117
118 RETURNS
119 A pointer to response
120 *********/
121 char *GenerateAuth(char *challenge, gsi_char *password,/*[out]*/char response[33]);
122#endif //#ifdef 0 section from gstats.h
123
124/*************************
125The rest of the prototypes in this file are specific to
126the Persistent Storage SDK
127**************************/
128
129#ifndef GSI_UNICODE
130#define GenerateAuth GenerateAuthA
131#define PreAuthenticatePlayerCD PreAuthenticatePlayerCDA
132#define GetProfileIDFromCD GetProfileIDFromCDA
133#define GetPersistDataValues GetPersistDataValuesA
134#define GetPersistDataValuesModified GetPersistDataValuesModifiedA
135#define SetPersistDataValues SetPersistDataValuesA
136#else
137#define GenerateAuth GenerateAuthW
138#define PreAuthenticatePlayerCD PreAuthenticatePlayerCDW
139#define GetProfileIDFromCD GetProfileIDFromCDW
140#define GetPersistDataValues GetPersistDataValuesW
141#define GetPersistDataValuesModified GetPersistDataValuesModifiedW
142#define SetPersistDataValues SetPersistDataValuesW
143#endif
144
145/********
146persisttype_t
147There are 4 types of persistent data stored for each player:
148pd_private_ro: Readable only by the authenticated client it belongs to, can only by set on the server
149pd_private_rw: Readable only by the authenticated client it belongs to, set by the authenticated client it belongs to
150pd_public_ro: Readable by any client, can only be set on the server
151pd_public_rw: Readable by any client, set by the authenicated client is belongs to
152*********/
153typedef enum {pd_private_ro, pd_private_rw, pd_public_ro, pd_public_rw} persisttype_t;
154
155/*****************
156CALLBACK FUNCTIONS
157*****************/
158
159/****************
160PersAuthCallbackFn
161
162DESCRIPTION
163This type of function is passed to the two PreAuthentication functions.
164It returns the result of the Authentication request.
165
166PARAMETERS
167localid: The localid number passed into the PreAuthenticate function
168profileid: If authentication was successful, the profileid for this user
169authenticated: 1 if the player was authenticated < 1 otherwise
170errmsg: Error returned by the server to indicate why the player was not authenticated
171instance: Opaque value passed into the PreAuthenticate function (for your use)
172*****************/
173typedef void (*PersAuthCallbackFn)(int localid, int profileid, int authenticated, gsi_char *errmsg, void *instance);
174
175
176/****************
177PersDataCallbackFn
178
179DESCRIPTION
180This type of function is passed to the two GetPersistData functions.
181It returns the result of the data request.
182localid
183
184PARAMETERS
185localid: The localid number passed into the GetPersistData function
186profileid: The profileid of the user who the data was requested for
187type: The type of persistent data being returned
188index: The persistent data index
189success: 1 if the data was retrieved successfully
190 2 if the data had not been modified since the time requested
191 < 1 if there was an error
192modified: The last time the data for this index was modified (any persist type)
193 Only returned if success is 1
194data: Pointer to the data being returned. Note: you must use or copy
195 off the data before returning from the callback, as it may be freed or overwritten
196 once the callback is complete.
197len: Length of the data being returned. 0 indicates that no data was stored on the server
198 (if success was 1)
199instance: Opaque value passed into the GetPersistData function (for your use)
200*****************/
201typedef void (*PersDataCallbackFn)(int localid, int profileid, persisttype_t type, int index, int success, time_t modified, char *data, int len, void *instance);
202
203/****************
204PersDataSaveCallbackFn
205
206DESCRIPTION
207This type of function is passed to the two SetPersistData functions.
208It returns the result of the set data request.
209
210PARAMETERS
211localid: The localid number passed into the SetPersistData function
212profileid: The profileid of the user who the data is being saved for
213success: 1 if the data was saved successfully, < 1 otherwise
214modified: The time recorded on the backend for last modification
215instance: Opaque value passed into the SetPersistData function (for your use)
216*****************/
217typedef void (*PersDataSaveCallbackFn)(int localid, int profileid, persisttype_t type, int index, int success, time_t modified, void *instance);
218
219/****************
220ProfileCallbackFn
221
222DESCRIPTION
223This type of function is passed to the GetProfileIDFromCD function.
224It returns the result of the lookup request.
225
226PARAMETERS
227localid: The localid number passed into the GetProfileIDFromCD function
228profileid: The profileid of the requested user, if the lookup was successful
229success: 1 if the lookup was successful, < 1 otherwise
230instance: Opaque value passed into the GetProfileIDFromCD function (for your use)
231*****************/
232typedef void (*ProfileCallbackFn)(int localid, int profileid, int success, void *instance);
233
234
235/***************************
236PERSISTENT STORAGE FUNCTIONS
237****************************/
238
239/****************
240PreAuthenticatePlayerPM
241PreAuthenticatePlayerCD
242
243DESCRIPTION
244These two functions are used to authenticate a player on the Stats server.
245A player MUST be authenticated before getting private persistent data, or
246setting public or private data.
247If the StatsServer connection is ever lost and reconnected (using InitStatsConnection)
248the player must be reauthenticated before reading / writing their data.
249PreAuthenticatePlayerPM authenticates players using the Presence & Messaging SDK account info
250PreAuthenticatePlayerCD authenticates players using the CDKey SDK CD Key.
251Typically you will only use one of these in your game (depending on whether you use
252the Presence & Messaging SDK, or the CD Key SDK), however they can both be used in the
253same game if needed.
254
255PARAMETERS
256localid: Your game-specific reference number for this player, returned in the callback
257 to allow you to identify which player it is referring to.
258profileid: (PreAuthenticatePlayerPM) The profileid of the player being authenicated. This can be obtained in the
259 Presence & Messaging SDK through gpIDFromProfile()
260nick: (PreAuthenticatePlayerCD) Nickname of the player to authenticate. Note that the nickname is not actually
261 authenticated, it is simply used to determine which profile under the authenticated CD Key to use.
262 Each CD Key can have mutiple profiles, each using a different nick.
263keyhash: (PreAuthenticatePlayerCD) Hash of the player's CD Key. If used on the server, this can be obtained from gcd_getkeyhash
264 On the client, you can easily get the hash by calling GenerateAuth() with challenge as an empty string ("")
265 and the CD Key has the password parameter.
266challengeresponse: Result of the GenerateAuth() call, after passing in the challenge and the client's
267 password or CD Key
268PersAuthCallbackFn: Callback to be called after the authentication is complete
269instance: Pointer that will be passed to the callback function (for your use)
270 Typically used for passing an object or structure pointer into the callback.
271*****************/
272void PreAuthenticatePlayerPartner(int localid, const char* authtoken, const char *challengeresponse, PersAuthCallbackFn callback, void *instance);
273void PreAuthenticatePlayerPM(int localid, int profileid, const char *challengeresponse, PersAuthCallbackFn callback, void *instance);
274void PreAuthenticatePlayerCD(int localid, const gsi_char *nick, const char *keyhash, const char *challengeresponse, PersAuthCallbackFn callback, void *instance);
275
276/****************
277GetProfileIDFromCD
278
279DESCRIPTION
280Given a nickname and CD Key hash, this will lookup the profileid for the user.
281If the user has never authenticated (and has no persistent data associated with them),
282the callback will indicate a failure. No persistent data can be retreived for the user,
283since they don't have any stored. Persistent data can be stored, but only after authenticating
284with PreAuthenticatePlayerCD.
285
286PARAMETERS
287localid: Your game-specific reference number for this player, returned in the callback
288 to allow you to identify which player it is referring to.
289nick: The nick of the user whose profileid you are looking up
290keyhash: The CD Key Hash of the user whose profileid you are looking up
291ProfileCallbackFn: Callback to be called when the lookup is completed
292instance: Pointer that will be passed to the callback function (for your use)
293*****************/
294void GetProfileIDFromCD(int localid, const gsi_char *nick, const char *keyhash, ProfileCallbackFn callback, void *instance);
295
296/****************
297GetPersistData[Modified]
298
299DESCRIPTION
300Gets the entire block of persistent data for a user.
301The data and length are returned in the callback function.
302Note that only an authenticated player can get their private data. Any
303player can get any other player's public data.
304
305PARAMETERS
306localid: Your game-specific reference number for this player, returned in the callback
307 to allow you to identify which player it is referring to.
308profileid: The profileid of the player whose data you are looking up.
309 Returned by gpIDFromProfile() in the Presence & Messaging SDK, or using GetProfileIDFromCD
310type: The type of persistent data you are looking up
311index: Each profile can have multiple persistent data records associated with them. Usually you
312 just want to use index 0.
313modifiedsince: A time value to limit the request for data. Data will only be returned if it has been
314 modified since the time provided. If data has not been modified since that time, the callback will be
315 called with a success value that indicates it is unmodified.
316 Note: modification time is tracked for the given profileid/index, not on a per persisttype basis
317PersDataCallbackFn: Callback that will be called with the data when it is returned
318ProfileCallbackFn: Callback to be called when the lookup is completed
319instance: Pointer that will be passed to the callback function (for your use)
320*****************/
321void GetPersistData(int localid, int profileid, persisttype_t type, int index, PersDataCallbackFn callback, void *instance);
322void GetPersistDataModified(int localid, int profileid, persisttype_t type, int index, time_t modifiedsince, PersDataCallbackFn callback, void *instance);
323
324/****************
325GetPersistDataValues[Modified]
326
327DESCRIPTION
328If you store your data in key\value delimited pairs, GetPersistDataValues will
329allow you to easily retrieve a subset of the stored data. To retrieve the entire
330data set, use GetPersistData. The data will be returned as a null-terminated string,
331unless no data is available (in which case len will be 0 in the callback).
332
333PARAMETERS
334localid: Your game-specific reference number for this player, returned in the callback
335 to allow you to identify which player it is referring to.
336profileid: The profileid of the player whose data you are looking up.
337 Returned by gpIDFromProfile() in the Presence & Messaging SDK, or using GetProfileIDFromCD
338type: The type of persistent data you are looking up
339index: Each profile can have multiple persistent data records associated with them. Usually you
340 just want to use index 0.
341modifiedsince: A time value to limit the request for data. Data will only be returned if it has been
342 modified since the time provided. If data has not been modified since that time, the callback will be
343 called with a success value that indicates it is unmodified.
344 Note: modification time is tracked for the given profileid/index, not on a per-persisttype or per-key basis
345keys: A "\" delimited list of the keys you want returned (for example: "\clan\color\homepage\birthday")
346PersDataCallbackFn: Callback that will be called with the data when it is returned
347instance: Pointer that will be passed to the callback function (for your use)
348*****************/
349void GetPersistDataValues(int localid, int profileid, persisttype_t type, int index, gsi_char *keys, PersDataCallbackFn callback, void *instance);
350void GetPersistDataValuesModified(int localid, int profileid, persisttype_t type, int index, time_t modifiedsince, gsi_char *keys, PersDataCallbackFn callback, void *instance);
351
352/****************
353SetPersistData
354
355DESCRIPTION
356Sets the entire block of persistent data for a user.
357The profileid for whom the data is being set MUST have been authenticated already.
358
359PARAMETERS
360localid: Your game-specific reference number for this player, returned in the callback
361 to allow you to identify which player it is referring to.
362profileid: The profileid of the player whose data you are setting.
363 The player must have already been authenticated with one of the PreAuthenticatePlayer functions.
364type: The type of persistent data you are setting. Only rw data is setable.
365index: Each profile can have multiple persistent data records associated with them. Usually you
366 just want to use index 0.
367data: The persistent data to be saved
368len: The length of the data. If you are setting key\value delimited data, make
369 sure the "len" parameter includes length of the null terminator
370PersDataSaveCallbackFn: Callback that will be called with the data save is complete
371instance: Pointer that will be passed to the callback function (for your use)
372*****************/
373void SetPersistData(int localid, int profileid, persisttype_t type, int index, const char *data, int len, PersDataSaveCallbackFn callback, void *instance);
374
375/****************
376SetPersistDataValues
377
378DESCRIPTION
379If you are saving data in key\value delimited format, you can use this function
380to only set SOME of the key\value pairs. Only the key value pairs you include in
381they keyvalues parameter will be updated, the other pairs will stay the same.
382
383PARAMETERS
384localid: Your game-specific reference number for this player, returned in the callback
385 to allow you to identify which player it is referring to.
386profileid: The profileid of the player whose data you are setting.
387 The player must have already been authenticated with one of the PreAuthenticatePlayer functions.
388type: The type of persistent data you are setting. Only rw data is setable.
389index: Each profile can have multiple persistent data records associated with them. Usually you
390 just want to use index 0.
391keyvalues: The key\value pairs to be updated (for example: \clan\The A-Team\homepage\http://www.myclan.net\age\15)
392PersDataSaveCallbackFn: Callback that will be called with the data save is complete
393instance: Pointer that will be passed to the callback function (for your use)
394*****************/
395void SetPersistDataValues(int localid, int profileid, persisttype_t type, int index, const gsi_char *keyvalues, PersDataSaveCallbackFn callback, void *instance);
396
397/****************
398PersistThink
399
400DESCRIPTION
401This function needs to be called any time a asynchronous operation is in progress. It will
402check for the incoming replies and call the callbacks associated with them as needed.
403It's recommened that you call this in your main loop at all times while you are connected
404to the stats server, so that if the stats server disconnects it can be detected immediately.
405
406RETURNS
4070 if the connection to the stats server is lost, 1 otherwise
408*****************/
409int PersistThink();
410
411#ifdef __cplusplus
412}
413#endif
414
415#endif