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