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