/*---------------------------------------------------------------------------* 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-11-30#$ $Rev: 32066 $ $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 namespace nn { namespace ac { namespace CTR { /*! @brief 自動接続の初期化をします。 内部で参照カウンターを持っていますので、
多重で本関数を呼び出してもエラーにはなりませんが、
同じ回数 @ref Finalize を呼び出してください。
@return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultAlreadyInitialized 既に初期化されています。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result Initialize(); /*! @brief 自動接続の開放処理をします。 @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultNotInitialized 初期化されていません。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result Finalize(); /*! @brief 自動接続が初期化済みかを取得します。 @return 初期化済みか */ bool IsInitialized(); /*! @brief 一般的な接続条件を生成します。 通常、アプリケーションは確保した Config をこの関数に渡し、
そのまま @ref Connect の引数に指定してください。

configのフォーマットは将来システムアップデートによって変更される可能性があります。
中身を書き換えるようなコーディングは避けてください。
@param[out] config 接続条件インスタンス @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定しました。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result CreateDefaultConfig( Config* config ); /*! @brief ネットワーク接続するAPの種類を指定します。 @ref ApType の値を aptype に指定します。
@ref ApType は論理和することで、同時に複数のAP種別を指定する事ができます。

本関数はデバッグ用関数です。Releaseビルドでは動作しませんのでご注意ください。
@param[in] config 接続条件インスタンス @param[in] aptype APの種類 @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定しました。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result DebugSetApType( Config* config, u32 aptype ); /*! @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 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定しました。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result DebugSetNetworkArea( Config* config, NetworkArea networkArea ); /*! @brief 自動接続を開始します。 @ref nn::fs::Initialize を呼び出した後で利用するようにしてください。 接続完了後、APから意図せず切断された時には
@ref nn::ac::RegisterDisconnectEvent で登録した @ref nn::os::LightEvent がシグナルします。
この関数内でアプリの EULA バージョンを取得するため、アイコンファイルを設定していないと @ref ResultNotAgreeEula が返ります。 @param[in] config 接続条件インスタンス @return 結果 @retval ResultLanConnected LAN接続に成功しました。 @retval ResultWanConnected WAN接続に成功しました。 @retval nn::fs::ResultNotInitialized fsが初期化されていません。 @retval ResultNotFoundAccessPoint 接続できるアクセスポイントが見つかりませんでした。 @retval ResultCanceled 接続処理中にキャンセルされました。 @retval ResultAlreadyExists 既に処理中です。 @retval ResultNotAgreeEula EULAに同意していない、もしくはアイコンファイルが設定されていません。 @retval ResultAlreadyConnectUnsupportAp 利用できないAPに接続中です。 @retval ResultWifiOff フライトモードの為、ネットワークを利用できません。 @retval ResultFailedScan スキャンに失敗しました。 @retval ResultConflictIpAddress IPアドレスが衝突しています。 @retval ResultFailedDhcp DHCPに失敗しました。 @retval ResultInvalidDns 名前解決に失敗しました。 @retval ResultInvalidProxy プロキシに失敗しました。 @retval ResultFailedConnTest インターネット接続テストに失敗しました。 @retval ResultFailedHotspotAuthentication ホットスポット認証に失敗しました。 @retval ResultFailedHotspotConntest ホットスポット認証通過後にインターネット接続テストに失敗しました。 @retval ResultOutOfMemory メモリの確保に失敗しました。 @retval ResultUnsupportAuthAlgorithm 非対応の暗号化方式のアクセスポイントだった為、接続できませんでした。 @retval ResultDenyUsbAp ニンテンドーWi-Fi USBコネクタにアクセス拒否されました。 @retval ResultUnsupportPlace ネットワークを利用できない場所のため接続できませんでした。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result Connect( Config& config ); /*! @brief 非同期で自動接続を開始します。 処理の成功・失敗に関わらず、処理が終了した段階で
引数に指定した @ref nn::os::Event がシグナルします。
@ref nn::fs::Initialize を呼び出した後で利用するようにしてください。 接続完了後、APから意図せず切断された時には
@ref nn::ac::RegisterDisconnectEvent で登録した @ref nn::os::Event がシグナルします。
この関数内でアプリの EULA バージョンを取得するため、アイコンファイルを設定していないと @ref ResultNotAgreeEula が返ります。 @param[in] config 接続条件インスタンス @param[in] event 処理の完了を通知する初期化済み @ref nn::os::Event @return 結果 @retval ResultSuccess 正常に終了しました。 @retval nn::fs::ResultNotInitialized fsが初期化されていません。 @retval ResultInvalidData 引数にNULLを指定したか、未初期化のEventを指定しました。 @retval ResultAlreadyExists 既に処理中です。 @retval ResultCanceled 接続処理中にキャンセルされました。 @retval ResultNotAgreeEula EULAに同意していない、もしくはアイコンファイルが設定されていません。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result ConnectAsync( Config& config, os::Event* event ); /*! @brief 非同期で自動接続を行った際の処理結果を取得します。 @ref ConnectAsync で接続処理を行った場合、
@ref nn::os::Event がシグナルしたら、この関数を利用して結果を確認してください。
@return 結果 @retval ResultLanConnected LAN接続に成功しました。 @retval ResultWanConnected WAN接続に成功しました。 @retval ResultProcessing 接続処理がまだ完了していません。 @retval ResultNotFoundAccessPoint 接続できるアクセスポイントが見つかりませんでした。 @retval ResultCanceled 接続処理中にキャンセルされました。 @retval ResultAlreadyConnectUnsupportAp 利用できないAPに接続中です。 @retval ResultWifiOff フライトモードの為、ネットワークを利用できません。 @retval ResultFailedScan スキャンに失敗しました。 @retval ResultConflictIpAddress IPアドレスが衝突しています。 @retval ResultFailedDhcp DHCPに失敗しました。 @retval ResultInvalidDns 名前解決に失敗しました。 @retval ResultInvalidProxy プロキシに失敗しました。 @retval ResultFailedConnTest インターネット接続テストに失敗しました。 @retval ResultFailedHotspotAuthentication ホットスポット認証に失敗しました。 @retval ResultFailedHotspotConntest ホットスポット認証通過後にインターネット接続テストに失敗しました。 @retval ResultOutOfMemory メモリの確保に失敗しました。 @retval ResultUnsupportAuthAlgorithm 非対応の暗号化方式のアクセスポイントだった為、接続できませんでした。 @retval ResultDenyUsbAp ニンテンドーWi-Fi USBコネクタにアクセス拒否されました。 @retval ResultUnsupportPlace ネットワークを利用できない場所のため接続できませんでした。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result GetConnectResult(); /*! @brief 非同期で自動接続処理中の場合、処理をキャンセルします。 キャンセルしたときには、Result にはキャンセルされたことを示す値が返ります。
@ref GetLastErrorCode で取得できるエラーコードは、キャンセルされたタイミングで失敗した相当のエラーコードが返ります。
キャンセルされたかの確認には Result の値を使うようにしてください。

キャンセルが成功するか、キャンセルが受け入れられるまでに接続処理が終了した場合は
@ref ConnectAsync で渡した @ref nn::os::Event がシグナルし、@ref GetConnectResult でキャンセルされたことを取得できます。 @ref Connect 実行中に他スレッドから実行した場合は、@ref Connect の戻り値からキャンセルされたことを取得できます。 @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultNotConnecting 接続処理中ではありません。 @retval ResultAlreadyConnecting 既に接続処理が完了し、接続が確立しています。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result CancelConnectAsync(); /*! @brief 現在接続中のアクセスポイントとの電波強度を取得します。
データ取得時にエラーが発生した時には、LINK_LEVEL_0 を結果として返します。
そのため、LinkLevelを書き換えるなどのエラーハンドリングは特に必要ありません。
@param[out] linkLevel 電波強度 @ref LinkLevel @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定しました。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result GetLinkLevel( LinkLevel* linkLevel ); /*! @brief 現在接続中のアクセスポイントとの電波強度を取得します。
本APIは内部的に引数指定の @ref GetLinkLevel を呼び出します。
引数指定の @ref GetLinkLevel に失敗した場合は
LINK_LEVEL_0 を結果として返します。
@return 電波強度 @ref LinkLevel */ LinkLevel GetLinkLevel(); /*! @brief ネットワーク設定1に設定します。
設定内容は即座にNANDに反映されます。

本関数はデバッグ用関数です。Releaseビルドでは動作しませんのでご注意ください。
@param[in] ssid アクセスポイントのSSID @param[in] ssidLength アクセスポイントのSSID長 @param[in] securityMode アクセスポイントの暗号化方式 @param[in] key アクセスポイントの暗号化鍵 @param[in] keyLen アクセスポイントの暗号化鍵長 @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultOutOfMemory メモリの確保に失敗しました。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result DebugSetNetworkSetting1( const u8 ssid[], u8 ssidLength, SecurityMode securityMode, const u8 key[], u8 keyLen ); /*! @brief 自動接続によって確立した接続を切断します。 @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultAlreadyExists 既に処理中です。 @retval ResultNotConnecting 接続していません。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result Close(); /*! @brief 非同期で自動接続によって確立した接続を切断します。 処理の成功・失敗に関わらず、処理が終了した段階で
引数に指定した @ref nn::os::Event がシグナルします。
@param[in] event 処理の完了を通知する初期化済み @ref nn::os::Event @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定したか、未初期化のEventを指定しました。 @retval ResultAlreadyExists 既に処理中です。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result CloseAsync( os::Event* event ); /*! @brief 非同期で自動接続によって確立した接続を切断した際の処理結果を取得します。 @ref CloseAsync で接続処理を行った場合、
@ref nn::os::Event がシグナルしたら、この関数を利用して結果を確認してください。
@return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultProcessing 切断処理がまだ完了していません。 @retval ResultNotConnecting 接続していません。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result GetCloseResult(); /*! @brief 自動接続で最後に発生したエラーのエラーコードを取得します。 エラーコードの詳細については別途資料を参考にしてください。
@param[out] errorCode エラーコードを書き出す変数 @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定しました。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result GetLastErrorCode( u32* errorCode ); /*! @brief 自動接続で最後に発生したエラーの詳細なエラーコードを取得します。 本エラーコードはACライブラリのサポートで利用します。
一般のゲーム開発では使用しないようにしてください。
@param[out] errorCode エラーコードを書き出す変数 @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定しました。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result GetLastDetailErrorCode( u32* errorCode ); /*! @brief APに接続中かを取得します。 本関数は毎ゲームフレーム呼び出すには重い処理です。
本関数は @ref Initialize を呼び出していなくても利用でき、失敗が帰ります。
@return APに接続中かの真偽値 */ bool IsConnected(); /*! @brief 現在接続中のアクセスポイントの種類を取得します。 本APIは基本的に参考値として取得することを想定してます。 ApTypeの種類はファームウェアアップデートで増減する可能性がありますので、 この値を元に処理を分岐する際は else も考慮した実装にしてください。 なお、この関数の想定する利用用途は AP_TYPE_NINTENDO_ZONE だった時に @ref GetConnectingNintendoZoneBeaconSubset を呼び出したり、 AP_TYPE_HOTSPOT だった時に @ref GetConnectingHotspotSubset を呼び出すことで、 インターネット接続中のロケーションを取得することを想定しています。 @param[out] apType アクセスポイントの種類を書き出す変数 @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定しました。 @retval ResultNotConnecting ネットワークに接続していません。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result GetConnectingApType( ApType* apType ); /*! @brief 現在接続しているニンテンドーゾーンの情報を取得します。 @param[out] beacon ゾーンビーコンを書き出すポインタ @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定しました。 @retval ResultNotConnecting ネットワークに接続していません。 @retval ResultInvalidLocation ニンテンドーゾーンに接続していません。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result GetConnectingNintendoZoneBeaconSubset( NintendoZoneBeaconSubset* beacon ); /*! @brief 現在接続しているホットスポットの情報を取得します。 @param[out] hotspot ホットスポットを書き出すポインタ @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定しました。 @retval ResultNotConnecting ネットワークに接続していません。 @retval ResultInvalidLocation ホットスポットに接続していません。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result GetConnectingHotspotSubset( HotspotSubset* hotspot ); /*! @brief AP切断時に通知される @ref nn::os::Event を設定します。 @param[out] event 通知を受ける初期化済み @ref nn::os::Event のポインタ @return 結果 @retval ResultSuccess 正常に終了しました。 @retval ResultInvalidData 引数にNULLを指定したか、未初期化のEventを指定しました。 @retval 上記以外 上記以外の理由で失敗しました。 */ Result RegisterDisconnectEvent(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::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::GetConnectingHotspotSubset を参照してください。 */ NN_EXTERN_C nnResult nnacGetConnectingHotspotSubset( nnacHotspotSubset* hotspot ); /*! @brief 対応する C++ 関数 @ref nn::ac::CTR::RegisterDisconnectEvent を参照してください。 */ NN_EXTERN_C nnResult nnacRegisterDisconnectEvent( nnosEvent* event ); /*! @} */ #endif // ifndef NN_AC_CTR_AC_API_H_