CTR-Pia  5.4.3
Game Communication Engine
 全て クラス ネームスペース 関数 変数 型定義 列挙型 列挙型の値 ページ
transport_Transport.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_Singleton.h>
19 #include <nn/pia/transport/transport_ProtocolManager.h>
20 
21 #include <nn/pia/common/common_Time.h>
22 #include <nn/pia/common/common_Job.h>
23 
24 
25 // 先行宣言(common)
26 namespace nn
27 {
28 namespace pia
29 {
30 namespace common
31 {
32 class IPacketInput;
33 class IPacketOutput;
34 class StationAddress;
35 struct CryptoSetting;
36 }
37 }
38 }
39 
40 
41 namespace nn
42 {
43 namespace pia
44 {
45 namespace transport
46 {
47 
48 
49 // 先行宣言(transport)
50 class NetworkFactory;
51 class StationConnectionInfo;
52 class KeepAliveSender;
53 class KeepAliveReceiver;
54 class ThreadStreamManager;
55 class IRelayAddressTable;
56 class RelayRouteManager;
57 class PacketHandler;
58 class Station;
59 class StationIdTable;
60 
61 
62 /*!
63  @brief transport モジュールの中核的な存在のクラスです。
64 
65  */
67 {
68 public:
69  /*!
70  @brief CreateInstance() に各種パラメータを渡すための構造体です。
71 
72  @details この構造体に設定する内部バッファのパラメータは、 PiaTransport のメモリ使用量に
73  直結します。大きな値を設定すれば、送受信処理において内部バッファ枯渇による
74  ResultBufferIsFull エラーの発生頻度を低減させることができ、スムーズな通信処理が
75  期待できますが、もちろんメモリ使用量は増大します。
76  PiaTransport にとって必要十分なメモリ量は、アプリケーションの通信仕様に依存します。
77  これらのパラメータをチューニングするのを支援する手段として、
78  @ref common::WatermarkManager を用意しています。
79  このウォーターマーク機能を用いると、実際にプログラムを動作させた際に、
80  内部バッファ使用量のピーク値などを取得できるので、アプリケーションプログラマが
81  適切な Pia の内部バッファサイズを決定するのに役立ちます。
82  @see CreateInstance, common::WatermarkManager, ThreadStreamManager
83  @if CTR_DOC
84  @see nn::pia::local::UdsNetworkFactory
85  @endif
86  @if NIN_DOC
87  @see nn::pia::local::LdnNetworkFactory
88  @endif
89  @see nn::pia::inet::NexNetworkFactory
90  @see nn::pia::lan::LanNetworkFactory
91  */
92  struct Setting
93  {
94 
95  /*!
96  @brief デフォルトコンストラクタです。
97  */
99  : pFactory(NULL),
100  maxStationNum(0),
103  analysisInterval(0),
106  {
107  }
108 
109  /*!
110  @brief 引数つきコンストラクタです。引数で指定した値が各メンバ変数にセットされます。
111 
112  @param[in] pFactory NetworkFactory から派生させた具象クラスのインスタンスを指すポインタ(ファクトリパターン)。
113  @param[in] maxStationNum 一つのネットワークに参加可能な最大 Station 数を指定します。
114  @param[in] maxSendThreadBufferNum Pia 内部の送信スレッドにおける送信パケット用バッファの個数です(1個につき約1.5KB)。 2 以上の値を設定する必要があります。
115  @param[in] maxReceiveThreadBufferNum Pia 内部の受信スレッドにおける受信パケット用バッファの個数です(1個につき約1.5KB)。 2 以上の値を設定する必要があります。
116  @param[in] analysisInterval TransportAnalyzer による分析データを自動的にコンソールに出力する間隔です。単位は秒です。0 を指定した場合、出力は自動では行われなくなり、データの取得はアプリケーションに委ねられます。
117  @param[in] isAnalysisAutoPrintDetail TransportAnalyzer による分析データを自動的にコンソールに出力する際に、Pia 内部で使用されているプロトコルも出力する場合は true を設定します。
118  @param[in] isAnalysisAutoPrintTotalOnly TransportAnalyzer による分析データを自動的にコンソールに出力する際に、ユニキャスト送信とブロードキャスト送信を分けた分析データも出力する場合は false を設定します。インターネット通信時にはこの設定は無視され、これらを分けた分析データは出力されません。
119 
120  @if CTR_DOC
121  @see nn::pia::local::UdsNetworkFactory
122  @endif
123  @if NIN_DOC
124  @see nn::pia::local::LdnNetworkFactory
125  @endif
126  @see nn::pia::inet::NexNetworkFactory
127  @see nn::pia::lan::LanNetworkFactory
128  */
129  Setting(
131  uint16_t maxStationNum = 0,
132  uint32_t maxSendThreadBufferNum = 0,
133  uint32_t maxReceiveThreadBufferNum = 0,
134  int32_t analysisInterval = 0,
135  bool isAnalysisAutoPrintDetail = true,
136  bool isAnalysisAutoPrintTotalOnly = false);
137 
138  NetworkFactory* pFactory; //!< NetworkFactory から派生させた具象クラスのインスタンスを指すポインタ(ファクトリパターン)。
139  uint16_t maxStationNum; //!< 一つのネットワークに参加可能な最大 Station 数を指定します。
140  uint32_t maxSendThreadBufferNum; //!< Pia 内部の送信スレッドにおける送信パケット用バッファの個数です(1個につき約1.5KB)。 2 以上の値を設定する必要があります。
141  uint32_t maxReceiveThreadBufferNum; //!< Pia 内部の受信スレッドにおける受信パケット用バッファの個数です(1個につき約1.5KB)。 2 以上の値を設定する必要があります。
142  int32_t analysisInterval; //!< TransportAnalyzer 機能による測定結果を自動的にコンソールに出力する間隔です。単位は秒です。0 を指定した場合、出力は自動では行われなくなり、データの取得はアプリケーションに委ねられます。
143  bool isAnalysisAutoPrintDetail; //!< TransportAnalyzer 機能による測定結果を自動的にコンソールに出力する際に、Pia 内部で使用されているプロトコルも出力する場合は true を設定します。
144  bool isAnalysisAutoPrintTotalOnly; //!< TransportAnalyzer 機能による測定結果を自動的にコンソールに出力する際に、ユニキャスト送信とブロードキャスト送信の解析結果も出力する場合は false を設定します。
145  };
146 
147 
148  /*!
149  @cond PRIVATE
150  @brief コンストラクタです。アプリケーションはこのコンストラクタを直接呼び出すのではなく、 CreateInstance() を使う必要があります。
151  */
152  Transport(void);
153  //! @endcond
154 
155 
156  /*!
157  @cond PRIVATE
158  @brief デストラクタです。
159  */
160  virtual ~Transport(void);
161  //! @endcond
162 
163 
164  /*!
165  @brief Transport クラスのインスタンスを作成します(シングルトンパターン)。
166 
167  @param[in] setting 各種パラメータが書き込まれた Setting 構造体。
168 
169  @return インスタンスの作成に成功すれば、成功の Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
170  @retval ResultNotInitialized transport モジュールが未初期化です。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
171  @retval ResultInvalidState CreateInstance() を呼ぶタイミングが誤っています。 BeginSetup() ~ EndSetup() 間で呼び出す必要があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
172  @retval ResultAlreadyExists 既にインスタンスは作成されています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
173  @retval ResultInvalidArgument 引数が誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
174  @retval ResultAllocationFailed 内部でメモリ確保に失敗しました。 common::Initialize() で Pia に供給するメモリを増やすか、よりメモリ消費量の少ないパラメータ設定を試す必要があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
175  @see DestroyInstance, GetInstance, Setting
176  */
177  static Result CreateInstance(const Transport::Setting& setting);
178 
179 
180  /*!
181  @brief Transport クラスのインスタンスを破棄します(シングルトンパターン)。
182  インスタンスが存在していなかった場合は、何もしません。
183 
184  @see CreateInstance, GetInstance
185  */
186  static void DestroyInstance(void);
187 
188 
189  /*!
190  @brief Transport クラスのインスタンスを得ます(シングルトンパターン)。
191  事前に CreateInstance() によってインスタンスを作成していない場合は、
192  NULL ポインタが返されます。
193  この関数はスレッドセーフです。
194 
195  @return Transport インスタンスへのポインタ。
196  @see CreateInstance, DestroyInstance
197  */
198  static Transport* GetInstance(void)
199  {
200  return s_pInstance;
201  }
202 
203 
204  /*!
205  @cond PRIVATE
206  @brief スタートアップ処理を実行します。
207 
208  @details transport::EndSetup() 呼び出しで transport モジュールの
209  初期化処理を終えた後で呼び出す必要があります。
210  @param[in] mtuSize パケットの MTU を指定します。単位はバイトです。
211  @param[in] cpRelayNodeAddress リレーノードのアドレスへのポインタです。
212  一時的なインスタンスへのポインタで構いません。
213  リレーノードを使用しない場合はNULLを指定する必要があります。
214  @param[in] cpCryptoSetting 暗号化設定へのポインタです。
215  NULL を指定した場合は暗号化されません。
216  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
217  @retval ResultInvalidState 既に Startup() が呼ばれているか、
218  transport::BeginSetup() ~ transport::EndSetup() 区間の中で
219  呼び出されている可能性があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
220  @see Cleanup, transport::EndSetup
221  */
222  Result Startup(uint32_t mtuSize, const common::StationAddress* cpRelayNodeAddress = NULL, const common::CryptoSetting* cpCryptoSetting = NULL);
223 //! @endcond
224 
225 
226  Result UpdateLocalStationKey();
227 
228  /*!
229  @cond PRIVATE
230  @brief PacketHandler の暗号化設定を更新します。
231  @param[in] cpCryptoSetting 暗号化設定へのポインタです。NULL を指定した場合は暗号化されません。
232  @retval ResultInvalidArgument 引数が誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
233  */
234  Result UpdateSetting(const common::CryptoSetting* cpCryptoSetting);
235 //! @endcond
236 
237 
238  /*!
239  @cond PRIVATE
240  @brief クリーンアップ処理を実行します。
241 
242  @details transport モジュールの終了処理を実行する前に呼び出す必要があります。
243  <br>
244  @see Startup
245  */
246  void Cleanup(void);
247  //! @endcond
248 
249  void ReserveRestartup()
250  {
251  m_IsRestartupReserved = true;
252  }
253 
254  bool IsRestartupReserved() const
255  {
256  return m_IsRestartupReserved;
257  }
258 
259  Result Restartup(const common::StationAddress* cpRelayNodeAddress = NULL, const common::CryptoSetting* cpCryptoSetting = NULL);
260 
261  /*!
262  @brief T型のプロトコルのインスタンスを生成します。
263 
264  @details @tparam T プロトコルの型を指定します。
265  @param[in] port プロトコルのポートの値です。
266 
267  @return 生成したプロトコルのハンドルです。同じプロトコル ID のものが既にある場合は 0 を返します。
268  @see DestroyProtocol, GetProtocol
269  */
270  template <typename T>
271  uint32_t CreateProtocol(uint16_t port = 0)
272  {
273  return m_ProtocolManager.CreateProtocol<T>(port);
274  }
275 
276 
277  /*!
278  @brief プロトコルのインスタンスを破棄します。
279 
280  @param[in] protocolHandle 削除したいプロトコルのハンドルです。
281  @see CreateProtocol, GetProtocol
282  */
283  void DestroyProtocol(uint32_t protocolHandle)
284  {
285  m_ProtocolManager.DestroyProtocol(protocolHandle);
286  }
287 
288 
289  /*!
290  @brief T型のプロトコルのインスタンスを取得します。
291 
292  @details @tparam T プロトコルの型を指定します。
293  @param[in] protocolHandle 取得したいプロトコルのハンドルです。
294 
295  @return プロトコルのインスタンスのアドレスです。指定されたハンドルのプロトコルが存在しなかったり、T型でなかったりした場合は NULL を返します。
296  @see CreateProtocol, DestroyProtocol
297  */
298  template <typename T>
299  T* GetProtocol(uint32_t protocolHandle)
300  {
301  return m_ProtocolManager.GetProtocol<T>(protocolHandle);
302  }
303 
304 
305  /*!
306  @cond PRIVATE
307  @brief transport モジュールにおける接続状態を返します。
308 
309  @details この関数はスレッドセーフです。
310  <br>
311  @return ネットワーク接続に問題がなければ、 IsSuccess() が true となる Result が返されます。
312  @retval ResultInvalidState アプリケーションが適切な初期化関数/セットアップ関数を呼び出していない
313  疑いがあります。例えば、インターネット接続を試みようとしていながら、
314  ソケットライブラリが未初期化だった場合、この Result が返されます。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
315  @cond CTR_DOC
316  @retval ResultNetworkConnectionIsLost ネットワーク接続が断絶したことを示します。無線スイッチ Off や、
317  アクセスポイントの障害などの原因が考えられます。<br>
318  ローカル接続環境でこのエラーが返された場合は、PiaLocal の上位
319  モジュールと PiaLocal の初期化からやり直す必要があります。<br>
320  インターネット接続環境でこのエラーが返された場合は、クリーンアップ処理と
321  NEX サーバーのログアウト処理を行った後、ネットワークのシャットダウン処理
322  (AC のクローズ)を実行する必要があります(ローカル接続環境と同様に初期化から
323  やり直しても問題ありません)。アプリケーションで適切にハンドリングしてください。
324  @endcond
325  @cond CAFE_DOC
326  @retval ResultNetworkConnectionIsLost ネットワーク接続が断絶したことを示します。
327  アクセスポイントの障害などの原因が考えられます。クリーンアップ処理、NEX サーバーからのログアウト処理(インターネット通信時限定)、ネットワークのシャットダウン処理を順に実行してください。
328  @endcond
329  */
330  Result CheckConnectionError(void) const
331  {
332  return m_ConnectionError;
333  }
334  //! @endcond
335 
336 
337  /*!
338  @cond PRIVATE
339  @brief dispatch() を呼び出した直後の時刻を得ます。
340 
341  @return dispatch() 呼び出し直後の時刻が返ります。
342  @see dispatch
343  */
344  const common::Time& GetDispatchedTime(void) const
345  {
346  return m_DispatchedTime;
347  }
348  //! @endcond
349 
350 
351  /*!
352  @brief CreateInstance() 時に設定された、接続可能な最大 Station 数を返します。
353 
354  @details この関数はスレッドセーフです。
355  <br>
356  @return 接続可能な最大 Station 数。
357  @see CreateInstance
358  */
359  uint16_t GetMaxStationNum(void) const
360  {
361  return m_MaxStationNum;
362  }
363 
364 
365  /*!
366  @cond PRIVATE
367  @brief プロトコルマネージャを取得します。
368 
369  @return プロトコルマネージャのアドレスです。
370  */
371  ProtocolManager* GetProtocolManager()
372  {
373  return &m_ProtocolManager;
374  }
375  //! @endcond
376 
377 
378  /*!
379  @cond PRIVATE
380  @brief キープアライブパケット送信間隔を指定します。
381 
382  @param[in] msec キープアライブパケット送信間隔。単位はミリ秒。
383  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
384  @retval ResultInvalidArgument 引数に誤りがあります(負数であるなど)プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
385  @see GetKeepAliveInterval
386  */
387  Result SetKeepAliveInterval(int32_t msec);
388  //! @endcond
389 
390 
391  /*!
392  @brief キープアライブパケット送信間隔を取得します。
393 
394  @details この関数はスレッドセーフです。
395  <br>
396  @return キープアライブパケット送信間隔。単位はミリ秒。
397  @see SetKeepAliveInterval
398  */
399  int32_t GetKeepAliveInterval(void) const;
400 
401 
402  /*!
403  @brief キープアライブ処理を有効にします。
404 
405  @see DisableKeepAlive, IsKeepAliveEnabled
406  */
407  void EnableKeepAlive(void);
408 
409 
410  /*!
411  @brief キープアライブ処理を無効にします。
412 
413  @see EnableKeepAlive, IsKeepAliveEnabled
414  */
415  void DisableKeepAlive(void);
416 
417 
418  /*!
419  @brief キープアライブ処理が有効か無効であるかを返します。
420 
421  @details この関数はスレッドセーフです。
422  <br>
423  @return 有効であれば true 、無効であれば false が返ります。
424  @see EnableKeepAlive, DisableKeepAlive
425  */
426  bool IsKeepAliveEnabled(void) const;
427 
428 
429  /*!
430  @brief 自分自身を示すアドレス(@ref StationConnectionInfo )を取得します。
431 
432  @details ネットワークに接続できていない状態では、取得できるアドレスは不定となります。
433  <br>
434  @param[out] pInfoOut 取得した自分自身を示すアドレスの格納先を示すポインタ
435  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
436  @retval ResultInvalidArgument 引数に誤りがあります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
437  @see GetHostStationConnectionInfo
438  */
439  Result GetLocalStationConnectionInfo(StationConnectionInfo* pInfoOut);
440 
441 
442  /*!
443  @brief セッションホストを示すアドレス(@ref StationConnectionInfo )を取得します。
444 
445  @details ネットワークに接続できていない状態では、取得できるアドレスは不定となります。
446  <br>
447  @param[out] pInfoOut 取得したセッションホストを示すアドレスの格納先を示すポインタ
448  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。この関数がエラーを返さないようにアプリケーションを実装する必要があります。
449  @retval ResultInvalidArgument 引数に誤りがあります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
450  @see GetLocalStationConnectionInfo
451  */
452  Result GetHostStationConnectionInfo(StationConnectionInfo* pInfoOut);
453 
454 
455  /*!
456  @cond PRIVATE
457  @brief 経路表のインスタンスへのポインタを得ます。
458  */
459  IRelayAddressTable* GetRelayAddressTable(void)
460  {
461  return m_pRelayAddressTable;
462  }
463  //! @endcond
464 
465 
466  /// @cond PRIVATE
467  /*!
468  @brief リレー依頼先管理クラスのインスタンスへのポインタを得ます。
469  */
470  RelayRouteManager* GetRelayRouteManagerPtr(void)
471  {
472  return m_pRelayRouteManager;
473  }
474 
475  /*!
476  @brief リレー依頼先管理クラスのインスタンスへのポインタを設定します。
477  */
478  void SetRelayRouteManagerPtr(RelayRouteManager* ptr)
479  {
480  m_pRelayRouteManager = ptr;
481  }
482  //! @endcond
483 
484 
485  /// @cond PRIVATE
486  void SetMonitoringNetworkRtt(bool isBegin);
487  //! @endcond
488 
489  /// @cond PRIVATE
490  PacketHandler* GetPacketHandler(void)
491  {
492  return m_pPacketHandler;
493  }
494  //! @endcond
495 
496 
497  /*!
498  @brief StationId を @ref StationIndex に変換します。
499 
500  @details 自ステーションがセッションに参加していない状態であったり、ジョイントセッション処理中に
501  この API を呼び出した場合は失敗の Result が返されます。
502  @details EVENT_JOIN, EVENT_LEAVE イベントが通知される、セッションの状態変化イベントコールバック内で
503  この関数を呼び出すことは可能です。
504  @details この関数はセッション API 使用時とメッシュ API 使用時とで挙動が異なります。
505  メッシュ API 使用時は、メッシュ未参加の StationId を指定した場合でも変換に成功します。
506 
507  @param[out] pIdx 変換した @ref StationIndex の格納先を示すポインタ
508  @param[in] id 変換する StationId
509  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
510  @retval ResultInvalidArgument 引数に誤りがあります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
511  @retval ResultInvalidState 変換処理を実行できる状態ではありません。session のセットアップが完了していない可能性があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
512  @retval ResultNotFound 指定した @ref nn::pia::StationId "StationId" のステーションはセッションに参加していません。アプリケーションで適切にハンドリングしてください。
513  @retval ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。
514  @see ConvertToStationId, session::Session::SessionEventCallback
515  */
516  Result ConvertToStationIndex(StationIndex* pIdx, StationId id) const;
517 
518 
519  /*!
520  @cond PRIVATE
521  @brief StationId を @ref StationIndex に変換しますが、引数チェックや状態チェックなどを行いません。
522 
523  @details この関数は各種チェックを省いているため、不用意に呼び出すと、
524  メモリアクセス違反などでプログラムがクラッシュする危険があります。
525  @param[in] id 変換する StationId
526  @return 変換に失敗した場合は StationIndex_Invalid が返ります。
527  */
528  StationIndex ConvertToStationIndexUnsafe(StationId id) const;
529  //! @endcond
530 
531 
532  /*!
533  @brief @ref StationIndex を StationId に変換します。
534 
535  @details 自ステーションがセッションに参加していない状態であったり、ジョイントセッション処理中に
536  この API を呼び出した場合は失敗の Result が返されます。
537  @details EVENT_JOIN, EVENT_LEAVE イベントが通知される、セッションの状態変化イベントコールバック内で
538  この関数を呼び出すことは可能です。
539  @details この関数はセッション API 使用時とメッシュ API 使用時とで挙動が異なります。
540  メッシュ API 使用時は、メッシュ未参加の StationIndex を指定した場合でも変換に成功します。
541 
542  @param[out] pId 変換した StationId の格納先を示すポインタ
543  @param[in] idx 変換する @ref StationIndex
544  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
545  @retval ResultInvalidArgument 引数に誤りがあります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
546  @retval ResultInvalidState 変換処理を実行できる状態ではありません。session のセットアップが完了していない可能性があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
547  @retval ResultNotFound 指定した @ref nn::pia::StationIndex "StationIndex" のステーションはセッションに参加していません。アプリケーションで適切にハンドリングしてください。
548  @retval ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。
549  @see ConvertToStationIndex, session::Session::SessionEventCallback
550  */
551  Result ConvertToStationId(StationId* pId, StationIndex idx) const;
552 
553 
554  /*!
555  @cond PRIVATE
556  @brief @ref StationIndex を StationId に変換しますが、引数チェックや状態チェックなどを行いません。
557 
558  @details この関数は各種チェックを省いているため、不用意に呼び出すと、
559  メモリアクセス違反などでプログラムがクラッシュする危険があります。
560  @param[in] idx 変換する StationIndex
561  @return 変換に失敗した場合は StationIdInvalid が返ります。
562  */
563  StationId ConvertToStationIdUnsafe(StationIndex idx) const;
564  //! @endcond
565 
566 
567  /*!
568  @brief Transport の状態をチェックし、送受信処理などが実行できる状態であるかどうかを判定します。
569 
570  @return session モジュールのセットアップが完了しており、各種の API を問題なく呼び出せる状態であれば、
571  IsSuccess() が true を返す Result が返されます。
572  @retval ResultInvalidState session モジュールのセットアップが完了していません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
573  @retval ResultTemporaryUnavailable セッション移行処理中のため、一時的に API を利用できない状態です。ジョイントセッション機能使用時にのみ返ります。アプリケーションで適切にハンドリングしてください。
574  @see ConvertToStationIndex, ConvertToStationId
575  */
577  {
578  PIA_ASSERT((m_TransportStatus.IsSuccess()) || (m_TransportStatus == ResultInvalidState()) || (m_TransportStatus == ResultTemporaryUnavailable()));
579  return m_TransportStatus;
580  }
581 
582 
583  /*!
584  @cond PRIVATE
585  @brief Transport の状態を設定します。session から呼び出されることを想定しています。
586 
587  @param[in] state Transport の状態を Result 値で設定します。設定可能な Result 値は
588  ResultInvalidState、ResultTemporaryUnavailable、ResultSuccess() の3種です。
589  session 側の準備が整ったときは ResultSuccess、
590  セッション移行処理を開始するときは ResultTemporaryUnavailable、
591  session を破棄するときは ResultInvalidState を引数に渡して呼び出す必要があります。
592  @return 呼び出しが成功すれば、IsSuccess() が true を返す Result が返されます。
593  @retval ResultInvalidArgument 引数が誤っています。state として指定可能な Result 値は上記の 3 種類のみです。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
594  */
595  Result SetTransportStatus(Result state);
596  //! @endcond
597 
598 
599  // StationId 変換を StationIdTable クラスを使って行うか、ダイレクトに変換するかの制御
600  void SetStationIdTableEnabled()
601  {
602  m_IsStationIdTableEnabled = true;
603  }
604  void SetStationIdTableDisabled()
605  {
606  m_IsStationIdTableEnabled = false;
607  }
608  bool IsStationIdTableEnabled() const
609  {
610  return m_IsStationIdTableEnabled;
611  }
612 
613  // session はこの API で変換テーブルクラスのインスタンスを取得し、
614  // 更新処理などを実行してもらうことを想定しています。
615  const StationIdTable* GetStationIdTable() const
616  {
617  return m_pStationIdTable;
618  }
619  StationIdTable* GetStationIdTable()
620  {
621  return m_pStationIdTable;
622  }
623 
624  /*!
625  @brief SetDebugSetting() に渡すパラメータをまとめた構造体です。
626  */
628  {
633  {
634  } //!< デフォルトコンストラクタです。各メンバ変数をクリアします。
635 
636  uint32_t sendThreadLatencyEmulationPacketNum; //!< 送信レイテンシエミュレーション機能のためのバッファの個数です(1個につき約1.5KB)。
637  uint32_t receiveThreadLatencyEmulationPacketNum; //!< 受信レイテンシエミュレーション機能のためのバッファの個数です(1個につき約1.5KB)。
638  bool isPacketLossEmulationEnabled; //!< パケロスエミュレーション機能を用いる場合は true をセットする必要があります。
639  };
640 
641 
642  /*!
643  @brief デバッグ用の機能を有効にします。
644 
645  @details 引数で設定した内容で、デバッグ用機能を有効にします。
646  この API を製品版 ROM で呼び出してはなりません。
647  @details この API を使用する際は、Transport::CreateInstance() 呼び出しよりも
648  前に呼び出す必要があります。
649 
650  @return 成功すれば、 IsSuccess()が true を返す Result が返されます。
651  @retval ResultInvalidState この API を呼び出すタイミングが誤っています。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
652  */
653  static Result SetDebugSetting(const struct DebugSetting& setting);
654 
655 
656  /*!
657  @brief デバッグに有用な情報をプリントします。
658 
659  @param[in] flag トレースフラグの論理和。詳細は @ref TraceFlag 型を参照してください。
660  */
661  virtual void Trace(uint64_t flag) const;
662 
663  //n1589:NexFacadeで必要
664  common::IPacketInput* GetInputStream(void);
665  common::IPacketOutput* GetOutputStream(void);
666 
667  uint8_t GetSendingConnectionId() const
668  {
669  return m_SendingConnectionId;
670  }
671 
672  void OutputStreamUpdateEvent(void);
673 
674  // 切断イベント
675  enum DisconnectionEventType
676  {
677  DisconnectionEventType_EventLeave, // 通常離脱
678  DisconnectionEventType_EventRejoin // 別セッションへ合流するために一時的な離脱
679  };
680 
681  // イベントリスナー
682  typedef DisconnectionEventType (*DisconnectionEventListener)(void* pStationIdTableEntry);
683 
684  void RegisterEventListener(DisconnectionEventListener func)
685  {
686  m_EventListener = func;
687  }
688  DisconnectionEventListener GetEventListener()
689  {
690  return m_EventListener;
691  }
692 
693  bool IsConnectionRequestPrincipalIdEnabled() const
694  {
695  return m_IsConnectionRequestPrincipalIdEnabled;
696  }
697 
698  uint32_t GetDispatchCountForTransportAnalyzer() const
699  {
700  return m_DispatchCountForTransportAnalyzer;
701  }
702 
703  void ClearDispatchCountForTransportAnalyzer()
704  {
705  m_DispatchCountForTransportAnalyzer = 0;
706  }
707 
708 private:
709  /*!
710  @cond PRIVATE
711  @brief ディスパッチ関数です。
712 
713  @details この関数を実行すると、 PiaTransport の送受信スレッドとの間でデータが受け渡されたり、
714  各プロトコル固有の送受信処理などが実行されます。
715  この関数は、無線モジュールに対する送受信関数を呼び出してはいませんので、
716  送受信処理待ちによるブロックは発生しません
717  (無線モジュールに対する送受信関数呼び出しは、 PiaTransport の送受信スレッドの中で
718  実行されます)。
719  この関数は、少なくとも毎ゲームフレームに 1 回は呼び出してもらうことを想定しています。
720 
721  @return 成功すれば、 IsSuccess()が true を返す Result が返されます。
722  @retval ResultInvalidState プロトコルの初期化処理などが済んでいない可能性があります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
723  */
724  Result dispatch(void);
725  //! @endcond
726 
727 
728  /*!
729  @cond PRIVATE
730  @brief Transportインスタンスを初期化します。
731 
732  @details 使用するファクトリと、最大 Station 数を設定して初期化します。
733  <br>
734  @param[in] setting 各種パラメータが書き込まれた Setting 構造体。
735  @return 成功すれば、 IsSuccess()が true を返す Result が返されます。
736  @retval ResultInvalidArgument 引数に誤りがあります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
737  @see finalize
738  */
739  Result initialize(const Transport::Setting& setting);
740  //! @endcond
741 
742 
743  /*!
744  @cond PRIVATE
745  @brief 解放処理です。
746  @see initialize
747  */
748  void finalize(void);
749  //! @endcond
750 
751 
752  /*!
753  @brief コピーコンストラクタは封印します。
754  */
755  Transport(const Transport&);
756 
757  /*!
758  @brief 代入演算子は封印します。
759  */
760  Transport& operator=(const Transport&);
761 
762 
763  /*!
764  @brief dispatch() 直後の時刻を更新します。
765 
766  @details CPU負荷低減のため、1回の Dispatch()につき、1回だけ呼び出すようにします。
767  この時刻はキープアライブ処理などに使われます。さほど精度が必要とされる処理では無いので、
768  dispatch() 一回につき一度の更新で十分だと考えます。
769  @see GetDispatchedTime
770  */
771  void updateDispatchedTime(void)
772  {
773  m_DispatchedTime = common::Time::GetTime();
774  }
775 
776 
777  void updateTransportAnalyzer(void);
778 
779 
780  // dispatch() を呼ぶためのジョブ
781  class DispatchJob : public common::Job
782  {
783  protected:
784  virtual ExecuteResult ExecuteCore()
785  {
786  Transport::GetInstance()->dispatch();
787  return Job::ExecuteState_WaitNext;
788  }
789  };
790 
791  common::Time m_DispatchedTime;
792 
793  NetworkFactory* m_pNetworkFactory;
794 
795  ProtocolManager m_ProtocolManager;
796  PacketHandler* m_pPacketHandler;
797 
798  uint16_t m_MaxStationNum;
799 
800  uint8_t m_SendingConnectionId;
801 
802  bool m_IsStartup;
803  bool m_IsRestartupReserved;
804 
805  Result m_ConnectionError;
806  DispatchJob m_DispatchJob;
807 
808  IRelayAddressTable* m_pRelayAddressTable;
809  RelayRouteManager* m_pRelayRouteManager;
810 
811  int32_t m_AnalysisInterval; // TransportAnalyzer::Update() を自動的に呼び出す時間間隔。単位は秒。
812  common::Time m_AnalysisUpdatedTime; // TransportAnalyzer::Update() が最後に呼び出されたときの時間。
813  bool m_IsAnalysisAutoPrintDetail;
814  bool m_IsAnalysisAutoPrintTotalOnly;
815  uint32_t m_DispatchCountForTransportAnalyzer;
816 
817  DisconnectionEventListener m_EventListener;
818 
819  StationIdTable* m_pStationIdTable;
820  bool m_IsStationIdTableEnabled;
821 
822  Result m_TransportStatus; // session によって制御される Transport 側の状態。
823 
824  bool m_IsConnectionRequestPrincipalIdEnabled;
825 
826  static struct DebugSetting s_DebugSetting;
827 
828  static Transport* s_pInstance;
829 };
830 }
831 }
832 } // end of namespace nn::pia::transport