/*---------------------------------------------------------------------------* Project: Horizon File: ac_API.h Copyright 2009 Nintendo. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. $Date:: 2010-09-13#$ $Rev: 25689 $ $Author: niwa_kazutomo $ *---------------------------------------------------------------------------*/ #ifndef NN_AC_CTR_AC_API_H_ #define NN_AC_CTR_AC_API_H_ /*! @file @brief AC に関する API の宣言 */ #include #include #include #ifdef __cplusplus #include namespace nn { namespace ac { namespace CTR { /*! @brief 自動接続の初期化をします。 内部で参照カウンターを持っていますので、
多重で本関数を呼び出してもエラーにはなりませんが、
同じ回数 @ref Finalize を呼び出してください。
@return 結果 */ Result Initialize(); /*! @brief 自動接続の開放処理をします。 @return 結果 */ Result Finalize(); /*! @brief 自動接続が初期化済みかを取得します。 @return 結果 */ bool IsInitialized(); /*! @brief 一般的な接続条件を生成します。 通常、アプリケーションは確保した Config をこの関数に渡し、
そのまま @ref Connect の引数に指定してください。

configのフォーマットは将来システムアップデートによって変更される可能性があります。
中身を書き換えるようなコーディングは避けてください。
@param[out] config 接続条件インスタンス @return 結果 */ Result CreateDefaultConfig( Config* config ); /*! @brief ネットワーク接続要求のレベルを指定します。 @ref NETWORK_AREA_WAN を指定した場合は、インターネットに接続されている場合[WAN Connected]ステータスで成功します。
@ref NETWORK_AREA_LAN を指定した場合は、アクセスポイントに接続できた段階で[LAN Connected]ステータスで成功します。
@ref NETWORK_AREA_AUTO を指定した場合は、インターネットに接続されているか検証しますが、
インターネットに接続できていなくても[LAN Connected]ステータスで成功します。
インターネット接続できていた場合は[WAN Connected]ステータスで成功します。

本関数はデバッグ用関数です。Releaseビルドでは動作しませんのでご注意ください。
@param[in] config 接続条件インスタンス @param[in] networkArea ネットワーク接続要求レベル @return 結果 */ Result DebugSetNetworkArea( Config* config, NetworkArea networkArea ); /*! @brief 自動接続を開始します。 接続完了後、APから意図せず切断された時には
@ref nn::ac::RegisterDisconnectEvent で登録した @ref nn::os::LightEvent がシグナルします。
@param[in] config 接続条件インスタンス @return 結果 */ Result Connect( Config& config ); /*! @brief 非同期で自動接続を開始します。 処理の成功・失敗に関わらず、処理が終了した段階で
引数に指定した @ref nn::os::Event がシグナルします。
接続完了後、APから意図せず切断された時には
@ref nn::ac::RegisterDisconnectEvent で登録した @ref nn::os::Event がシグナルします。
@param[in] config 接続条件インスタンス @param[in] event 処理の完了を通知する初期化済み @ref nn::os::Event @return 結果 */ Result ConnectAsync( Config& config, os::Event* event ); /*! @brief 非同期で自動接続処理中の場合、処理をキャンセルします。 キャンセルしたときには、Result にはキャンセルされたことを示す値が返ります。
@ref GetLastErrorCode で取得できるエラーコードは、キャンセルされたタイミングで失敗した相当のエラーコードが返ります。
キャンセルされたかの確認には Result の値を使うようにしてください。

キャンセルが成功するか、キャンセルが受け入れられるまでに接続処理が終了した場合は
@ref ConnectAsync で渡した @ref nn::os::Event がシグナルし、@ref GetConnectResult でキャンセルされたことを取得できます。 @ref Connect 実行中に他スレッドから実行した場合は、@ref Connect の戻り値からキャンセルされたことを取得できます。 @return 結果 */ Result CancelConnectAsync(); /*! @brief 非同期で自動接続を行った際の処理結果を取得します。 @ref ConnectAsync で接続処理を行った場合、
@ref nn::os::Event がシグナルしたら、この関数を利用して結果を確認してください。
@return 結果 */ Result GetConnectResult(); /*! @brief 現在接続中のアクセスポイントとの電波強度を取得します。 本関数は毎フレーム呼び出すには重い処理です。
必要に応じて呼び出し間隔を調整するようにしてください。
@param[out] linkLevel 電波強度 @ref LinkLevel @return 結果 */ Result GetLinkLevel( LinkLevel* linkLevel ); /*! @brief 現在接続中のアクセスポイントとの電波強度を取得します。 本関数は毎フレーム呼び出すには重い処理です。
必要に応じて呼び出し間隔を調整するようにしてください。
@return 電波強度 @ref LinkLevel */ LinkLevel GetLinkLevel(); /*! @brief ネットワーク設定1に設定を反映します。
本関数はデバッグ用関数です。Releaseビルドでは動作しませんのでご注意ください。
@param[in] ssid アクセスポイントのSSID @param[in] ssidLength アクセスポイントのSSID長 @param[in] securityMode アクセスポイントの暗号化方式 @param[in] key アクセスポイントの暗号化鍵 @param[in] keyLen アクセスポイントの暗号化鍵長 @return 結果 */ Result DebugSetNetworkSetting1( const u8 ssid[], u8 ssidLength, SecurityMode securityMode, const u8 key[], u8 keyLen ); /*! @brief 自動接続によって確立した接続を切断します。 本関数を呼び出した時に、他のプロセスがインターネット接続を利用していた場合、
@ref GetStatus で取得できるステートがアイドルになることは保障されません。
切断出来たかの確認は戻り値で判断してください。
@return 結果 */ Result Close(); /*! @brief 非同期で自動接続によって確立した接続を切断します。 処理の成功・失敗に関わらず、処理が終了した段階で
引数に指定した @ref nn::os::Event がシグナルします。
@param[in] event 処理の完了を通知する初期化済み @ref nn::os::Event @return 結果 */ Result CloseAsync( os::Event* event ); /*! @brief 非同期で自動接続によって確立した接続を切断した際の処理結果を取得します。 @ref CloseAsync で接続処理を行った場合、
@ref nn::os::Event がシグナルしたら、この関数を利用して結果を確認してください。
@return 結果 */ Result GetCloseResult(); /*! @brief 自動接続で最後に発生したエラーのエラーコードを取得します。 エラーコードの詳細については別途資料を参考にしてください。
@param[out] errorCode エラーコードを書き出す変数 @return 結果 */ Result GetLastErrorCode( u32* errorCode ); /*! @brief 自動接続で最後に発生したエラーの詳細なエラーコードを取得します。 本エラーコードはACライブラリのサポートで利用します。
一般のゲーム開発では使用しないようにしてください。
@param[out] errorCode エラーコードを書き出す変数 @return 結果 */ Result GetLastDetailErrorCode( u32* errorCode ); /*! @brief 自動接続の現在のステータスを取得します。 本関数は毎ゲームフレーム呼び出すには重い処理です。
APとの切断を検出したい場合は @ref RegisterDisconnectEvent を使ってください。

システムがバックグラウンドでインフラ接続を利用中の場合、
アプリケーションが切断しても STATUS_IDLE に戻らない事があります。
このように、ステートはシステムの利用状況により意図した動作をしないことがありますので、
ステートを監視してアプリケーションの遷移を制御するのは危険ですので避けてください。
@param[out] status ステータスを書き出す変数 @return 結果 */ Result GetStatus( Status* status ); /*! @brief 自動接続の現在のステータスを取得します。 本関数は毎ゲームフレーム呼び出すには重い処理です。
APとの切断を検出したい場合は @ref RegisterDisconnectEvent を使ってください。

システムがバックグラウンドでインフラ接続を利用中の場合、
アプリケーションが切断しても STATUS_IDLE に戻らない事があります。
このように、ステートはシステムの利用状況により意図した動作をしないことがありますので、
ステートを監視してアプリケーションの遷移を制御するのは危険ですので避けてください。
@return ステータス */ Status GetStatus(); /*! @brief 現在接続中のアクセスポイントの種類を取得します。 @param[out] apType アクセスポイントの種類を書き出す変数 @return 結果 */ Result GetConnectingApType( ApType* apType ); /*! @brief 現在接続しているニンテンドーゾーンの情報を取得します。 @param[out] beacon ゾーンビーコンを書き出すポインタ @return 結果 */ Result GetConnectingNintendoZoneBeaconSubset( NintendoZoneBeaconSubset* beacon ); /*! @brief AP切断時に通知される @ref nn::os::Event を設定します。 @param[out] event 通知を受ける初期化済み @ref nn::os::Event のポインタ @return 結果 */ Result RegisterDisconnectEvent(nn::os::Event* event); /*! @brief ACのステート変化時に通知される @ref nn::os::Event を設定します。 @ref GetStatus の補足説明のとおり、 アプリケーションからみたステート遷移が意図したとおりに遷移しない可能性があるため
ステートを監視してアプリケーションの遷移を制御すること危険ですので避けてください。
@param[out] event 通知を受ける未初期化 @ref nn::os::Event のポインタ @return 結果 */ Result GetStatusChangeEvent( nn::os::Event* event ); namespace { const char PORT_NAME_USER[] = "ac:u"; } } } } #endif // __cplusplus // 以下、C 用宣言 #include /*! @addtogroup nn_ac ac @brief @ref nn::ac の C インタフェースモジュールです。 @{ */ /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::Initialize を参照してください。 */ NN_EXTERN_C nnResult nnacInitialize(void); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::Finalize を参照してください。 */ NN_EXTERN_C nnResult nnacFinalize(void); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::CreateDefaultConfig を参照してください。 */ NN_EXTERN_C nnResult nnacCreateDefaultConfig( nnacConfig* config ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::DebugSetNetworkArea を参照してください。 */ NN_EXTERN_C nnResult nnacDebugSetNetworkArea( nnacConfig* config, nnacNetworkArea networkArea ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::Connect を参照してください。 */ NN_EXTERN_C nnResult nnacConnect( nnacConfig* config ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::ConnectAsync を参照してください。 */ NN_EXTERN_C nnResult nnacConnectAsync( nnacConfig* config, nnosEvent* event ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::CancelConnectAsync を参照してください。 */ NN_EXTERN_C nnResult nnacCancelConnectAsync(void); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::GetConnectResult を参照してください。 */ NN_EXTERN_C nnResult nnacGetConnectResult(void); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::DebugSetNetworkSetting1 を参照してください。 */ NN_EXTERN_C nnResult nnacDebugSetNetworkSetting1( const u8 ssid[], u8 ssidLength, nnacSecurityMode securityMode, const u8 key[], u8 keyLen ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::DebugFlushNetworkSetting を参照してください。 */ NN_EXTERN_C nnResult nnacDebugFlushNetworkSetting(void); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::Close を参照してください。 */ NN_EXTERN_C nnResult nnacClose(void); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::CloseAsync を参照してください。 */ NN_EXTERN_C nnResult nnacCloseAsync( nnosEvent* event ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::GetCloseResult を参照してください。 */ NN_EXTERN_C nnResult nnacGetCloseResult(void); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::GetStatus を参照してください。 */ NN_EXTERN_C nnResult nnacGetStatus( nnacStatus* status ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::GetLinkLevel を参照してください。 */ NN_EXTERN_C nnResult nnacGetLinkLevel( nnacLinkLevel* linkLevel ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::GetLastErrorCode を参照してください。 */ NN_EXTERN_C nnResult nnacGetLastErrorCode( u32* errorCode ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::GetLastDetailErrorCode を参照してください。 */ NN_EXTERN_C nnResult nnacGetLastDetailErrorCode( u32* errorCode ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::GetConnectingApType を参照してください。 */ NN_EXTERN_C nnResult nnacGetConnectingApType( nnacApType* apType ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::GetConnectingNintendoZoneBeaconSubset を参照してください。 */ NN_EXTERN_C nnResult nnacGetConnectingNintendoZoneBeaconSubset( nnacNintendoZoneBeaconSubset* beacon ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::RegisterDisconnectEvent を参照してください。 */ NN_EXTERN_C nnResult nnacRegisterDisconnectEvent( nnosEvent* event ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::GetStatusChaneEvent を参照してください。 */ NN_EXTERN_C nnResult nnacGetStatusChaneEvent( nnosEvent* event ); /*! @} */ #endif // ifndef NN_AC_CTR_AC_API_H_