1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: dlp_Server.h 4 5 Copyright (C)2009 Nintendo Co., Ltd. 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 NN_DLP_CTR_DLP_SERVER_H_ 16 #define NN_DLP_CTR_DLP_SERVER_H_ 17 18 #include <nn/dlp/CTR/dlp_Type.h> 19 20 #ifdef __cplusplus 21 22 namespace nn { 23 namespace dlp { 24 namespace CTR { 25 26 /*!--------------------------------------------------------------------------* 27 @brief ダウンロードプレイのサーバのクラスです。 28 *--------------------------------------------------------------------------*/ 29 class Server 30 { 31 private: Server()32 Server() {}; ~Server()33 ~Server() {}; 34 35 public: 36 /*!--------------------------------------------------------------------------* 37 @brief サーバの初期化に必要なバッファのサイズを取得します。 38 39 @param[in] maxClientNum サーバに接続可能なクライアントの最大数(1 ~ MAX_CLIENT_NUM)を指定します。 40 @param[in] blockBufferSize ファイルから読みだしたデータを送信前にためるブロックバッファのサイズです。<BR> 41 MIN_NETWORK_BLOCK_BUFFER_SIZE 以上 MAX_NETWORK_BLOCK_BUFFER_SIZE 以下を指定してください。 42 @param[in] blockBufferNum ブロックバッファの数です。<BR> 43 MIN_NETWORK_BLOCK_BUFFER_NUM 以上 MAX_NETWORK_BLOCK_BUFFER_NUM 以下を指定してください。 44 45 @return バッファのサイズを返します。 46 47 *--------------------------------------------------------------------------*/ 48 static size_t GetBufferSize(u8 maxClientNum, size_t blockBufferSize = MIN_NETWORK_BLOCK_BUFFER_SIZE * 2, size_t blockBufferNum = MIN_NETWORK_BLOCK_BUFFER_NUM); 49 50 51 /*!--------------------------------------------------------------------------* 52 @brief サーバを初期化します。 53 54 pBuffer に GetBufferSize() で指定されたサイズの 4096 Byte 境界 のバッファを指定してください。バッファにデバイスメモリを使用しないでください。<BR> 55 配信できる子機プログラムのサイズは 最大で 32 MB です。<BR> 56 バックグラウンドでの通信処理を終了させ、Finalize() を実行するまで DLP ライブラリが通信デバイスを占有する処理を行うため、長時間ブロックする可能性があります。 57 58 @param[in] eventHandle ダウンロードプレイからのシグナルを待つ nn::os::Event のハンドルを指定します。 Event はアプリケーションで初期化してください。また、イベントの情報は GetEventDesc で取得します。 59 @param[in] maxClientNum サーバに接続可能なクライアントの最大数(1 ~ MAX_CLIENT_NUM)を指定します。 60 @param[in] childIndex 配信する子機プログラムのインデックス(rsf の ChildIndex)を指定してください。 0 ～ 255 まで指定できます。(サーバは子機を 256 個まで持つことができます。) 61 @param[in] pBuffer DLP の作業バッファへのポインタ。4096 バイト境界にしてください。 62 @param[in] bufferSize 作業バッファのサイズ。4096 バイト境界にしてください。 63 @param[in] blockBufferSize ファイルから読みだしたデータを送信前にためるブロックバッファのサイズです。MIN_NETWORK_BLOCK_BUFFER_SIZE 以上 MAX_NETWORK_BLOCK_BUFFER_SIZE 以下を指定してください。 64 @param[in] blockBufferNum ブロックバッファの数です。MIN_NETWORK_BLOCK_BUFFER_NUM 以上 MAX_NETWORK_BLOCK_BUFFER_NUM 以下を指定してください。 65 66 @return 処理の結果として以下の Result が返ってきます。 67 @retval ResultSuccess 初期化が成功しました。 68 @retval ResultInvalidPointer pBuffer が NULL か 4096 バイト境界でないです。 69 @retval ResultOutOfRange maxClientNum、bufferSize、blockBufferSize、blockBufferNum が不正です。 70 @retval ResultInvalidHandle eventHandle が不正です。 71 @retval ResultAlreadyOccupiedWirelessDevice 無線デバイスが既に他の用途で占有されています。 他の無線処理を終了してください。 72 @retval ResultInternalError 内部に回復不可のエラーが発生しました。 73 @retval ResultWirelessOff 通信できない状態(スリープあるいは Wifi ボタンが OFF)です。 74 @retval ResultInvalidMediaType 親機のメディアタイプがサポートされていません。 75 @retval ResultFailedToAccessMedia メディアにアクセスできませんでした。子機プログラムが正しく親機に組み込まれていないか、カード抜けの可能性があります。 76 @retval ResultChildTooLarge 子機プログラムのインポートサイズが規定 ( MAX_CHILD_IMPORT_SIZE ) を超えています。 77 @retval ResultInvalidRegion 子機プログラムのリージョンが本体リージョンと異なります。 78 79 *--------------------------------------------------------------------------*/ 80 static nn::Result Initialize( 81 nn::Handle eventHandle, 82 u8 maxClientNum, 83 u8 childIndex, 84 void* pBuffer, 85 size_t bufferSize, 86 size_t blockBufferSize = MIN_NETWORK_BLOCK_BUFFER_SIZE * 2, 87 size_t blockBufferNum = MIN_NETWORK_BLOCK_BUFFER_NUM); 88 89 90 /*!--------------------------------------------------------------------------* 91 @brief サーバを終了します。 92 93 @return 処理の結果が返ってきます。 94 @retval ResultSuccess 終了が成功しました。 95 96 *--------------------------------------------------------------------------*/ 97 static nn::Result Finalize(); 98 99 100 /*!--------------------------------------------------------------------------* 101 @brief サーバの状態を取得します。 102 103 @param[out] pState サーバの状態を返します。 104 105 @return 処理の結果として以下の Result が返ってきます。 106 @retval ResultSuccess 状態の取得が成功しました。 107 108 *--------------------------------------------------------------------------*/ 109 static nn::Result GetState(ServerState* pState); 110 111 112 /*!--------------------------------------------------------------------------* 113 @brief 到着しているイベントをキューから取得します。 114 115 現在のキューのサイズはイベント32個分です。キューがいっぱいになると、古いイベントから消去され新しいイベントが追加されます。<BR> 116 イベントがない場合、本API はブロックせず ResultNoData() の返すエラーコードを 返します。<BR> 117 なお、 イベントを取得しなくても各種状態取得 API を利用すれば処理を行えます。 118 119 @param[out] pEventDesc イベントを読み込み先を指定します。 120 121 @return 処理の結果として以下の Result が返ってきます。 122 @retval ResultSuccess イベントの取得が成功しました。 123 @retval ResultNoData イベントがありません。 124 125 *--------------------------------------------------------------------------*/ 126 static nn::Result GetEventDesc(EventDesc* pEventDesc); 127 128 129 /*!--------------------------------------------------------------------------* 130 @brief ダウンロードセッションを開始します。 131 132 @param[in] isManualAccept true : AcceptClient でクライアントの接続を許可します。 false : 無条件に接続を許可します。 133 @param[in] channel チャンネルを0(自動選択)、1、6、11 から指定してください。製品機 では 0 が強制的に選ばれます。 134 135 @return 処理の結果として以下の Result が返ってきます。 136 @retval ResultSuccess セッションの開始が成功しました。 137 @retval ResultOutOfRange 不正なチャンネルを指定しています。 138 @retval ResultInvalidState 状態が不正です。 SERVER_STATE_INITIALIZED で使用してください。 139 @retval ResultWirelessOff 通信できない状態(スリープあるいは Wifi ボタンが OFF)です。 140 141 *--------------------------------------------------------------------------*/ 142 static nn::Result OpenSessions(bool isManualAccept = false, u8 channel = 0); 143 144 145 /*!--------------------------------------------------------------------------* 146 @brief クライアントの接続を許可します。 147 148 isManualAccept 引数 を true で OpenSession() を呼ぶと、クライアントは接続後に CLIENT_STATE_WAITING_ACCEPT 状態になり<BR> 149 サーバからの許可を待ち続けます。このクライアントの接続を許可するには本 API を呼んでください。<BR> 150 呼び出し後、クライアントは CLIENT_STATE_WAITING_INVITE 状態へ遷移します。なお、接続を拒否する場合、DisconnectClient() でクライアントを切断してください。 151 152 @param[in] nodeId クライアントのノード ID を指定します。 153 154 @return 処理の結果として以下の Result が返ってきます。 155 @retval ResultSuccess 接続許可が成功しました。 156 @retval ResultInvalidState 状態が不正です。 SERVER_STATE_OPENED_SESSIONS 状態(OpenSessions() が成功した後) で使用してください。 157 @retval ResultNoData 指定されたノード ID を持つノードは接続されていません。 158 159 *--------------------------------------------------------------------------*/ 160 static nn::Result AcceptClient(u16 nodeId); 161 162 163 /*!--------------------------------------------------------------------------* 164 @brief クライアントのネットワーク接続を強制的に切断します。 165 166 接続しているクライアントをネットワークから切断します。 167 168 @param[in] nodeId クライアントのノード ID を指定します。 169 170 @return 処理の結果として以下の Result が返ってきます。 171 @retval ResultSuccess 切断が成功しました。 172 @retval ResultInvalidState 状態が不正です。 SERVER_STATE_OPENED_SESSIONS 状態(OpenSessions() が成功した後) で使用してください。 173 @retval ResultWirelessOff 通信できない状態(スリープあるいは Wifi ボタンが OFF)です。 174 175 *--------------------------------------------------------------------------*/ 176 static nn::Result DisconnectClient(u16 nodeId); 177 178 179 /*!--------------------------------------------------------------------------* 180 @brief ダウンロードセッションを開始します。 181 182 本 API の呼び出し以降、新たにクライアントの接続は行えません。また、本 API の呼び出し時に CLIENT_STATE_WAITING_ACCEPT 状態のクライアントは切断されます。<BR> 183 サーバは子機プログラムだけでなく子機プログラムのブートに必要なシステムを配信することがあります。サーバは、システムをダウンロードしたクライアントがリブートし<BR> 184 再接続して来るのを、永遠に SERVER_STATE_WAITING_RECONNECT 状態で待ち続けます。<BR> 185 しかし、クライアント側がダウンロードをキャンセルしたり、無線 OFF や電源断、通信品質の低下により親機との通信ができない状態になるなど<BR> 186 クライアントが必ず再接続してくるとは限りませんので、ユーザがいつでもダウンロードデータセッションを停止できるようにしてください。 187 188 @return 処理の結果として以下の Result が返ってきます。 189 @retval ResultSuccess セッションの開始が成功しました。 190 @retval ResultInvalidState 状態が不正か、AcceptClient()されたクライアントがいません。SERVER_STATE_OPENED_SESSIONS 状態(OpenSessions() が成功した後) で使用してください。 191 @retval ResultWirelessOff 通信できない状態(スリープあるいは Wifi ボタンが OFF)です。 192 @retval ResultFailedToAccessMedia メディアにアクセスできませんでした。カード抜けの可能性があります。 193 194 *--------------------------------------------------------------------------*/ 195 static nn::Result StartDistribute(); 196 197 198 /*!--------------------------------------------------------------------------* 199 @brief 全てのクライアントへリブート要求を出します。 200 201 リブート後にダウンロードセッションに参加した CTR だけを接続したい場合、passPharase で UDS のパスフレーズを指定してください。<BR> 202 パスフレーズを指定する場合、ダウンロードセッションごとにパスフレーズを変えてください。<BR> 203 本 API 呼び出し後、全てのクライアントが切断されてから CloseSessions() と Finalize() を呼んでください。<BR> 204 クライアントの切断は、GetConnectingClients() のクライアント数から判断してください。<BR> 205 クライアントがリブート後に子機として再接続してくる保証はありません。親機として子機を待ち受ける場合は注意してください。 206 207 @param[in] passpharase 再接続時の UDS パスフレーズです。長さは、MAX_CHILD_UDS_PASSPHRASE_LENGTH までです。 208 @return 処理の結果として以下の Result が返ってきます。 209 @retval ResultSuccess リブート要求をクライアントへ出しました。 210 @retval ResultInvalidState 状態が不正です。ダウンロードが完了した状態 (SERVER_STATE_COMPLETE_DISTRIBUTION) で使用してください。 211 212 *--------------------------------------------------------------------------*/ 213 static nn::Result RebootAllClients(const char passpharase[] = NULL); 214 215 216 /*!--------------------------------------------------------------------------* 217 @brief ダウンロードセッションを停止します。 218 219 @return 処理の結果として以下の Result が返ってきます。 220 @retval ResultSuccess 停止が成功しました。 221 222 *--------------------------------------------------------------------------*/ 223 static nn::Result CloseSessions(); 224 225 226 /*!--------------------------------------------------------------------------* 227 @brief 接続しているクライアントの数を取得します。 228 229 @param[out] pNum clients に格納されたクライアント ID の数を返します。 230 @param[out] clients クライアントのノードIDを返します。 231 @param[in] size clients の配列の個数を指定します。 232 233 @return 処理の結果として以下の Result が返ってきます。 234 @retval ResultSuccess クライアント数の取得が成功しました。 235 @retval ResultInvalidState 状態が不正です。OpenSessions() が成功した( SERVER_STATE_OPENED_SESSIONS ) 以降、SERVER_STATE_ERROR 状態でない限り使用できます。 236 237 *--------------------------------------------------------------------------*/ 238 static nn::Result GetConnectingClients(u16* pNum, u16 clients[], u16 size); 239 240 241 /*!--------------------------------------------------------------------------* 242 @brief クライアントの情報を取得します。 243 244 245 @param[out] pNodeInfo クライアントの情報を返します。 246 @param[in] nodeId クライアントのノードIDを指定します。 247 248 @return 処理の結果として以下の Result が返ってきます。 249 @retval ResultSuccess クライアント情報の取得が成功しました。 250 @retval ResultInvalidState 状態が不正です。OpenSessions() が成功した( SERVER_STATE_OPENED_SESSIONS ) 以降、SERVER_STATE_ERROR 状態でない限り使用できます。 251 @retval ResultNoData 指定されたノード ID を持つクライアントは接続されていません。 252 253 *--------------------------------------------------------------------------*/ 254 static nn::Result GetClientInfo( 255 NodeInfo* pClientInfo, 256 u16 nodeId); 257 258 259 /*!--------------------------------------------------------------------------* 260 @brief クライアントの状態、ダウンロードの進捗などを取得します。 261 262 @param[out] pClientStatus クライアントの情報、状態、ダウンロードの進捗などを返します。 263 @param[in] nodeId クライアントのノードIDを指定します。 264 265 @return 処理の結果として以下の Result が返ってきます。 266 @retval ResultSuccess クライアントの状態取得が成功しました。 267 @retval ResultInvalidState 状態が不正です。OpenSessions() が成功した( SERVER_STATE_OPENED_SESSIONS ) 以降、SERVER_STATE_ERROR 状態でない限り使用できます。 268 @retval ResultNoData 指定されたノード ID を持つクライアントは接続されていません。 269 270 *--------------------------------------------------------------------------*/ 271 static nn::Result GetClientStatus( 272 ClientStatus* pClientStatus, 273 u16 nodeId); 274 275 /*!--------------------------------------------------------------------------* 276 @brief クライアントのうち、最も弱いリンクレベルを返します。 277 278 @param[out] pLinkLevel リンクレベルを返します。 279 280 @return 処理の結果として以下の Result が返ってきます。 281 @retval ResultSuccess リンクレベルの取得が成功しました。 282 283 *--------------------------------------------------------------------------*/ 284 static nn::Result GetLinkLevel(nn::uds::LinkLevel* pLinkLevel); 285 286 }; 287 288 } // namespace CTR 289 } // namespace dlp 290 } // namespace nn 291 292 293 #endif // __cplusplus 294 #endif // ifndef NN_DLP_CTR_DLP_SERVER_H_ 295 296