1 /*---------------------------------------------------------------------------* 2 Project: RevolutionDWC public include file 3 File: ./match/dwc_match.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_MATCH_H_ 16 #define DWC_MATCH_H_ 17 18 19 #ifdef __cplusplus 20 extern "C" 21 { 22 #endif 23 24 //---------------------------------------------------------------------------- 25 // preprocessor switch 26 //---------------------------------------------------------------------------- 27 28 // Specifications call for terminating QR2 once matchmaking has ended when using matchmaking other than server-client matchmaking 29 #define DWC_QR2_ALIVE_DURING_MATCHING 30 31 // Depending on the situation, it's okay to start matchmaking even when there are no friends on the friend roster 32 #define DWC_MATCH_ACCEPT_NO_FRIEND 33 34 // Enable friend-limited friend specified peer matchmaking 35 #define DWC_LIMIT_FRIENDS_MATCH_VALID 36 37 //---------------------------------------------------------------------------- 38 // Define 39 //---------------------------------------------------------------------------- 40 41 /// Maximum number of simultaneous connections 42 #define DWC_MAX_CONNECTIONS 32 43 44 /** 45 * Starting value for game-defined keys 46 * 47 * Version: 1.4.20 Made definitions public 48 */ 49 #define DWC_QR2_GAME_KEY_START 100 50 51 /** 52 * Number of keys reserved by DWC 53 * 54 * Version: 1.4.20 Made definitions public 55 */ 56 #define DWC_QR2_RESERVED_KEYS (100-50) // 50 is originally from NUM_RESERVED_KEYS in qr2regkeys.h 57 #define DWC_MAX_REGISTERED_KEYS 254 // 254 is originally from NUM_RESERVED_KEYS in qr2regkeys.h 58 59 /** 60 * The maximum number of keys that can be used in the game (154) 61 * 62 * Version: 2.0.1 153->154 63 * Version: 1.4.21 Made definitions public 64 */ 65 #define DWC_QR2_GAME_RESERVED_KEYS (DWC_MAX_REGISTERED_KEYS-DWC_QR2_RESERVED_KEYS-DWC_QR2_RESERVED_KEYS) 66 67 //---------------------------------------------------------------------------- 68 // struct 69 //---------------------------------------------------------------------------- 70 71 //---------------------------------------------------------------------------- 72 // enum 73 //---------------------------------------------------------------------------- 74 75 /// Matchmaking state enumerator 76 typedef enum { 77 DWC_MATCH_STATE_INIT = 0, ///< Initial state 78 79 // Client state 80 DWC_MATCH_STATE_CL_WAITING, ///< Waiting 81 DWC_MATCH_STATE_CL_SEARCH_HOST, ///< Available host search state (only when friends are not specified) 82 DWC_MATCH_STATE_CL_WAIT_RESV, ///< Waiting on a response from the server for a reservation 83 DWC_MATCH_STATE_CL_SEARCH_EVAL_HOST,///< Searching for a (partner) host to evaluate 84 DWC_MATCH_STATE_CL_NN, ///< NAT negotiation in progress 85 DWC_MATCH_STATE_CL_GT2, ///< Establishing a GT2 connection 86 DWC_MATCH_STATE_CL_CANCEL_SYN, ///< Synchronization adjustment in progress for a server-client matchmaking cancellation 87 DWC_MATCH_STATE_CL_SYN, ///< Synchronization adjustment in progress for matchmaking completion 88 DWC_MATCH_STATE_CL_SVDOWN_1, ///< Searching for a downed server 89 DWC_MATCH_STATE_CL_SVDOWN_2, ///< Searching for a downed server 2 90 DWC_MATCH_STATE_CL_SVDOWN_3, ///< Searching for a downed server 3 91 DWC_MATCH_STATE_CL_SEARCH_GROUPID_HOST, ///< Search for a host from a group ID 92 93 // Server state 94 DWC_MATCH_STATE_SV_WAITING, ///< Waiting 95 DWC_MATCH_STATE_SV_OWN_NN, ///< NAT negotiation with client in progress 96 DWC_MATCH_STATE_SV_OWN_GT2, ///< Establishing GT2 connection with client 97 DWC_MATCH_STATE_SV_WAIT_CL_LINK, ///< Waiting for connection between clients to complete 98 DWC_MATCH_STATE_SV_CANCEL_SYN, ///< Waiting on a SYN-ACK during synchronization adjustment of a server-client matchmaking cancellation 99 DWC_MATCH_STATE_SV_CANCEL_SYN_WAIT, ///< Waiting for synchronization adjustment to complete for server-client matchmaking cancellation 100 DWC_MATCH_STATE_SV_SYN, ///< Waiting on a SYN-ACK during synchronization adjustment for matchmaking termination 101 DWC_MATCH_STATE_SV_SYN_WAIT, ///< Waiting on synchronization adjustment to complete for matchmaking termination 102 103 // Common states 104 DWC_MATCH_STATE_WAIT_CLOSE, ///< Waiting to finish closing a connection 105 DWC_MATCH_STATE_SEARCH_OWN, ///< Searching for this host's information (the previous name was DWC_MATCH_STATE_CL_SEARCH_OWN) 106 DWC_MATCH_STATE_SV_SYN_CLOSE_WAIT, ///< Time to wait after sending the CLOSE command 107 108 DWC_MATCH_STATE_NUM 109 } DWCMatchState; 110 111 /** 112 * Buffer length used by matchmaking connection conditions 113 * 114 * Version: 2.0.0 Newly added. 115 */ 116 #define DWC_CONNECTION_USERDATA_LEN 4 117 118 /// Matchmaking type enumerator 119 enum { 120 DWC_MATCH_TYPE_ANYBODY = 0, ///< Peer matchmaking with friend unspecified 121 DWC_MATCH_TYPE_FRIEND, ///< Peer matchmaking with friend specified 122 DWC_MATCH_TYPE_SC_SV, ///< Server-client matchmaking, server-side 123 DWC_MATCH_TYPE_SC_CL, ///< Server-client matchmaking, client-side 124 DWC_MATCH_TYPE_NUM 125 }; 126 127 /// Enumerated type for suspend callbacks 128 typedef enum { 129 DWC_SUSPEND_SUCCESS = 0, ///<normal end 130 DWC_SUSPEND_TIMEOUT, ///< Timed out (not currently used) 131 DWC_SUSPEND_NUM 132 }DWCSuspendResult; 133 134 /// Enumerated type for the connection structure 135 typedef enum{ 136 DWC_TOPOLOGY_TYPE_HYBRID = 0, ///< Hybrid 137 DWC_TOPOLOGY_TYPE_STAR, ///< Star 138 DWC_TOPOLOGY_TYPE_FULLMESH, ///< Full-mesh 139 DWC_TOPOLOGY_TYPE_NUM 140 }DWCTopologyType; 141 142 //---------------------------------------------------------------------------- 143 // typedef - function 144 //---------------------------------------------------------------------------- 145 /** 146 * Matchmaking completion callback 147 * 148 * Invoked when a connection has been established or cancelled, or an error has occurred, after a call to one of the following functions: DWC_ConnectToAnybodyAsync, DWC_ConnectToFriendsAsync, DWC_SetupGameServer, DWC_ConnectToGameServerAsync or DWC_ConnectToGameServerByGroupID. 149 * 150 * 151 * 152 * 153 * When an error occurs, all argument values except for error and param are undefined. 154 * 155 * This callback function can be configured by the following functions: DWC_ConnectToAnybodyAsync, DWC_ConnectToFriendsAsync, DWC_SetupGameServer, DWC_ConnectToGameServerAsync and DWC_ConnectToGameServerByGroupID. 156 * 157 * 158 * 159 * 160 * Combinations of values that the arguments can take 161 * 162 * When error == DWC_ERROR_NONE && cancel == FALSE 163 * 164 * 165 * self 166 * isServer 167 * Content 168 * 169 * 170 * TRUE 171 * TRUE 172 * 173 * None. 174 * 175 * 176 * 177 * TRUE 178 * FALSE 179 * 180 * The local host is a client and has successfully connected to the server and its network. 'index' is -1. 181 * 182 * 183 * 184 * FALSE 185 * TRUE 186 * None. 187 * 188 * 189 * FALSE 190 * FALSE 191 * 192 * The local host is a server or client, and another client has successfully connected to the server and its network. @n 193 * 'index' indicates the client's friend roster index. -1 If the client is not a friend. 194 * 195 * 196 * 197 * 198 * 199 * When error == DWC_ERROR_NONE && cancel == TRUE 200 * 201 * 202 * self 203 * isServer 204 * Content 205 * 206 * 207 * TRUE 208 * TRUE 209 * 210 * The local host is the server, and the local host cancelled the matchmaking. 'index' is -1. 211 * 212 * 213 * 214 * TRUE 215 * FALSE 216 * 217 * The local host is the client, and the local host cancelled the matchmaking. 'index' is -1. 218 * 219 * 220 * 221 * FALSE 222 * TRUE 223 * 224 * The local host is the client, and the server cancelled the matchmaking. 'index' will be the friend roster index of the server. 225 * 226 * 227 * 228 * FALSE 229 * FALSE 230 * 231 * The local host is either the server or the client, and another client cancelled matchmaking. @n 232 * 'index' indicates the client's friend roster index. -1 If the client is not a friend. 233 * 234 * 235 * 236 * 237 * Param: error: DWC error type 238 * Param: cancel: TRUE: Matchmaking ended with a cancellation 239 * FALSE: Not cancelled 240 * Param: self TRUE: Either connection of host to server was successful or the connection was cancelled. 241 * FALSE: Either another host connected to the server successfully, or the connection was cancelled. 242 * Param: isServer TRUE: When self = FALSE, the host that completed the above operation is a server 243 * FALSE: Either the host that completed the above operation is a client when self = FALSE, or self = TRUE 244 * Param: index When self = FALSE, the friend roster index for host that completed the above operation. 245 * If the host is not a friend or if self = TRUE, then it is -1. 246 * Param: param: Parameters for the callback 247 * 248 * See also: DWC_ConnectToAnybodyAsync 249 * See also: DWC_ConnectToFriendsAsync 250 * See also: DWC_SetupGameServer 251 * See also: DWC_ConnectToGameServerAsync 252 * See also: DWC_ConnectToGameServerByGroupID 253 * 254 * Version: 2.0.0 Revised to match changes to specifications used by all matchmaking types 255 * Version: 1.1.0 Corrected a table because it was in disarray 256 */ 257 typedef void (*DWCMatchedSCCallback)(DWCError error, BOOL cancel, BOOL self, BOOL isServer, int index, void* param); 258 259 /** 260 * Callback type that sends a notification of a started connection for newly connected clients 261 * 262 * Called when another client has started a new connection to the current network during matchmaking. 263 * 264 * 265 * Param: index: Friend roster index for the newly connected client. 266 * This is -1 if the newly connected client is not a friend. 267 * Param: param: Parameters for the callback 268 * 269 * See also: DWC_ConnectToAnybodyAsync 270 * See also: DWC_ConnectToFriendsAsync 271 * See also: DWC_SetupGameServer 272 * See also: DWC_ConnectToGameServerAsync 273 * See also: DWC_ConnectToGameServerByGroupID 274 * 275 * Version: 2.0.0 Revised to match changes to specifications used by all matchmaking types 276 */ 277 typedef void (*DWCNewClientCallback)(int index, void* param); 278 279 /** 280 * Player evaluation callback type 281 * 282 * Called each time a matchmaking candidate is found when performing peer matchmaking with friend specified/unspecified. 283 * The larger a player's return value here, the greater the chance that player will be selected as a connection target. 284 * 285 * 286 * You can get the values specified to the DWC_AddMatchKeyString and DWC_AddMatchKeyInt functions and use them as rating standards. 287 * 288 * 289 * It takes some time for the addition of a condition key to be propagated to the server. Therefore, even if the application sets the condition key, it will sometimes be determined to not exist and the default value will be returned. 290 * 291 * 292 * 293 * Param: index: Index for the player being evaluated. 294 * This must be passed to the function that gets the value of the matchmaking key. 295 * Param: param: Parameters for the callback 296 * 297 * Return value: Player evaluation value. If the value is zero or less, is not considered for matchmaking. 298 * 299 * See also: DWC_ConnectToFriendsAsync 300 * See also: DWC_ConnectToAnybodyAsync 301 * See also: DWC_AddMatchKeyString 302 * See also: DWC_AddMatchKeyInt 303 * See also: DWC_GetMatchStringValue 304 * See also: DWC_GetMatchIntValue 305 * 306 * Version: 1.4.20 Added a note stating that condition keys take time to be propagated to the server 307 */ 308 typedef int (*DWCEvalPlayerCallback)(int index, void* param); 309 310 /** 311 * Callback type for deciding matchmaking conditions 312 * 313 * This callback is invoked at the final stage of determining participation for a newly connected client, to request the application to make the decision. 314 * 315 * (This callback is not invoked when the number of players is full or requests are denied in the current state.) 316 * To determine if a newly connected client should be accepted, refer to the connection user data for newly connected clients that can be obtained from the newClientUserData argument, and the connection user data for connected clients that can be obtained using DWC_GetConnectionUserData. 317 * 318 * 319 * 320 * 321 * Param: newClientUserData: Pointer to the buffer that stores the value configured by a newly connected client using the DWC_ConnectToAnybodyAsync, DWC_ConnectToFriendsAsync, DWC_SetupGameServer, DWC_ConnectToGameServerAsync or DWC_ConnectToGameServerByGroupID function. 322 * 323 * 324 * 325 * 326 * The size of u8[DWC_CONNECTION_USERDATA_LEN]. 327 * Param: param: Parameters for the callback 328 * 329 * Return value: TRUE: Accept the newly connected client. 330 * Return value: FALSE: Reject the newly connected client. 331 * 332 * See also: DWC_ConnectToAnybodyAsync 333 * See also: DWC_ConnectToFriendsAsync 334 * See also: DWC_SetupGameServer 335 * See also: DWC_ConnectToGameServerAsync 336 * See also: DWC_ConnectToGameServerByGroupID 337 * 338 * Version: 2.0.0 Newly added. 339 */ 340 typedef BOOL (*DWCConnectAttemptCallback)(u8* newClientUserData, void* param); 341 342 /** 343 * Callback type for suspend completion 344 * 345 * This is specified by DWC_RequestSuspendMatchAsync and called when suspend processing completes. 346 * When 'result' is DWC_SUSPEND_SUCCESS, the suspend state will be set to 'suspend'. 347 * When 'result' is not DWC_SUSPEND_SUCCESS, suspend processing has failed. However, 'suspend' will keep the value passed in by DWC_RequestSuspendMatchAsync for reference. 348 * 349 * 350 * 351 * Param: result: The result of suspend processing. 352 * DWC_SUSPEND_SUCCESS: Completed with the suspend state set to 'suspend'. 353 * Value other than DWC_SUSPEND_SUCCESS: Suspend processing failed. 354 * Param: suspend: TRUE: Request-denied state 355 * FALSE: Request-accepted state 356 * The value specified by DWC_RequestSuspendMatchAsync will be passed unchanged. 357 * Param: data: Callback parameters 358 * 359 * See also: DWC_RequestSuspendMatchAsync 360 * 361 * Version: 2.0.0 Newly added. 362 */ 363 typedef void (*DWCSuspendCallback)(DWCSuspendResult result, BOOL suspend, void* data); 364 365 //---------------------------------------------------------------------------- 366 // Function - external 367 //---------------------------------------------------------------------------- 368 369 #ifdef DWC_QR2_ALIVE_DURING_MATCHING 370 BOOL DWC_RegisterMatchStatus ( void ); 371 #endif 372 BOOL DWC_CancelMatch ( void ); 373 BOOL DWC_CancelMatchAsync ( void ); 374 BOOL DWC_IsValidCancelMatch ( void ); 375 u8 DWC_AddMatchKeyInt ( u8 keyID, const char* keyString, const int* valueSrc ); 376 u8 DWC_AddMatchKeyString ( u8 keyID, const char* keyString, const char* valueSrc ); 377 int DWC_GetMatchIntValue ( int index, const char* keyString, int idefault ); 378 const char* DWC_GetMatchStringValue ( int index, const char* keyString, const char* sdefault ); 379 int DWC_GetLastMatchType ( void ); 380 DWCMatchState DWC_GetMatchState ( void ); 381 382 u32 DWC_GetGroupID(void); 383 384 // suspend processing 385 BOOL DWC_RequestSuspendMatchAsync(BOOL suspend, DWCSuspendCallback callback, void* data); 386 BOOL DWC_GetSuspendMatch(void); 387 388 // ConnUserData-related 389 BOOL DWC_GetConnectionUserData(u8 aid, u8* userData); 390 391 // For debugging 392 void DWC_SetDebugMeshNNRetryMax(int retryMax); 393 int DWC_GetDebugMeshNNRetryMax(void); 394 395 BOOL DWC_SetServerSearchRatio(int percentage); 396 int DWC_GetServerSearchRatio(); 397 398 #ifdef __cplusplus 399 } 400 #endif 401 402 403 #endif // DWC_MATCH_H_ 404