CTR-Pia  5.4.3
Game Communication Engine
 全て クラス ネームスペース 関数 変数 型定義 列挙型 列挙型の値 ページ
transport_UnreliableProtocol.h
1 /*--------------------------------------------------------------------------------*
2  Copyright (C)Nintendo All rights reserved.
3 
4  These coded instructions, statements, and computer programs contain proprietary
5  information of Nintendo and/or its licensed developers and are protected by
6  national and international copyright laws. They may not be disclosed to third
7  parties or copied or duplicated in any form, in whole or in part, without the
8  prior written consent of Nintendo.
9 
10  The content herein is highly confidential and should be handled accordingly.
11  *--------------------------------------------------------------------------------*/
12 
13 
14 #pragma once
15 
16 #include <nn/pia/transport/transport_Definitions.h>
17 
18 #include <nn/pia/transport/transport_Protocol.h>
19 #include <nn/pia/common/common_PacketDefine.h>
20 
21 
22 // 先行宣言。
23 namespace nn
24 {
25 namespace pia
26 {
27 namespace transport
28 {
29 class ReceivedDataContainer;
30 }
31 }
32 }
33 
34 
35 namespace nn
36 {
37 namespace pia
38 {
39 namespace transport
40 {
41 
42 
43 /*!
44  @brief 信頼性の無い(データ欠落の可能性がある)プロトコルのクラスです。
45  UnreliableProtocol は、データ到着の順序を保証しません。
46  送信側がデータを Send() した順で受信側がデータを Receive() できるとは限りません。
47  */
49 {
50 public:
51  /*!
52  @brief UnreliableProtocol で一度に送信/受信が可能なデータサイズの最大値です。単位はバイトです。
53 
54  @details この定数値は 1440 ですが、アプリケーションが小さめの MTU 値を設定した場合には、実際に
55  送受信可能なデータサイズはこの値よりも小さくなります。
56  */
57  static const uint32_t MaxDataSize = common::ProtocolMessgaePayloadSizeMax;
58 
59 
60  /*!
61  @brief 一度に送信可能なデータサイズの上限を取得します。単位はバイトです。
62 
63  @details この API 呼び出しで返される値は、アプリケーションによる MTU 値の設定や、
64  パケットへの署名の有無に影響されます。
65  この関数はスレッドセーフです。
66  @details アプリケーションがメッシュを使用する場合は、メッシュのスタートアップ処理が
67  完了した後でこの API を呼び出す必要があります。これよりも早いタイミングで
68  呼び出すと、正しい値が返されません。
69  @details アプリケーションがセッションを使用する場合は、セッション参加後にこの API を
70  呼び出す必要があります。これよりも早いタイミングで呼び出すと、正しい値が
71  返されないことがあります。
72  @return Send(), SendToAll() で一度に送信可能なデータサイズの上限が返されます。単位はバイトです。
73 
74  @see Send, SendToAll
75  */
76  uint32_t GetDataSizeLimit(void);
77 
78 
79  /*!
80  @cond PRIVATE
81  @brief デフォルトコンストラクタです。
82 
83  @details アプリケーションプログラムは、このコンストラクタを直接呼び出してはいけません。
84  インスタンスの作成は、 @ref Transport::CreateProtocol を利用してください。
85  */
86  UnreliableProtocol(void);
87  //! @endcond
88 
89 
90  /*!
91  @cond PRIVATE
92  @brief デストラクタです。
93 
94  @details アプリケーションプログラムは、このデストラクタを直接呼び出してはいけません。
95  インスタンスの破棄は、 @ref Transport::DestroyProtocol を利用してください。
96  */
97  virtual ~UnreliableProtocol(void);
98  //! @endcond
99 
100 
101  /*!
102  @cond PRIVATE
103  @brief ディスパッチ関数です。
104 
105  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
106  @retval ResultInvalidState UnreliableProtocol::Initialize() が実行されていない可能性があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
107  */
108  virtual Result Dispatch(void);
109  //! @endcond
110 
111 
112  virtual Result UpdateProtocolEvent(const ProtocolEvent& event);
113 
114 
115  PIA_PROTOCOL_TYPE_INFO(ProtocolTypeUnreliable);
116 
117 
118  /*!
119  @brief インスタンスを初期化します。
120 
121  @details BeginSetup() ~ EndSetup() 間で呼び出す必要があります。
122  <br>
123 
124  @param[in] recvBufNum 受信バッファの個数。受信バッファ1個につき、約 1500 バイトのメモリが使用されます。
125  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
126  @retval ResultNotInitialized transport モジュールが未初期化です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
127  @retval ResultAllocationFailed メモリ確保に失敗しました。 common::Initialize() 呼び出し時に、より多くのメモリを供給することを検討してください。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
128  @retval ResultAlreadyInitialized UnreliableProtocol は既に初期化されています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
129  @retval ResultInvalidArgument 引数が誤っています。 recvBufNum に 0 を指定するなどした場合に返されます。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
130  @retval ResultInvalidState BeginSetup() ~ EndSetup() 間で呼び出されていません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
131  @see Finalize
132  */
133  Result Initialize(uint32_t recvBufNum = 32);
134 
135 
136  /*!
137  @brief インスタンスの終了処理を実行します。
138 
139  @details Initialize() が呼び出されていない状態でこの関数を呼び出した場合は、何もせずに返ります。
140  <br>
141  @see Initialize
142  */
143  void Finalize(void);
144 
145 
146  /*!
147  @cond PRIVATE
148  @brief 通信を開始します。
149 
150  @param[in] localStationAddress 自分の(ローカルの) StationAddress 。
151  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
152  @retval ResultInvalidArgument 引数に誤りがあります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
153  @retval ResultInvalidState 既に Startup() は呼ばれています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
154 
155  */
156  virtual Result StartupWithStationAddress(const common::StationAddress& localStationAddress);
157  //! @endcond
158 
159 
160  /*!
161  @cond PRIVATE
162  @brief 通信を終了します。
163  */
164  virtual void CleanupWithStationAddress(void);
165  //! @endcond
166 
167 
168  /*!
169  @brief 受信したデータをバッファに読み取ります。
170 
171  @details データを受信します。ただし、この関数呼び出しが無線モジュールの受信処理実行のトリガーとなっている
172  わけではありません。
173  無線モジュールからパケットを受信する処理は、 Pia 内部の受信スレッドによって定期的に実行されています。
174  この受信スレッドが受信したパケットは、 PiaTransport のディスパッチ処理が実行されるタイミングで
175  パケット解析処理用バッファにコピーされ、データが復元されます。
176  この関数は、このようにして復元されたデータをアプリケーション側で用意したバッファにコピーする処理を実行します。
177 
178  @param[out] pSrcId 読み取ったデータの送信元 StationId が書き込まれます。
179  @param[out] pRecvBuf データの読み取り先バッファです。
180  @param[out] pRecvDataSize 実際に読み取ることのできたデータサイズが書き込まれます。単位はバイトです。
181  @param[in] recvBuffSize データの読み取り先バッファのサイズを指定します。単位はバイトです。
182 
183  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
184  @retval ResultInvalidArgument 引数に誤りがあります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
185  @retval ResultInvalidState UnreliableProtocol::Initialize() が呼ばれていなかったり、session のセットアップが完了していない可能性があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
186  @retval ResultBufferShortage 読み取りバッファのサイズが不足しています。 recvBuffSize で指定したサイズを上回る大きさのデータが到着していた場合に返されます。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
187  @retval ResultNoData 受信バッファが空っぽで、読み取ることのできるデータがありませんでした。アプリケーションで適切にハンドリングしてください。
188  @retval ResultNotInCommunication 通信が可能な状態ではありません。アプリケーションで適切にハンドリングしてください。
189  @retval ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。
190  @see Send, SendToAll, MaxDataSize
191  */
192  Result Receive(StationId* pSrcId, void* pRecvBuf, uint32_t* pRecvDataSize, uint32_t recvBuffSize);
193 
194 
195  /*!
196  @cond PRIVATE
197  @brief 受信したデータをバッファに読み取ります。
198  */
199  Result Receive(StationIndex* pSrcId, void* pRecvBuf, uint32_t* pRecvDataSize, uint32_t recvBuffSize);
200  //! @endcond
201 
202 
203  /*!
204  @brief データを特定のステーションに向けて送信します。
205 
206  @details データを送信します。ただし、この関数を呼び出しただけでは実際のデータ送信は行われません。
207  この関数は、アプリケーションが渡したデータを Pia 内部のパケット生成処理用バッファにコピーします。
208  その後、 PiaTransport のディスパッチ処理が実行されることで、パケット生成処理用バッファにコピー
209  されていたデータ群がパケットにまとめられ、 Pia 内部の送信スレッドに渡されます。実際の送信処理は、
210  この送信スレッドが定期的にパケットを無線モジュールに渡すことで行われます。
211 
212  @param[in] destId 送信先の StationId 。
213  @param[in] pData 送信したいデータの先頭を指すポインタ。
214  @param[in] dataSize 送信データサイズ。単位はバイトです。 GetDataSizeLimit() が返す値を超過してはいけません。
215  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
216  @retval ResultInvalidArgument 引数に誤りがあります。送信データサイズが過大であった場合にも、このエラーが返されます。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
217  @retval ResultInvalidState UnreliableProtocol::Initialize() が呼ばれていなかったり、session のセットアップが完了していない可能性があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
218  @retval ResultNotInCommunication 通信が可能な状態ではありません。アプリケーションで適切にハンドリングしてください。
219  @retval ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。
220  @retval ResultNotFound 指定された送信先が見つかりません。
221  @see SendToAll, Receive, MaxDataSize, GetDataSizeLimit, IsInCommunication
222  */
223  Result Send(StationId destId, const void* pData, uint32_t dataSize);
224 
225 
226  /*!
227  @cond PRIVATE
228  @brief データを特定のステーションに向けて送信します。
229  */
230  Result Send(StationIndex destId, const void* pData, uint32_t dataSize);
231  //! @endcond
232 
233 
234  /*!
235  @brief データを全ステーションに向けて送信します。
236 
237  @details データを送信します。ただし、この関数を呼び出しただけでは実際のデータ送信は行われません。
238  この関数は、アプリケーションが渡したデータを Pia 内部のパケット生成処理用バッファにコピーします。
239  その後、 PiaTransport のディスパッチ処理が実行されることで、パケット生成処理用バッファにコピー
240  されていたデータ群がパケットにまとめられ、 Pia 内部の送信スレッドに渡されます。実際の送信処理は、
241  この送信スレッドが定期的にパケットを無線モジュールに渡すことで行われます。
242 
243  @param[in] pData 送信したいデータの先頭を指すポインタ。
244  @param[in] dataSize 送信データサイズ。単位はバイトです。 GetDataSizeLimit() が返す値を超過してはいけません。
245  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
246  @retval ResultInvalidArgument 引数に誤りがあります。送信データサイズが過大であった場合にも、このエラーが返されます。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
247  @retval ResultInvalidState UnreliableProtocol::Initialize() が呼ばれていない可能性があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
248  @retval ResultNotInCommunication 通信が可能な状態ではありません。アプリケーションで適切にハンドリングしてください。
249  @retval ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。
250  @see Send, Receive, MaxDataSize, GetDataSizeLimit, IsInCommunication
251  */
252  Result SendToAll(const void* pData, uint32_t dataSize);
253 
254 
255  /*!
256  @cond PRIVATE
257  @brief データを複数ステーションに向けて送信します。
258  */
259  Result SendToMulti(uint32_t stationBitmap, const void* pData, uint32_t dataSize);
260  //! @endcond
261 
262 
263  /*!
264  @brief 通信可能な状態であるかどうかを判定します。
265 
266  @return 通信が可能な状態であれば true 、そうでなければ false が返されます。
267  */
268  bool IsInCommunication(void) const;
269 
270 
271  /*!
272  @brief デバッグに有用な情報をプリントします。
273 
274  @param[in] flag トレースフラグの論理和。詳細は @ref TraceFlag 型を参照してください。
275  */
276  virtual void Trace(uint64_t flag) const;
277 
278 
279 private:
280  Result sendImpl(StationIndex destId, const void* pData, uint32_t dataSize);
281 
282 protected:
283  void* m_pRawBuffer; // m_pReceiveBuffer に渡される生メモリ。
284  ReceivedDataContainer* m_pReceiveBuffer;
285 
286  StationIndex m_LocalStationIndex;
287 };
288 }
289 }
290 } // end of namespace nn::pia::transport