1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: ac_API.h 4 5 Copyright 2009 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:: 2010-09-13#$ 14 $Rev: 25689 $ 15 $Author: niwa_kazutomo $ 16 *---------------------------------------------------------------------------*/ 17 18 #ifndef NN_AC_CTR_AC_API_H_ 19 #define NN_AC_CTR_AC_API_H_ 20 21 /*! @file 22 @brief AC に関する API の宣言 23 */ 24 25 #include <nn/os/os_Event.h> 26 #include <nn/ac/ac_Result.h> 27 #include <nn/ac/CTR/ac_Types.h> 28 29 #ifdef __cplusplus 30 31 #include <nn/ac/CTR/ac_Ac.h> 32 33 namespace nn { 34 namespace ac { 35 namespace CTR { 36 37 /*! 38 @brief 自動接続の初期化をします。 39 40 内部で参照カウンターを持っていますので、<BR> 41 多重で本関数を呼び出してもエラーにはなりませんが、<BR> 42 同じ回数 @ref Finalize を呼び出してください。<BR> 43 44 @return 結果 45 */ 46 Result Initialize(); 47 48 /*! 49 @brief 自動接続の開放処理をします。 50 51 @return 結果 52 */ 53 Result Finalize(); 54 55 /*! 56 @brief 自動接続が初期化済みかを取得します。 57 58 @return 結果 59 */ 60 bool IsInitialized(); 61 62 /*! 63 @brief 一般的な接続条件を生成します。 64 65 通常、アプリケーションは確保した Config をこの関数に渡し、<BR> 66 そのまま @ref Connect の引数に指定してください。<BR> 67 <BR> 68 configのフォーマットは将来システムアップデートによって変更される可能性があります。<BR> 69 中身を書き換えるようなコーディングは避けてください。<BR> 70 71 @param[out] config 接続条件インスタンス 72 73 @return 結果 74 */ 75 Result CreateDefaultConfig( Config* config ); 76 77 /*! 78 @brief ネットワーク接続要求のレベルを指定します。 79 80 @ref NETWORK_AREA_WAN を指定した場合は、インターネットに接続されている場合[WAN Connected]ステータスで成功します。<BR> 81 @ref NETWORK_AREA_LAN を指定した場合は、アクセスポイントに接続できた段階で[LAN Connected]ステータスで成功します。<BR> 82 @ref NETWORK_AREA_AUTO を指定した場合は、インターネットに接続されているか検証しますが、<BR> 83 インターネットに接続できていなくても[LAN Connected]ステータスで成功します。<BR> 84 インターネット接続できていた場合は[WAN Connected]ステータスで成功します。<BR> 85 <BR> 86 本関数はデバッグ用関数です。Releaseビルドでは動作しませんのでご注意ください。<BR> 87 88 @param[in] config 接続条件インスタンス 89 @param[in] networkArea ネットワーク接続要求レベル 90 91 @return 結果 92 */ 93 Result DebugSetNetworkArea( Config* config, NetworkArea networkArea ); 94 95 /*! 96 @brief 自動接続を開始します。 97 98 接続完了後、APから意図せず切断された時には<BR> 99 @ref nn::ac::RegisterDisconnectEvent で登録した @ref nn::os::LightEvent がシグナルします。<BR> 100 101 @param[in] config 接続条件インスタンス 102 103 @return 結果 104 */ 105 Result Connect( Config& config ); 106 107 /*! 108 @brief 非同期で自動接続を開始します。 109 110 処理の成功・失敗に関わらず、処理が終了した段階で<BR> 111 引数に指定した @ref nn::os::Event がシグナルします。<BR> 112 113 接続完了後、APから意図せず切断された時には<BR> 114 @ref nn::ac::RegisterDisconnectEvent で登録した @ref nn::os::Event がシグナルします。<BR> 115 116 @param[in] config 接続条件インスタンス 117 @param[in] event 処理の完了を通知する初期化済み @ref nn::os::Event 118 119 @return 結果 120 */ 121 Result ConnectAsync( Config& config, os::Event* event ); 122 123 /*! 124 @brief 非同期で自動接続処理中の場合、処理をキャンセルします。 125 126 キャンセルしたときには、Result にはキャンセルされたことを示す値が返ります。<BR> 127 @ref GetLastErrorCode で取得できるエラーコードは、キャンセルされたタイミングで失敗した相当のエラーコードが返ります。<BR> 128 キャンセルされたかの確認には Result の値を使うようにしてください。<BR> 129 <BR> 130 キャンセルが成功するか、キャンセルが受け入れられるまでに接続処理が終了した場合は<BR> 131 @ref ConnectAsync で渡した @ref nn::os::Event がシグナルし、@ref GetConnectResult でキャンセルされたことを取得できます。 132 @ref Connect 実行中に他スレッドから実行した場合は、@ref Connect の戻り値からキャンセルされたことを取得できます。 133 134 @return 結果 135 */ 136 Result CancelConnectAsync(); 137 138 /*! 139 @brief 非同期で自動接続を行った際の処理結果を取得します。 140 141 @ref ConnectAsync で接続処理を行った場合、<BR> 142 @ref nn::os::Event がシグナルしたら、この関数を利用して結果を確認してください。<BR> 143 144 @return 結果 145 */ 146 Result GetConnectResult(); 147 148 /*! 149 @brief 現在接続中のアクセスポイントとの電波強度を取得します。 150 151 本関数は毎フレーム呼び出すには重い処理です。<BR> 152 必要に応じて呼び出し間隔を調整するようにしてください。<BR> 153 154 @param[out] linkLevel 電波強度 @ref LinkLevel 155 156 @return 結果 157 */ 158 Result GetLinkLevel( LinkLevel* linkLevel ); 159 160 /*! 161 @brief 現在接続中のアクセスポイントとの電波強度を取得します。 162 163 本関数は毎フレーム呼び出すには重い処理です。<BR> 164 必要に応じて呼び出し間隔を調整するようにしてください。<BR> 165 166 @return 電波強度 @ref LinkLevel 167 */ 168 LinkLevel GetLinkLevel(); 169 170 /*! 171 @brief ネットワーク設定1に設定を反映します。 172 <BR> 173 本関数はデバッグ用関数です。Releaseビルドでは動作しませんのでご注意ください。<BR> 174 175 @param[in] ssid アクセスポイントのSSID 176 @param[in] ssidLength アクセスポイントのSSID長 177 @param[in] securityMode アクセスポイントの暗号化方式 178 @param[in] key アクセスポイントの暗号化鍵 179 @param[in] keyLen アクセスポイントの暗号化鍵長 180 181 @return 結果 182 */ 183 Result DebugSetNetworkSetting1( const u8 ssid[], u8 ssidLength, SecurityMode securityMode, const u8 key[], u8 keyLen ); 184 185 /*! 186 @brief 自動接続によって確立した接続を切断します。 187 188 本関数を呼び出した時に、他のプロセスがインターネット接続を利用していた場合、<BR> 189 @ref GetStatus で取得できるステートがアイドルになることは保障されません。<BR> 190 切断出来たかの確認は戻り値で判断してください。<BR> 191 192 @return 結果 193 */ 194 Result Close(); 195 196 /*! 197 @brief 非同期で自動接続によって確立した接続を切断します。 198 199 処理の成功・失敗に関わらず、処理が終了した段階で<BR> 200 引数に指定した @ref nn::os::Event がシグナルします。<BR> 201 202 @param[in] event 処理の完了を通知する初期化済み @ref nn::os::Event 203 204 @return 結果 205 */ 206 Result CloseAsync( os::Event* event ); 207 208 /*! 209 @brief 非同期で自動接続によって確立した接続を切断した際の処理結果を取得します。 210 211 @ref CloseAsync で接続処理を行った場合、<BR> 212 @ref nn::os::Event がシグナルしたら、この関数を利用して結果を確認してください。<BR> 213 214 @return 結果 215 */ 216 Result GetCloseResult(); 217 218 /*! 219 @brief 自動接続で最後に発生したエラーのエラーコードを取得します。 220 221 エラーコードの詳細については別途資料を参考にしてください。<BR> 222 223 @param[out] errorCode エラーコードを書き出す変数 224 225 @return 結果 226 */ 227 Result GetLastErrorCode( u32* errorCode ); 228 229 /*! 230 @brief 自動接続で最後に発生したエラーの詳細なエラーコードを取得します。 231 232 本エラーコードはACライブラリのサポートで利用します。<BR> 233 一般のゲーム開発では使用しないようにしてください。<BR> 234 235 @param[out] errorCode エラーコードを書き出す変数 236 237 @return 結果 238 */ 239 Result GetLastDetailErrorCode( u32* errorCode ); 240 241 /*! 242 @brief 自動接続の現在のステータスを取得します。 243 244 本関数は毎ゲームフレーム呼び出すには重い処理です。<BR> 245 APとの切断を検出したい場合は @ref RegisterDisconnectEvent を使ってください。<BR> 246 <BR> 247 システムがバックグラウンドでインフラ接続を利用中の場合、<BR> 248 アプリケーションが切断しても STATUS_IDLE に戻らない事があります。<BR> 249 このように、ステートはシステムの利用状況により意図した動作をしないことがありますので、<BR> 250 ステートを監視してアプリケーションの遷移を制御するのは危険ですので避けてください。<BR> 251 252 @param[out] status ステータスを書き出す変数 253 254 @return 結果 255 */ 256 Result GetStatus( Status* status ); 257 258 /*! 259 @brief 自動接続の現在のステータスを取得します。 260 261 本関数は毎ゲームフレーム呼び出すには重い処理です。<BR> 262 APとの切断を検出したい場合は @ref RegisterDisconnectEvent を使ってください。<BR> 263 <BR> 264 システムがバックグラウンドでインフラ接続を利用中の場合、<BR> 265 アプリケーションが切断しても STATUS_IDLE に戻らない事があります。<BR> 266 このように、ステートはシステムの利用状況により意図した動作をしないことがありますので、<BR> 267 ステートを監視してアプリケーションの遷移を制御するのは危険ですので避けてください。<BR> 268 269 @return ステータス 270 */ 271 Status GetStatus(); 272 273 /*! 274 @brief 現在接続中のアクセスポイントの種類を取得します。 275 276 @param[out] apType アクセスポイントの種類を書き出す変数 277 278 @return 結果 279 */ 280 Result GetConnectingApType( ApType* apType ); 281 282 /*! 283 @brief 現在接続しているニンテンドーゾーンの情報を取得します。 284 285 @param[out] beacon ゾーンビーコンを書き出すポインタ 286 287 @return 結果 288 */ 289 Result GetConnectingNintendoZoneBeaconSubset( NintendoZoneBeaconSubset* beacon ); 290 291 /*! 292 @brief AP切断時に通知される @ref nn::os::Event を設定します。 293 294 @param[out] event 通知を受ける初期化済み @ref nn::os::Event のポインタ 295 296 @return 結果 297 */ 298 Result RegisterDisconnectEvent(nn::os::Event* event); 299 300 /*! 301 @brief ACのステート変化時に通知される @ref nn::os::Event を設定します。 302 303 @ref GetStatus の補足説明のとおり、 304 アプリケーションからみたステート遷移が意図したとおりに遷移しない可能性があるため<BR> 305 ステートを監視してアプリケーションの遷移を制御すること危険ですので避けてください。<BR> 306 307 @param[out] event 通知を受ける未初期化 @ref nn::os::Event のポインタ 308 309 @return 結果 310 */ 311 Result GetStatusChangeEvent( nn::os::Event* event ); 312 313 namespace 314 { 315 const char PORT_NAME_USER[] = "ac:u"; 316 } 317 } 318 } 319 } 320 321 #endif // __cplusplus 322 323 // 以下、C 用宣言 324 325 #include <nn/util/detail/util_CLibImpl.h> 326 327 /*! 328 @addtogroup nn_ac ac 329 330 @brief @ref nn::ac の C インタフェースモジュールです。 331 332 @{ 333 */ 334 335 /*! 336 @brief 対応する C++ 関数 @ref nn::ac::CTR::Initialize を参照してください。 337 */ 338 NN_EXTERN_C nnResult nnacInitialize(void); 339 340 /*! 341 @brief 対応する C++ 関数 @ref nn::ac::CTR::Finalize を参照してください。 342 */ 343 NN_EXTERN_C nnResult nnacFinalize(void); 344 345 /*! 346 @brief 対応する C++ 関数 @ref nn::ac::CTR::CreateDefaultConfig を参照してください。 347 */ 348 NN_EXTERN_C nnResult nnacCreateDefaultConfig( nnacConfig* config ); 349 350 /*! 351 @brief 対応する C++ 関数 @ref nn::ac::CTR::DebugSetNetworkArea を参照してください。 352 */ 353 NN_EXTERN_C nnResult nnacDebugSetNetworkArea( nnacConfig* config, nnacNetworkArea networkArea ); 354 355 /*! 356 @brief 対応する C++ 関数 @ref nn::ac::CTR::Connect を参照してください。 357 */ 358 NN_EXTERN_C nnResult nnacConnect( nnacConfig* config ); 359 360 /*! 361 @brief 対応する C++ 関数 @ref nn::ac::CTR::ConnectAsync を参照してください。 362 */ 363 NN_EXTERN_C nnResult nnacConnectAsync( nnacConfig* config, nnosEvent* event ); 364 365 /*! 366 @brief 対応する C++ 関数 @ref nn::ac::CTR::CancelConnectAsync を参照してください。 367 */ 368 NN_EXTERN_C nnResult nnacCancelConnectAsync(void); 369 370 /*! 371 @brief 対応する C++ 関数 @ref nn::ac::CTR::GetConnectResult を参照してください。 372 */ 373 NN_EXTERN_C nnResult nnacGetConnectResult(void); 374 375 /*! 376 @brief 対応する C++ 関数 @ref nn::ac::CTR::DebugSetNetworkSetting1 を参照してください。 377 */ 378 NN_EXTERN_C nnResult nnacDebugSetNetworkSetting1( const u8 ssid[], u8 ssidLength, nnacSecurityMode securityMode, const u8 key[], u8 keyLen ); 379 380 /*! 381 @brief 対応する C++ 関数 @ref nn::ac::CTR::DebugFlushNetworkSetting を参照してください。 382 */ 383 NN_EXTERN_C nnResult nnacDebugFlushNetworkSetting(void); 384 385 /*! 386 @brief 対応する C++ 関数 @ref nn::ac::CTR::Close を参照してください。 387 */ 388 NN_EXTERN_C nnResult nnacClose(void); 389 390 /*! 391 @brief 対応する C++ 関数 @ref nn::ac::CTR::CloseAsync を参照してください。 392 */ 393 NN_EXTERN_C nnResult nnacCloseAsync( nnosEvent* event ); 394 395 /*! 396 @brief 対応する C++ 関数 @ref nn::ac::CTR::GetCloseResult を参照してください。 397 */ 398 NN_EXTERN_C nnResult nnacGetCloseResult(void); 399 400 /*! 401 @brief 対応する C++ 関数 @ref nn::ac::CTR::GetStatus を参照してください。 402 */ 403 NN_EXTERN_C nnResult nnacGetStatus( nnacStatus* status ); 404 405 /*! 406 @brief 対応する C++ 関数 @ref nn::ac::CTR::GetLinkLevel を参照してください。 407 */ 408 NN_EXTERN_C nnResult nnacGetLinkLevel( nnacLinkLevel* linkLevel ); 409 410 /*! 411 @brief 対応する C++ 関数 @ref nn::ac::CTR::GetLastErrorCode を参照してください。 412 */ 413 NN_EXTERN_C nnResult nnacGetLastErrorCode( u32* errorCode ); 414 415 /*! 416 @brief 対応する C++ 関数 @ref nn::ac::CTR::GetLastDetailErrorCode を参照してください。 417 */ 418 NN_EXTERN_C nnResult nnacGetLastDetailErrorCode( u32* errorCode ); 419 420 /*! 421 @brief 対応する C++ 関数 @ref nn::ac::CTR::GetConnectingApType を参照してください。 422 */ 423 NN_EXTERN_C nnResult nnacGetConnectingApType( nnacApType* apType ); 424 425 /*! 426 @brief 対応する C++ 関数 @ref nn::ac::CTR::GetConnectingNintendoZoneBeaconSubset を参照してください。 427 */ 428 NN_EXTERN_C nnResult nnacGetConnectingNintendoZoneBeaconSubset( nnacNintendoZoneBeaconSubset* beacon ); 429 430 /*! 431 @brief 対応する C++ 関数 @ref nn::ac::CTR::RegisterDisconnectEvent を参照してください。 432 */ 433 NN_EXTERN_C nnResult nnacRegisterDisconnectEvent( nnosEvent* event ); 434 435 /*! 436 @brief 対応する C++ 関数 @ref nn::ac::CTR::GetStatusChaneEvent を参照してください。 437 */ 438 NN_EXTERN_C nnResult nnacGetStatusChaneEvent( nnosEvent* event ); 439 440 /*! 441 @} 442 */ 443 444 #endif // ifndef NN_AC_CTR_AC_API_H_ 445