/*-------------------------------------------------------------------------- Project: Horizon File: rdt_Receiver.h Copyright (C)2010 Nintendo Co., Ltd. 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. $Rev: 26004 $ *-------------------------------------------------------------------------*/ ////#include "stdafx.h" #ifndef NN_RDT_RECEIVER_H_ #define NN_RDT_RECEIVER_H_ #include "rdt_define.h" #include #include namespace nn { namespace rdt { namespace CTR { class ReceiverImpl; /*! @brief @ref Initialize に渡す初期化情報がまとめられた構造体です。 */ struct ReceiverConfig{ void *pWorkBuf; //!< Receiverインスタンスがワークメモリとして使用する領域を指すポインタ。 //!< 8byteアライメントが必要です。ワークメモリは、 //!< Receiver::RECEIVER_WORKBUF_SIZE以上のサイズを確保してください。 void *pRecvBuf; //!< 受信バッファの先頭アドレスを与えます。 u16 recvBufSize; //!< pRecvBufで指定した受信バッファのサイズ（単位はByte）です。 u16 nodeId; //!< UDS通信における相手のノードID u8 port; //!< UDS通信において使用するポート番号 u8 padding[3]; //!< パディング #ifdef _WIN32 SOCKET sock; #endif }; /*! @brief データの受信側を表現するクラスです。 Receiverクラスの使い方を示します。以下の説明では、@ref Process の呼び出しに ついての言及を省いていますが、実際にはゲームフレーム程度の周期、あるいはそれ以上の 周期で@ref Process を定期的に呼び出すことが必要となります。 1. Receiverクラスのインスタンスを作成します。 2. @ref Initialize を呼び出し、インスタンスを初期化します。 （このとき、Receiverインスタンスが内部で利用するワークメモリと、受信バッファ用の メモリを割り当てます） 3. @ref Wait を呼び出し、Senderインスタンスからの接続を待ちます。 4. 状態がRECEIVER_STATE_OPENEDに遷移したら、定期的に @ref Receive を呼び出し、 到着したデータを（アプリケーション側が用意した領域に）書き込んでいきます。 5. 状態がRECEIVER_STATE_FINISHEDに遷移し、@ref Receive で読み取ることの できるデータサイズが0になったことを確認したら、@ref Close を呼び出します。 6. 状態がRECEIVER_STATE_CLOSEDに遷移したら、@ref Finalize を呼び出し、Receiver クラスの後始末をします。 */ class Receiver{ public: static const size_t RECEIVER_WORKBUF_SIZE = 128; //!< Receiverインスタンスが必要とするワークメモリのサイズです。 /*! @brief コンストラクタです。 Receiverインスタンスを利用可能にするには、後で @ref Initialize を 呼ぶ必要があります。 */ Receiver(void); /*! @brief デストラクタです。 @ref Finalize が呼ばれずにデストラクタが呼ばれた場合は、 ここで@ref Finalize が呼ばれます。 */ ~Receiver(void); /*! @brief インスタンスを初期化します。 初期化が成功すると、内部で暗黙的に、@ref nn::uds::EndpointDescriptorが2つ消費されます。 初期化に失敗した場合は、@ref nn::uds::EndpointDescriptorは消費されずに関数が返ります。 この呼び出しでインスタンスに渡したメモリは、@ref Finalize を呼び出すまで 確保しておく必要があります。 @param[in] config 初期化パラメータをまとめた構造体。詳細は ReceiverConifg を参照してください。 @return 初期化処理の結果が返されます。具体的には、 @ref ResultSuccess, @ref ResultAlreadyInitialized, @ref ResultNullPointer, @ref ResultInvalidSize, そのほか、UDS APIが返しうるリザルトコードが返される可能性があります。 */ nn::Result Initialize(const ReceiverConfig &config); /*! @brief Receiverインスタンスが使用していたリソース（受信バッファ・エンドポイントディスクリプタなど）を解放します。 @return ありません。@ref Finalize の呼び出しは必ず成功します。 インスタンスの初期化がされていない状態で @ref Finalize を呼び出した場合は、 何も起こらずに関数呼び出しから返ります。 */ void Finalize(void); /*! @brief 接続を待ち受けるリクエストを発行します。 リモートのSenderインスタンスが発行する接続要求を待ち受けるリクエストを発行します。 この関数呼び出しが成功すると、RECEIVER_STATE_WAITING状態に移行します。 実際の待ち受け動作は @ref Process 内部で実行されます。 @return リクエストが受諾されれば、成功が返ります。 インスタンスの状態がRECEIVER_STATE_CLOSED以外のときにこの関数を呼び出すと、失敗が返ります。 具体的には、 @ref ResultSuccess, @ref ResultNotInitialized, @ref ResultUntimelyFunctionCall が返される可能性があります。 */ nn::Result Wait(void); /*! @brief 状態をCLOSEDに戻すリクエストを発行します。 全てのデータを受信できたと確認できてから呼ばれることを想定しています。 この関数呼び出しが成功すると、RECEIVER_STATE_CLOSED状態に移行します。 @return リクエストが受諾されれば、成功が返ります。 インスタンスの状態がRECEIVER_STATE_FINISHED以外のときにこの関数を呼び出すと、失敗が返ります。 具体的には、 @ref ResultSuccess, @ref ResultNotInitialized, @ref ResultUntimelyFunctionCall が返される可能性があります。 */ nn::Result Close(void); /*! @brief 受信バッファに溜められたデータを読み取ります。 スループットの向上のために、この関数は毎ゲームフレーム程度の周期で 呼び出すことを推奨します。 @param[out] pBuf 受信データの書き込み先バッファの先頭アドレスを与えます。 @param[out] pRecvSize 受信バッファから読み取ることのできたByte数が記録されます。 読み取るデータが1Byteも存在していなかった場合は、0が書き込まれます。 @param[in] bufSize 受信データの書き込み先バッファのサイズ（Byte数）を与えます。 0を指定した場合は、何もせずに非エラーの値を返します。 @return 関数の実行結果が返ります。 具体的には、 @ref ResultSuccess, @ref ResultDoNothing, @ref ResultNotInitialized, @ref ResultNullPointer, @ref ResultUntimelyFunctionCall が返される可能性があります。 */ nn::Result Receive(void *pBuf, size_t *pRecvSize, size_t bufSize); /*! @brief 通信処理を進行させます。実際の通信処理は、この関数の内部で実行されます。 アプリケーションは、この関数を少なくとも毎ゲームフレーム程度の間隔で 呼び出す必要があります。 また、実データを送受信する局面においては、この関数を数回、連続して呼び出すことで、 送受信のパフォーマンスを改善できることがあります。 この関数呼び出し1回では、最大でも1400Byte程度の通信処理が行われるだけですが、 この関数を複数回呼び出すことで、より多くのデータを受信できる可能性が生まれます。 具体的なセッティングにつきましては、basicサンプルデモなどを参照してください。 なお、この関数の実行中は、他のメンバ関数（@ref Receive など）を呼ばないでください。 動作保証外となります。 Receiverインスタンスの状態遷移も、この関数の中で行われます。 @return 一連の通信処理の結果が返ります。 具体的には、 @ref ResultSuccess, @ref ResultNotInitialized, @ref ResultResetReceived, そのほか、UDS APIが返しうるリザルトコードが返される可能性があります。 */ nn::Result Process(void); /*! @brief 処理を中断します。 プレイヤーの指示により、通信を強制的に中断したい場合などに 呼ばれることを想定しています。 この関数呼び出しにより、Receiverインスタンスは RECEIVER_STATE_CLOSED 状態に移行します。 この関数は、例外的に、@ref Process の実行を待たずに処理が実行されます。 @return ありません。@ref Cancel 呼び出しは必ず成功します。 */ void Cancel(void); /*! @brief Receiverインスタンスの状態を取得します。 @return 関数呼び出し時点でのインスタンスの状態が返されます。 */ enum ReceiverState GetStatus(void) const; /*! @brief 擬似的にパケロス率を設定します（デバッグ用）。この関数は、将来のリリースにおいて予告無く削除される可能性があります。 @param[in] per 0 <= per <= 100の値を与えます。 @return ありません。 */ void SetPacketLossRatio(int per); /*! @brief Receiverインスタンスの詳細な内部状態をプリントします（デバッグ用）。この関数は、将来のリリースにおいて予告無く削除される可能性があります。 @return ありません。 */ void PrintDebugInfo(void) const; private: /*! @brief コピーコンストラクタは封印します。 */ Receiver (const Receiver&); /*! @brief 代入演算子は封印します。 */ Receiver& operator=(const Receiver&); /*! @brief プライベートメンバ変数。 */ ReceiverImpl *m_pImpl; }; }}} // namespace nn::rdt::CTR #endif // end of NN_RDT_RECEIVER_H_