1 /*---------------------------------------------------------------------------* 2 Project: TwlSDK - WM - demos.Twl 3 File: wh.c 4 5 Copyright 2007-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 $Date:: 2008-09-17#$ 14 $Rev: 8557 $ 15 $Author: nishimoto_takashi $ 16 *---------------------------------------------------------------------------*/ 17 18 19 #ifndef __WMHIGH_H__ 20 #define __WMHIGH_H__ 21 22 #include "wh_config.h" 23 24 /* added from NITRO-SDK3.1RC (prior to that is always 1) */ 25 #if !defined(WH_MP_FREQUENCY) 26 #define WH_MP_FREQUENCY 1 27 #endif 28 29 // OFF if initializing by using WM_Initialize 30 // Set to ON if there is a need to individually use and precisely control WM_Init, WM_Enable, and WM_PowerOn. 31 // #define WH_USE_DETAILED_INITIALIZE 32 33 enum 34 { 35 WH_SYSSTATE_STOP, // Initial state 36 WH_SYSSTATE_IDLE, // Waiting 37 WH_SYSSTATE_SCANNING, // Scanning 38 WH_SYSSTATE_BUSY, // Connecting 39 WH_SYSSTATE_CONNECTED, // Completed connection (Communications are possible in this state) 40 WH_SYSSTATE_DATASHARING, // Completed connection, with data-sharing enabled 41 WH_SYSSTATE_KEYSHARING, // Completed connection, with key-sharing enabled 42 WH_SYSSTATE_MEASURECHANNEL, // Check the radio wave usage rate of the channel 43 WH_SYSSTATE_CONNECT_FAIL, // Connection to the parent device failed 44 WH_SYSSTATE_ERROR, // Error occurred 45 WH_SYSSTATE_FATAL, // A FATAL error has occurred 46 WH_SYSSTATE_NUM 47 }; 48 49 enum 50 { 51 WH_CONNECTMODE_MP_PARENT, // Parent device MP connection mode 52 WH_CONNECTMODE_MP_CHILD, // Child device MP connection mode 53 WH_CONNECTMODE_KS_PARENT, // Parent device key-sharing connection mode 54 WH_CONNECTMODE_KS_CHILD, // Child device key-sharing connection mode 55 WH_CONNECTMODE_DS_PARENT, // Parent device data-sharing connection mode 56 WH_CONNECTMODE_DS_CHILD, // Child device data-sharing connection mode 57 WH_CONNECTMODE_NUM 58 }; 59 60 enum 61 { 62 // Separate error codes 63 WH_ERRCODE_DISCONNECTED = WM_ERRCODE_MAX, // Disconnected from parent 64 WH_ERRCODE_PARENT_NOT_FOUND, // No parent 65 WH_ERRCODE_NO_RADIO, // Wireless cannot be used 66 WH_ERRCODE_LOST_PARENT, // Parent lost 67 WH_ERRCODE_NOMORE_CHANNEL, // Scan has finished on all channels 68 WH_ERRCODE_MAX 69 }; 70 71 typedef void (*WHStartScanCallbackFunc) (WMBssDesc *bssDesc); 72 73 /* Parent device receive buffer size */ 74 #define WH_PARENT_RECV_BUFFER_SIZE WM_SIZE_MP_PARENT_RECEIVE_BUFFER( WH_CHILD_MAX_SIZE, WH_CHILD_MAX, FALSE ) 75 /* Parent device send buffer size */ 76 #define WH_PARENT_SEND_BUFFER_SIZE WM_SIZE_MP_PARENT_SEND_BUFFER( WH_PARENT_MAX_SIZE, FALSE ) 77 78 /* Child device receive buffer size */ 79 #define WH_CHILD_RECV_BUFFER_SIZE WM_SIZE_MP_CHILD_RECEIVE_BUFFER( WH_PARENT_MAX_SIZE, FALSE ) 80 /* Child device send buffer size */ 81 #define WH_CHILD_SEND_BUFFER_SIZE WM_SIZE_MP_CHILD_SEND_BUFFER( WH_CHILD_MAX_SIZE, FALSE ) 82 83 /* Macro that defines the GGID reserved for the SDK sample demo */ 84 #define SDK_MAKEGGID_SYSTEM(num) (0x003FFF00 | (num)) 85 86 /* Bitmap value indicating that either there is no connection or only a parent device */ 87 #define WH_BITMAP_EMPTY 1 88 89 // Send callback type (for data-sharing model) 90 typedef void (*WHSendCallbackFunc) (BOOL result); 91 92 // Function type for making connection permission determinations (for multiboot model) 93 typedef BOOL (*WHJudgeAcceptFunc) (WMStartParentCallback *); 94 95 // Receive callback type 96 typedef void (*WHReceiverFunc) (u16 aid, u16 *data, u16 size); 97 98 // Function for generating a WEP key 99 typedef u16 (*WHParentWEPKeyGeneratorFunc) (u16 *wepkey, const WMParentParam *parentParam); 100 typedef u16 (*WHChildWEPKeyGeneratorFunc) (u16 *wepkey, const WMBssDesc *bssDesc); 101 102 103 104 /************************************************************************** 105 * The following functions modify various WH configuration values. 106 **************************************************************************/ 107 108 /*---------------------------------------------------------------------------* 109 Name: WH_SetGgid 110 111 Description: Sets the game's group ID. 112 Call before making a connection to the parent device. 113 114 Arguments: ggid The game group ID to configure. 115 116 Returns: None. 117 *---------------------------------------------------------------------------*/ 118 extern void WH_SetGgid(u32 ggid); 119 120 /*---------------------------------------------------------------------------* 121 Name: WH_SetSsid 122 123 Description: Sets the SSID specified during child connection. 124 Call before making a connection from the child device. 125 126 Arguments: ssid Buffer in which the SSID to be set has been stored. 127 length Data length of the SSID to be set. 128 If less than WM_SIZE_CHILD_SSID (24-byte), fill the subsequent whitespace with 0s. If more than WM_SIZE_CHILD_SSID, truncate. 129 130 131 Returns: None. 132 *---------------------------------------------------------------------------*/ 133 extern void WH_SetSsid(const void *ssid, u32 length); 134 135 /*---------------------------------------------------------------------------* 136 Name: WH_SetUserGameInfo 137 138 Description: Configures user-defined parent device information 139 Call before making a connection to the parent device. 140 141 Arguments: userGameInfo Pointer to user-defined parent device information 142 length Size of the user-defined parent device information 143 144 Returns: None. 145 *---------------------------------------------------------------------------*/ 146 extern void WH_SetUserGameInfo(u16 *userGameInfo, u16 length); 147 148 /*---------------------------------------------------------------------------* 149 Name: WH_SetDebugOutput 150 151 Description: Configures the function for outputting the debug character string. 152 153 Arguments: func Function for the set debug character string output. 154 155 Returns: None. 156 *---------------------------------------------------------------------------*/ 157 void WH_SetDebugOutput(void (*func) (const char *, ...)); 158 159 /*---------------------------------------------------------------------------* 160 Name: WH_SetParentWEPKeyGenerator 161 162 Description: Sets the function that generates WEP Key. 163 If this function is called, WEP will be used for authentication during connection. 164 Using a unique algorithm for each game application, it sets the parent and child to the same value before connection. 165 166 This function is for parents. 167 168 Arguments: func Pointer to the function that generates the WEP Key 169 If NULL is specified, WEP Key is not used 170 171 Returns: None. 172 *---------------------------------------------------------------------------*/ 173 extern void WH_SetParentWEPKeyGenerator(WHParentWEPKeyGeneratorFunc func); 174 175 /*---------------------------------------------------------------------------* 176 Name: WH_SetChildWEPKeyGenerator 177 178 Description: Sets the function that generates WEP Key. 179 If this function is called, WEP will be used for authentication during connection. 180 Using a unique algorithm for each game application, it sets the parent and child to the same value before connection. 181 182 This function is for children. 183 184 Arguments: func Pointer to the function that generates the WEP Key 185 If NULL is specified, WEP Key is not used 186 187 Returns: None. 188 *---------------------------------------------------------------------------*/ 189 extern void WH_SetChildWEPKeyGenerator(WHChildWEPKeyGeneratorFunc func); 190 191 /*---------------------------------------------------------------------------* 192 Name: WH_SetIndCallback 193 194 Description: Sets the callback function specified in the WM_SetIndCallback function called by WH_Initialize. 195 196 This function should be called before WH_Initialize is called. 197 If a callback function is not specified by this function, the default WH_IndicateHandler will be set as the callback. 198 199 200 Arguments: callback Call back for the indication notification specified by WM_SetIndCallback. 201 202 Returns: None. 203 *---------------------------------------------------------------------------*/ 204 void WH_SetIndCallback(WMCallbackFunc callback); 205 206 /*---------------------------------------------------------------------------* 207 Name: WH_SetSessionUpdateCallback 208 209 Description: This function registers callbacks that are invoked when connecting, disconnecting, and making a new child connection. 210 211 Arguments: callback: Callback to register 212 213 Returns: None. 214 *---------------------------------------------------------------------------*/ 215 void WH_SetSessionUpdateCallback(WMCallbackFunc callback); 216 217 /************************************************************************** 218 * The following wrapper functions get the low-level WM library state. 219 **************************************************************************/ 220 221 /* ---------------------------------------------------------------------- 222 Name: WH_GetLinkLevel 223 Description: Gets the radio reception strength. 224 Arguments: None. 225 Returns: Returns the numeric value of WMLinkLevel. 226 ---------------------------------------------------------------------- */ 227 extern int WH_GetLinkLevel(void); 228 229 /* ---------------------------------------------------------------------- 230 Name: WH_GetAllowedChannel 231 Description: Gets the bit pattern of channels that can be used for connection. 232 Arguments: None. 233 Returns: channel pattern 234 ---------------------------------------------------------------------- */ 235 extern u16 WH_GetAllowedChannel(void); 236 237 238 /************************************************************************** 239 * The following functions get the WH state. 240 **************************************************************************/ 241 242 /* ---------------------------------------------------------------------- 243 Name: WH_GetBitmap 244 Description: Gets the bit pattern for displaying the connection state. 245 Arguments: None. 246 Returns: bitmap pattern 247 ---------------------------------------------------------------------- */ 248 extern u16 WH_GetBitmap(void); 249 250 /* ---------------------------------------------------------------------- 251 Name: WH_GetSystemState 252 Description: Gets the WH internal state. 253 Arguments: None. 254 Returns: The internal state (WH_SYSSTATE_XXXX). 255 ---------------------------------------------------------------------- */ 256 extern int WH_GetSystemState(void); 257 258 /* ---------------------------------------------------------------------- 259 Name: WH_GetConnectMode 260 Description: Gets the connection information. 261 Arguments: None. 262 Returns: The connection information (WH_CONNECTMODE_XX_XXXX). 263 ---------------------------------------------------------------------- */ 264 extern int WH_GetConnectMode(void); 265 266 /* ---------------------------------------------------------------------- 267 Name: WH_GetLastError 268 Description: Gets the error code that most recently occurred. 269 Arguments: None. 270 Returns: The error code. 271 ---------------------------------------------------------------------- */ 272 extern int WH_GetLastError(void); 273 274 /*---------------------------------------------------------------------------* 275 Name: WH_PrintBssDesc 276 277 Description: Debug outputs the members of the WMBssDesc structure. 278 279 Arguments: info The pointer to the BssDesc to be debug output. 280 281 Returns: None. 282 *---------------------------------------------------------------------------*/ 283 extern void WH_PrintBssDesc(WMBssDesc *info); 284 285 286 /************************************************************************** 287 * The following functions perform channel-related processes. 288 **************************************************************************/ 289 290 /*---------------------------------------------------------------------------* 291 Name: WH_StartMeasureChannel 292 293 Description: Starts measuring the radio wave usage rate on every usable channel. 294 When measurement is complete, internally calculates the channel with the lowest usage rate, and transitions it to the WH_SYSSTATE_MEASURECHANNEL state. 295 296 297 Arguments: None. 298 299 Returns: None. 300 *---------------------------------------------------------------------------*/ 301 extern BOOL WH_StartMeasureChannel(void); 302 303 /*---------------------------------------------------------------------------* 304 Name: WH_GetMeasureChannel 305 306 Description: Returns the channel with the lowest usage rate from all the usable channels. 307 The WH_MeasureChannel operations must be complete and it must be in a WH_SYSSTATE_MEASURECHANNEL state. 308 309 When this function is called, the channel with the lowest use rate is returned and the state transitions to WH_SYSSTATE_IDLE. 310 311 312 Arguments: None. 313 314 Returns: The channel number of the usable channel with the lowest usage rate 315 *---------------------------------------------------------------------------*/ 316 extern u16 WH_GetMeasureChannel(void); 317 318 319 /************************************************************************** 320 * The following functions initialize wireless communication and move it into an enabled state. 321 **************************************************************************/ 322 323 /* ---------------------------------------------------------------------- 324 Name: WH_Initialize 325 Description: Performs initialization operations, and starts the initialization sequence. 326 Arguments: None. 327 Returns: TRUE if the sequence start was a success. 328 ---------------------------------------------------------------------- */ 329 extern BOOL WH_Initialize(void); 330 331 332 /*---------------------------------------------------------------------------* 333 Name: WH_TurnOnPictoCatch 334 335 Description: Enables the Pictochat Search feature. 336 This causes a callback function to be invoked when PictoChat is discovered while scanning with WH_StartScan. 337 338 339 Arguments: None. 340 341 Returns: None. 342 *---------------------------------------------------------------------------*/ 343 extern void WH_TurnOnPictoCatch(void); 344 345 /*---------------------------------------------------------------------------* 346 Name: WH_TurnOffPictoCatch 347 348 Description: Disables the Pictochat Search feature. 349 This makes it to be ignored, even if pictochat was found while scanning with WH_StartScan. 350 351 352 Arguments: None. 353 354 Returns: None. 355 *---------------------------------------------------------------------------*/ 356 extern void WH_TurnOffPictoCatch(void); 357 358 /*---------------------------------------------------------------------------* 359 Name: WH_StartScan 360 361 Description: Function for fetching the parent beacon 362 363 Arguments: callback - Sets the callback returned when the parent device is found. 364 365 macAddr - Specifies the MAC address for the connected parent 366 If 0xFFFFFF, all parents are searched for. 367 368 channel - Designate the channels on which to search for the parent. 369 If 0, all channels are searched. 370 371 Returns: None. 372 *---------------------------------------------------------------------------*/ 373 extern BOOL WH_StartScan(WHStartScanCallbackFunc callback, const u8 *macAddr, u16 channel); 374 375 /*---------------------------------------------------------------------------* 376 Name: WH_EndScan 377 378 Description: Function for fetching the parent beacon 379 380 Arguments: None. 381 382 Returns: None. 383 *---------------------------------------------------------------------------*/ 384 extern BOOL WH_EndScan(void); 385 386 /* ---------------------------------------------------------------------- 387 Name: WH_ParentConnect 388 Description: Starts the connection sequence. 389 Arguments: mode - If WH_CONNECTMODE_MP_PARENT, MP starts as a parent. 390 If WH_CONNECTMODE_DS_PARENT, DataSharing starts as a parent. 391 If WH_CONNECTMODE_KS_PARENT, KeySharing starts as a parent. 392 tgid - The parent device communications tgid 393 channel - The parent device communications channel 394 Returns: TRUE if the connection sequence is successful 395 ---------------------------------------------------------------------- */ 396 extern BOOL WH_ParentConnect(int mode, u16 tgid, u16 channel); 397 398 /* ---------------------------------------------------------------------- 399 Name: WH_ChildConnect 400 Description: Starts the connection sequence. 401 Arguments: mode - Start MP as the child if WH_CONNECTMODE_MP_CHILD. 402 Start DataSharing as the child if WH_CONNECTMODE_DS_CHILD. 403 Start KeySharing as the child if WH_CONNECTMODE_KS_CHILD. 404 bssDesc - The bssDesc of the parent device to connect to. 405 406 Returns: TRUE if the connection sequence is successful 407 ---------------------------------------------------------------------- */ 408 extern BOOL WH_ChildConnect(int mode, WMBssDesc *bssDesc); 409 410 /* ---------------------------------------------------------------------- 411 Name: WH_ChildConnectAuto 412 Description: Starts the child device connection sequence. 413 However, each type of setting specified with WH_ParentConnect or WH_ChildConnect is left to automatic internal processing. 414 415 Arguments: mode - Start MP as the child if WH_CONNECTMODE_MP_CHILD. 416 Start DataSharing as the child if WH_CONNECTMODE_DS_CHILD. 417 Start KeySharing as the child if WH_CONNECTMODE_KS_CHILD. 418 419 macAddr - Specifies the MAC address for the connected parent 420 If 0xFFFFFF, all parents are searched for. 421 422 channel - Designate the channels on which to search for the parent. 423 If 0, all channels are searched. 424 425 Returns: TRUE if the connection sequence is successful 426 ---------------------------------------------------------------------- */ 427 extern BOOL WH_ChildConnectAuto(int mode, const u8 *macAddr, u16 channel); 428 429 /*---------------------------------------------------------------------------* 430 Name: WH_SetJudgeAcceptFunc 431 432 Description: Sets the functions used to determine whether to accept the child device connection. 433 434 Arguments: Set the child device connection determination functions. 435 436 Returns: None. 437 *---------------------------------------------------------------------------*/ 438 extern void WH_SetJudgeAcceptFunc(WHJudgeAcceptFunc func); 439 440 441 /************************************************************************** 442 * The following functions perform direct MP communication using WH_DATA_PORT. 443 **************************************************************************/ 444 445 /* ---------------------------------------------------------------------- 446 Name: WH_SetReceiver 447 Description: Configures the data reception callback in the WH_DATA_PORT port. 448 Arguments: proc - Data reception callback 449 Returns: None. 450 ---------------------------------------------------------------------- */ 451 extern void WH_SetReceiver(WHReceiverFunc proc); 452 453 /* ---------------------------------------------------------------------- 454 Name: WH_SendData 455 Description: Starts sending data to the WH_DATA_PORT port. 456 (For MP communications. There is no need to call this function while data sharing, etc.) 457 Arguments: size - The data size 458 Returns: Returns TRUE if starting the send is successful. 459 ---------------------------------------------------------------------- */ 460 extern BOOL WH_SendData(const void *data, u16 datasize, WHSendCallbackFunc callback); 461 462 463 /************************************************************************** 464 * The following functions control data sharing communication. 465 **************************************************************************/ 466 467 /* ---------------------------------------------------------------------- 468 Name: WH_GetKeySet 469 Description: Reads the common key data. 470 Arguments: keyset - Designates the data storage destination 471 Returns: If it succeeds returns TRUE. 472 ---------------------------------------------------------------------- */ 473 extern BOOL WH_GetKeySet(WMKeySet *keyset); 474 475 /* ---------------------------------------------------------------------- 476 Name: WH_GetSharedDataAdr 477 Description: Calculates and gets the data address obtained from the machine with the designated aid from the shared data address. 478 479 Arguments: aid - The machine designation 480 Returns: NULL on failure. 481 ---------------------------------------------------------------------- */ 482 extern u16 *WH_GetSharedDataAdr(u16 aid); 483 484 /* ---------------------------------------------------------------------- 485 Name: WH_StepDS 486 Description: Proceeds to the next synchronized data sharing process. 487 If communication is performed every frame, this function must also be called every frame. 488 489 Arguments: data - The data to send 490 Returns: If it succeeds returns TRUE. 491 ---------------------------------------------------------------------- */ 492 extern BOOL WH_StepDS(const void *data); 493 494 /* ---------------------------------------------------------------------- 495 Name: WH_GetBitmapDS 496 Description: Gets a list of systems that have shared data. 497 Arguments: None. 498 Returns: bitmap 499 ---------------------------------------------------------------------- */ 500 extern u16 WH_GetBitmapDS(void); 501 502 /************************************************************************** 503 * The following functions end communication and transition to the initialized state. 504 **************************************************************************/ 505 506 /* ---------------------------------------------------------------------- 507 Name: WH_Reset 508 Description: Starts the reset sequence. 509 When this function is called, it resets regardless of the current state. 510 It is used for forced recovery from errors. 511 Arguments: None. 512 Returns: TRUE if the process successfully starts 513 ---------------------------------------------------------------------- */ 514 extern void WH_Reset(void); 515 516 /* ---------------------------------------------------------------------- 517 Name: WH_Finalize 518 Description: Starts the post-processing / end sequence. 519 When this function is called, the current state is referenced and an appropriate end sequence is executed. 520 521 This function is used in the normal end process (not WH_Reset). 522 Arguments: None. 523 Returns: None. 524 ---------------------------------------------------------------------- */ 525 extern void WH_Finalize(void); 526 527 /*---------------------------------------------------------------------------* 528 Name: WH_End 529 530 Description: Ends wireless communication. 531 532 Arguments: None. 533 534 Returns: None. 535 *---------------------------------------------------------------------------*/ 536 extern BOOL WH_End(void); 537 538 /*---------------------------------------------------------------------------* 539 Name: WH_GetCurrentAid 540 541 Description: Gets its own current AID. 542 Children may change when they connect or disconnect. 543 544 Arguments: None. 545 546 Returns: AID value 547 *---------------------------------------------------------------------------*/ 548 extern u16 WH_GetCurrentAid(void); 549 550 #endif 551