1 /*---------------------------------------------------------------------------* 2 Project: RevolutionDWC public include file 3 File: ./ranking/dwc_ranking.h 4 5 Copyright 2005-2008 Nintendo. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 *---------------------------------------------------------------------------*/ 14 15 #ifndef DWC_RNK_H_ 16 #define DWC_RNK_H_ 17 18 #ifdef __cplusplus 19 extern "C" 20 { 21 #endif 22 23 /* ------------------------------------------------------------------------- 24 Define 25 ------------------------------------------------------------------------- */ 26 27 /** 28 * The maximum size that can be used in the user-defined data 29 * 30 * Version: 1.4.0: Changed from 768 to 764 bytes due to server restrictions. 31 */ 32 #define DWC_RNK_DATA_MAX 764 33 34 /** 35 * The maximum value that can be designated as a category. 36 * 37 * Version: 1.4.5: Changed DWC_RNK_CATEGORY_MAX from 100 to 1000. 38 */ 39 #define DWC_RNK_CATEGORY_MAX 1000 40 41 /// Constant that shows the ascending and descending order of the ranking list to be obtained 42 enum{ 43 DWC_RNK_ORDER_ASC = 0, ///< Ascending order 44 DWC_RNK_ORDER_DES = 1 ///< Descending 45 }; 46 47 /** 48 * The upper limit of the maximum value of the ranking list to be obtained. 49 * 50 * Version: 1.4.5: Changed DWC_RNK_GET_MAX from 10 to 30. 51 */ 52 #define DWC_RNK_GET_MAX 30 53 54 /// Maximum number of friends 55 #define DWC_RNK_FRIENDS_MAX 64 56 57 58 /* ------------------------------------------------------------------------- 59 enum 60 ------------------------------------------------------------------------- */ 61 62 /** 63 * Error Codes 64 * 65 * Version: 1.4.10: Added DWC_RNK_PROCESS_TIMEOUT. 66 */ 67 typedef enum{ 68 69 DWC_RNK_SUCCESS = 0, ///< Success 70 DWC_RNK_IN_ERROR, ///< Error occurring 71 72 DWC_RNK_ERROR_INVALID_PARAMETER, ///< Invalid parameter 73 74 // 75 // DWC_RnkInitialize error value 76 // 77 DWC_RNK_ERROR_INIT_ALREADYINITIALIZED, ///< Already initialized 78 DWC_RNK_ERROR_INIT_INVALID_INITDATASIZE, ///< Invalid initialization data size 79 DWC_RNK_ERROR_INIT_INVALID_INITDATA, ///< Invalid initialization data 80 DWC_RNK_ERROR_INIT_INVALID_USERDATA, ///< Invalid user information 81 82 // 83 // DWC_RnkPutScoreAsync error value 84 // 85 DWC_RNK_ERROR_PUT_NOTREADY, ///< Not initialized 86 DWC_RNK_ERROR_PUT_INVALID_KEY, ///< Encryption key is invalid 87 DWC_RNK_ERROR_PUT_NOMEMORY, ///< insufficient memory 88 89 // 90 // DWC_RnkGetScoreAsync error value 91 // 92 DWC_RNK_ERROR_GET_NOTREADY, ///< Not initialized 93 DWC_RNK_ERROR_GET_INVALID_KEY, ///< Encryption key is invalid 94 DWC_RNK_ERROR_GET_NOMEMORY, ///< insufficient memory 95 96 // 97 // DWC_RnkCancelProcess error value 98 // 99 DWC_RNK_ERROR_CANCEL_NOTASK, ///< No process during asynchronous processing 100 101 // 102 // DWC_RnkProcess error value 103 // 104 DWC_RNK_PROCESS_NOTASK, ///< No process during asynchronous processing 105 DWC_RNK_PROCESS_TIMEOUT, ///< Timeout 106 107 // 108 // DWC_RnkGetResponse error value 109 // 110 DWC_RNK_ERROR_INVALID_MODE, ///< Invalid mode 111 DWC_RNK_ERROR_NOTCOMPLETED, ///< Communications not completed 112 DWC_RNK_ERROR_EMPTY_RESPONSE ///< Empty response 113 114 115 } DWCRnkError; 116 117 118 /** 119 * Module status 120 * 121 * Version: 1.4.10: Added DWC_RNK_STATE_TIMEOUT. 122 */ 123 typedef enum{ 124 125 DWC_RNK_STATE_NOTREADY = 0, ///< Uninitialized state 126 127 DWC_RNK_STATE_INITIALIZED, ///< Initialization complete 128 DWC_RNK_STATE_PUT_ASYNC, ///< Currently in PUT asynchronous processing 129 DWC_RNK_STATE_GET_ASYNC, ///< Currently in GET asynchronous processing 130 DWC_RNK_STATE_COMPLETED, ///< Complete 131 132 DWC_RNK_STATE_TIMEOUT, ///< Timeout 133 DWC_RNK_STATE_ERROR ///< Error occurred 134 135 } DWCRnkState; 136 137 138 /** 139 * Region Codes 140 * 141 * Version: 1.4.0: Added South Korea (DWC_RNK_REGION_KR). 142 * Version: 1.4.14: Added China (DWC_RNK_REGION_CH). 143 */ 144 typedef enum{ 145 146 DWC_RNK_REGION_JP = 0x01, ///< Japan 147 DWC_RNK_REGION_US = 0x02, ///< United States 148 DWC_RNK_REGION_EU = 0x04, ///< Europe 149 DWC_RNK_REGION_KR = 0x08, ///< Korea 150 DWC_RNK_REGION_CH = 0x10, ///< China 151 152 DWC_RNK_REGION_ALL = 0xff ///< World 153 154 } DWCRnkRegion; 155 156 157 /** 158 * DWC_RnkGetScoreAsync get mode. 159 * 160 * Version: 1.4.5: Added DWC_RNK_GET_MODE_NEAR_HI and DWC_RNK_GET_MODE_NEAR_LOW. 161 * Version: 1.4.8: Changed "The ranking is above/below" to "The ranking is high/low". 162 */ 163 typedef enum{ 164 165 DWC_RNK_GET_MODE_ORDER, ///< Ascending 166 DWC_RNK_GET_MODE_TOPLIST, ///< High scores 167 DWC_RNK_GET_MODE_NEAR, ///< Nearby scores 168 DWC_RNK_GET_MODE_FRIENDS, ///< Friend-specific ranking 169 DWC_RNK_GET_MODE_NEAR_HI, ///< Nearby scores (higher than one's own ranking) 170 DWC_RNK_GET_MODE_NEAR_LOW ///< Nearby scores (lower than one's own ranking) 171 172 } DWCRnkGetMode; 173 174 175 /* ------------------------------------------------------------------------- 176 typedef - function 177 ------------------------------------------------------------------------- */ 178 179 180 /* ------------------------------------------------------------------------- 181 struct 182 ------------------------------------------------------------------------- */ 183 184 /** 185 * Structure for storing score information 186 */ 187 typedef struct 188 { 189 190 u32 order; ///< Ascending 191 s32 pid; ///< GameSpy Profile ID 192 s32 score; ///< Score 193 DWCRnkRegion region; ///< Region code 194 u32 lastupdate; ///< The amount of time that has passed since the last update (in minutes) 195 196 u32 size; ///< userdata size (in bytes) 197 void* userdata; ///< Buffer for user-defined data 198 199 } 200 DWCRnkData; 201 202 /** 203 * Parameters specified in the get ranking mode 204 * 205 * Specifies the parameters for the get rank mode (DWC_RNK_GET_MODE_ORDER). 206 * This is a member of DWCRnkGetParam. 207 * 208 * See also: DWCRnkGetParam 209 * 210 * Version: 1.3.0: Fixed a typo: changed "seconds" (incorrect) to "minutes" (correct). 211 */ 212 typedef struct 213 { 214 215 u32 sort; ///< DWC_RNK_ORDER_ASC: Ascending order@n 216 ///< DWC_RNK_ORDER_DES: Descending order 217 u32 since; ///< How many minutes ago? 218 219 } 220 DWCRnkGetParam_order; 221 222 /** 223 * Parameters specified in the get top ranking list mode 224 * 225 * Specifies the parameters used for the get top ranking list mode (DWC_RNK_GET_MODE_TOPLIST). 226 * 227 * This is a member of DWCRnkGetParam. 228 * 229 * See also: DWCRnkGetParam 230 * 231 * Version: 1.3.0: Fixed a typo: changed "seconds" (incorrect) to "minutes" (correct). 232 */ 233 typedef struct 234 { 235 236 u32 sort; ///< DWC_RNK_ORDER_ASC: Ascending order@n 237 ///< DWC_RNK_ORDER_DES: Descending order 238 u32 limit; ///< The maximum number to get 239 u32 since; ///< How many minutes ago? 240 241 } 242 DWCRnkGetParam_toplist; 243 244 /** 245 * Parameters specified in the get nearby ranking list mode 246 * 247 * Specifies the parameters used for the get nearby ranking list mode (DWC_RNK_GET_MODE_NEAR). 248 * 249 * This is a member of DWCRnkGetParam. 250 * 251 * See also: DWCRnkGetParam 252 * 253 * Version: 1.3.0: Fixed a typo: changed "seconds" (incorrect) to "minutes" (correct). 254 */ 255 typedef struct 256 { 257 258 u32 sort; ///< DWC_RNK_ORDER_ASC: Ascending order@n 259 ///< DWC_RNK_ORDER_DES: Descending order 260 u32 limit; ///< The maximum number to get 261 u32 since; ///< How many minutes ago? 262 263 } 264 DWCRnkGetParam_nearby; 265 266 /** 267 * Parameters specified in the get friends ranking list mode 268 * 269 * Specifies the parameters used for the get friends ranking list mode (DWC_RNK_GET_MODE_FRIENDS). 270 * 271 * This is a member of DWCRnkGetParam. 272 * 273 * See also: DWCRnkGetParam 274 * 275 * Version: 1.3.0: Fixed a typo: changed "seconds" (incorrect) to "minutes" (correct). 276 */ 277 typedef struct 278 { 279 280 u32 sort; ///< DWC_RNK_ORDER_ASC: Ascending order@n 281 ///< DWC_RNK_ORDER_DES: Descending order 282 u32 limit; ///< The maximum number to get 283 u32 since; ///< How many minutes ago? 284 s32 friends[DWC_RNK_FRIENDS_MAX]; ///< Friend PID list 285 286 } 287 DWCRnkGetParam_friends; 288 289 /** 290 * Parameters designated with DWC_RnkGetScoreAsync 291 * 292 * These are the parameters specified when getting scores with DWC_RnkGetScoreAsync. 293 * Set the appropriate parameters depending on the "score get mode" specified with DWCRnkGetScoreAsync. 294 * 295 * 296 * See also: DWC_RnkGetScoreAsync 297 * 298 * Version: 1.4.5: Added an explanation concerning DWC_RNK_GET_MODE_NEAR_*. 299 */ 300 typedef struct 301 { 302 303 u32 size; ///< Size (in bytes) 304 ///< Specifies the size of the parameters depending on the mode. @n 305 ///< Example: Specify sizeof(DWCRnkGetParam_order) when in the mode of getting the ranking. 306 ///< 307 308 union{ 309 310 DWCRnkGetParam_order order; ///< Specified when the mode is DWC_RNK_GET_MODE_ORDER 311 DWCRnkGetParam_toplist toplist; ///< Specified when the mode is DWC_RNK_GET_MODE_TOPLIST 312 DWCRnkGetParam_nearby nearby; ///< Specified when the mode is DWC_RNK_GET_MODE_NEAR_* 313 DWCRnkGetParam_friends friends; ///< Specified when the mode is DWC_RNK_GET_MODE_FRIENDS 314 315 u32 data; ///< Use within the library 316 317 }; 318 319 } 320 DWCRnkGetParam; 321 322 323 /* ------------------------------------------------------------------------- 324 Function - external 325 ------------------------------------------------------------------------- */ 326 327 DWCRnkError DWC_RnkInitialize( const char* initdata, 328 const DWCUserData* userdata); 329 330 DWCRnkError DWC_RnkShutdown(); 331 332 DWCRnkError DWC_RnkPutScoreAsync( u32 category, 333 DWCRnkRegion region, 334 s32 score, 335 void* data, 336 u32 size ); 337 338 DWCRnkError DWC_RnkGetScoreAsync( DWCRnkGetMode mode, 339 u32 category, 340 DWCRnkRegion region, 341 DWCRnkGetParam* param ); 342 343 DWCRnkError DWC_RnkCancelProcess(); 344 345 DWCRnkError DWC_RnkProcess(); 346 347 DWCRnkState DWC_RnkGetState(); 348 349 // 350 // For obtaining response 351 // 352 DWCRnkError DWC_RnkResGetRow( DWCRnkData* out, 353 u32 index ); 354 355 DWCRnkError DWC_RnkResGetRowCount( u32* count ); 356 357 DWCRnkError DWC_RnkResGetOrder( u32* order ); 358 359 DWCRnkError DWC_RnkResGetTotal( u32* total ); 360 361 362 #ifdef __cplusplus 363 } 364 #endif 365 366 #endif // DWC_RNK_H_ 367