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