CTR-Pia  5.4.3
Game Communication Engine
 全て クラス ネームスペース 関数 変数 型定義 列挙型 列挙型の値 ページ
transport_Station.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/common/common_FixedString.h>
19 #include <nn/pia/common/common_StationAddress.h>
20 #include <nn/pia/common/common_PacketDefine.h>
21 #include <nn/pia/common/common_Time.h>
22 
23 #include <nn/pia/transport/transport_SequenceIdController.h>
24 
25 
26 // 先行宣言
27 namespace nn
28 {
29 namespace pia
30 {
31 namespace common
32 {
33 class StepSequenceJob;
34 }
35 }
36 }
37 
38 
39 namespace nn
40 {
41 namespace pia
42 {
43 namespace transport
44 {
45 
46 
47 // 先行宣言
48 class StationProtocol;
49 class StationProtocolReliable;
50 class RttProtocol;
51 class ConnectStationJob;
52 class DisconnectStationJob;
53 class ProcessConnectionRequestJob;
54 class ReliableSlidingWindow;
55 class NetworkFactory;
56 
57 /*!
58  @brief ステーションを表現するクラスです。ステーションとは、 Pia のセッションに参加しているマシンを指す言葉です。
59 
60  */
62 {
63  friend class StationProtocolReliable;
64 
65 public:
66  static const uint32_t MaxDataSize = common::ProtocolMessgaePayloadSizeMax; // Send() / Receive() で送受信可能なデータサイズの最大値。単位はバイト。
67  static const int32_t InvalidRtt = -1; //!< GetRtt() が返しうる、無効な値です。
68 
69  /*!
70  @brief Station の状態を示す列挙型です。
71  */
73  {
74  StationState_Invalid, //!< 無効な StationState です。
75  StationState_Initial, //!< このステーションが初期化済みである状態を示します。
76  StationState_CreatingSession, //!< このステーションへ接続要求を行い、接続処理を開始した状態を示します。
77  StationState_JoiningSession, //!< このステーションから接続要求を受け、接続処理を開始した状態を示します。
78  StationState_WaitingConnection, //!< このステーションとの通信の確立を待っている状態を示します。
79  StationState_Participating, //!< このステーションと通信可能な状態を示します。
80  StationState_Leaving, //!< このステーションとの通信を切断中である状態を示します。
81  StationState_Max = StationState_Leaving //!< StationState の最大値です。
82  };
83 
84 
85  /*!
86  @cond PRIVATE
87  @brief デフォルトコンストラクタです。
88 
89  @details インスタンスの StationIndex は、 StationIndex_Invalid に設定されます。
90  */
91  Station(void);
92  //! @endcond
93 
94 
95  /*!
96  @cond PRIVATE
97  @brief デストラクタです。
98  */
99  virtual ~Station(void);
100  //! @endcond
101 
102 
103  /*!
104  @cond PRIVATE
105  @brief Station インスタンスを初期化します。
106 
107  @param[in] pFactory NetworkFactory から派生した具象クラスを指定します。このファクトリを用いて、ジョブのインスタンスが生成されます。
108  @param[in] pStationProtocol StationProtocol ポインタです。
109  @param[in] pRttProtocol RttProtocol ポインタです。
110  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
111  @retval ResultInvalidArgument 引数に誤りがあります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
112  @see Finalize
113  */
114  Result Initialize(NetworkFactory* pFactory, StationProtocol* pStationProtocol, RttProtocol* pRttProtocol);
115  //! @endcond
116 
117 
118  /*!
119  @cond PRIVATE
120  @brief Station インスタンスの解放処理を実行します。
121 
122  @see Initialize
123  */
124  void Finalize(void);
125  //! @endcond
126 
127  bool IsStartedUp() const
128  {
129  return m_IsStartedUp;
130  }
131 
132  /*!
133  @brief StationIndex を取得します。
134 
135  @details この関数はスレッドセーフです。
136  @details アプリケーションがジョイントセッション機能を使用する場合は、この関数を呼び出してはいけません。
137  動作保証外となります。
138  <br>
139  @return インスタンスに設定されていた StationIndex が返されます。
140  */
142  {
143  return m_StationIndex;
144  }
145 
146 
147  /*!
148  @cond PRIVATE
149  @brief StationIndex を設定します。
150  @details この関数は SetStationId と連携して使用する必要があります。
151  可能であれば、この関数と SetStationId をほぼ同じタイミングで呼び、
152  Station インスタンスにおける StationIndex と StationId の一貫性を保つ必要があります。
153  StationIndex は決定できたものの、まだ StationId を決定することができない状況も
154  あるかと思いますが、そのときは後で必ず SetStationId を呼び出す必要があります。
155 
156  @param[in] idx このインスタンスに設定する StationIndex 。
157  @see GetStationIndex, SetStationId
158  */
159  void SetStationIndex(StationIndex idx);
160  //! @endcond
161 
162 
163  /*!
164  @brief StationId を取得します。
165 
166  @return Station に対応づけられている StationId が返されます。
167  */
169  {
170  return m_StationId;
171  }
172 
173 
174  /*!
175  @cond PRIVATE
176  @brief StationId を設定します。
177  @details この関数は SetStationIndex と連携して使用する必要があります。
178  可能であれば、この関数と SetStationIndex をほぼ同じタイミングで呼び、
179  Station インスタンスにおける StationIndex と StationId の一貫性を保つ必要があります。
180  StationIndex は決定できたものの、まだ StationId を決定することができない状況も
181  あるかと思いますが、そのときは後で必ず SetStationId を呼び出す必要があります。
182 
183  @param[in] id このインスタンスに設定する StationId 。
184  @see GetStationId, SetStationIndex
185  */
186  void SetStationId(StationId id);
187  //! @endcond
188 
189 
190  /*!
191  @brief ステーションアドレスを取得します。
192 
193  @return 設定されていた StationAddress への const 参照が返されます。
194  */
196  {
197  return m_StationAddress;
198  }
199 
200 
201  /*!
202  @cond PRIVATE
203  @brief ステーションアドレスを設定します。
204 
205  @param[in] addr このインスタンスに設定する StationAddress 。
206  @see GetStationAddress
207  */
208  void SetStationAddress(const common::StationAddress& addr)
209  {
210  m_StationAddress = addr;
211  }
212  //! @endcond
213 
214 
215  /*!
216  @cond PRIVATE
217  @brief ConnectStationJob のポインタを得ます(非 const 版)。
218  @return ConnectStationJob インスタンスを指すポインタ。
219  */
220  ConnectStationJob* GetConnectStationJob(void)
221  {
222  return m_pConnectStationJob;
223  }
224  //! @endcond
225 
226 
227  /*!
228  @cond PRIVATE
229  @brief ConnectStationJob のポインタを得ます( const 版)。
230  @return ConnectStationJob インスタンスを指す const ポインタ。
231  */
232  const ConnectStationJob* GetConnectStationJob(void) const
233  {
234  return m_pConnectStationJob;
235  }
236  //! @endcond
237 
238 
239  /*!
240  @cond PRIVATE
241  @brief DisconnectStationJob のポインタを得ます(非 const 版)。
242  @return DisconnectStationJob インスタンスを指すポインタ。
243  */
244  DisconnectStationJob* GetDisconnectStationJob(void)
245  {
246  return m_pDisconnectStationJob;
247  }
248  //! @endcond
249 
250 
251  /*!
252  @cond PRIVATE
253  @brief DisconnectStationJob のポインタを得ます( const 版)。
254  @return DisconnectStationJob インスタンスを指す const ポインタ。
255  */
256  const DisconnectStationJob* GetDisconnectStationJob(void) const
257  {
258  return m_pDisconnectStationJob;
259  }
260  //! @endcond
261 
262 
263  /*!
264  @cond PRIVATE
265  @brief ProcessConnectionRequestJob のポインタを得ます(非 const 版)。
266  @return ProcessConnectionRequestJob インスタンスを指すポインタ。
267  */
268  ProcessConnectionRequestJob* GetProcessConnectionRequestJob(void)
269  {
270  return m_pProcessConnectionRequestJob;
271  }
272  //! @endcond
273 
274  /*!
275  @cond PRIVATE
276  @brief ProcessConnectionRequestJob のポインタを得ます( const 版)。
277  @return ProcessConnectionRequestJob インスタンスを指す const ポインタ。
278  */
279  const ProcessConnectionRequestJob* GetProcessConnectionRequestJob(void) const
280  {
281  return m_pProcessConnectionRequestJob;
282  }
283  //! @endcond
284 
285  /*!
286  @brief SequenceIdController のポインタを得ます(非 const 版)。
287  この関数はスレッドセーフです。
288  @return SequenceIdController インスタンスを指すポインタ。
289  */
291  {
292  return &m_SequenceIdController;
293  }
294 
295 
296  /*!
297  @brief SequenceIdController のポインタを得ます( const 版)。
298  この関数はスレッドセーフです。
299  @return SequenceIdController インスタンスを指す const ポインタ。
300  */
302  {
303  return &m_SequenceIdController;
304  }
305 
306 
307  /*!
308  @cond PRIVATE
309  @brief Station の受信用の ConnectionId を得ます。
310  @return Station の受信用 ConnectionId。
311  */
312  uint8_t GetReceivingConnectionId(void) const
313  {
314  return m_RecvConnectionId;
315  }
316  //! @endcond
317 
318 
319  /*!
320  @cond PRIVATE
321  @brief Station の受信用の ConnectionId を設定します。
322  @param[in] id この Station インスタンスに設定する受信用 ConnectionId。
323  */
324  void SetReceivingConnectionId(uint8_t id)
325  {
326  m_RecvConnectionId = id;
327  }
328  //! @endcond
329 
330 
331  /*!
332  @brief Station の状態を得ます。
333 
334  @details この関数はスレッドセーフです。
335  <br>
336  @return Station の状態を返します。
337  */
338  StationState GetState(void) const
339  {
340  return m_StationState;
341  }
342 
343 
344  /*!
345  @cond PRIVATE
346  @brief Station の状態を設定します。
347 
348  @param[in] state 設定する状態。
349  @see GetState
350  */
351  void SetState(StationState state)
352  {
353  m_StationState = state;
354  }
355  //! @endcond
356 
357 
358  /*!
359  @cond PRIVATE
360  @brief Stationのスタートアップ処理を行います。
361  @details この関数を呼び出した後に、SetStationId() で StationId を設定し、
362  StationIndex と StationId の一貫性を保つ必要があります。
363  @details この関数を呼び出すと、本インスタンスの StationId は StationIdInvalid に設定されます。
364 
365  @param[in] idx このインスタンスに設定する StationIndex を与えます。
366  @param[in] addr このインスタンスに設定する StationAddress を与えます。
367  @return 成功すれば true 、失敗すれば false が返されます。
368  @see Cleanup, SetStationId
369  */
370  bool Startup(StationIndex idx, const common::StationAddress& addr);
371  //! @endcond
372 
373 
374  /*!
375  @cond PRIVATE
376  @brief Stationのスタートアップ処理を行います。
377  このとき、本インスタンスの StationIndex は StationIndex_Invalid に設定されます。
378  @details この関数を呼び出すと、本インスタンスの StationId は StationIdInvalid に設定されます。
379 
380  @param[in] addr このインスタンスに設定する StationAddress を与えます。
381  @return 成功すれば true 、失敗すれば false が返されます。
382  @see Cleanup
383  */
384  bool Startup(const common::StationAddress& addr);
385  //! @endcond
386 
387 
388  /*!
389  @cond PRIVATE
390  @brief Stationのスタートアップ処理を行います。
391  このとき、本インスタンスの StationIndex は StationIndex_Invalid に設定され、
392  StationAddress は StationAddress::Clear() が実行されたのと等しい状態に設定されます。
393  @details この関数を呼び出すと、本インスタンスの StationId は StationIdInvalid に設定されます。
394 
395  @return 成功すれば true 、失敗すれば false が返されます。
396  @see Cleanup
397  */
398  bool Startup();
399  //! @endcond
400 
401 
402  /*!
403  @cond PRIVATE
404  @brief Station のクリーンアップ処理を行います。
405  Startup() に対応する API です。 Startup() によって設定されていた内容がクリアされます。
406 
407  @see Startup
408  */
409  void Cleanup(void);
410  //! @endcond
411 
412 
413  /*!
414  @brief ローカル Station と、この Station 間の RTT (Round Trip Time) を取得します。
415 
416  @details システムは RTT を取得する目的で、定期的に他 Station に向けてパルスを発信しています。
417  しかし Station がセッションに接続した直後などでは、パルス発信/応答の処理がまだ
418  一度も行われていないタイミングも存在します。
419  このとき GetRtt() は InvalidRtt を返しますが、しばらく時間が経過してから GetRtt() を
420  呼び出せば、正しい値が返されるようになります。
421  本 API は、過去に計測した複数のサンプリング値から得られる中央値を返します。
422  そのため、本 API で得られる値はネットワーク環境の微細な変動による影響を受けにくく、
423  ある程度安定した値が返されます。
424 
425  @return RTT 値が返されます。単位はミリ秒です。
426  @retval InvalidRtt RTT 値を取得できる状態ではなかったときに返される、負の値です。
427  @see SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
428  */
429  int32_t GetRtt(void) const;
430 
431 
432  /*!
433  @brief ローカル Station と、この Station 間の RTT を取得します。 RTT 算出に使用するサンプリング数を指定できます。
434 
435  @details システムは RTT パルス発信/応答によって得られたサンプリング値を複数個保持しています。
436  引数指定なしの GetRtt() では、保持されている全てのサンプリング値を用いて中央値を返しますが、
437  この引数指定ありの GetRtt() は、指定された個数だけのサンプリング値を用いて中央値を返します。
438  このとき、若い側のサンプリング値が使用されるので、小さな値を指定すると、最近のネットワーク環境を
439  強く反映した RTT 値が得られます。
440  その一方で、あまりに小さな値を設定すると、 RTT 値は変動しやすくなります。
441  @param[in] samplingNum RTT の算出に際して、直近のサンプリング値をいくつ使用するかを指定します。
442  @return RTT 値が返されます。単位はミリ秒です。
443  @retval InvalidRtt RTT 値を取得できる状態ではなかったときに返される、負の値です。
444  @see SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
445  */
446  int32_t GetRtt(uint32_t samplingNum) const;
447 
448 
449  /*!
450  @cond PRIVATE
451  @brief ローカル Station と、この Station 間で計測された直近の RTT (Round Trip Time) を取得します。
452 
453  @return システムによって直近に計測された RTT 値が返されます。単位はミリ秒です。
454  @retval InvalidRtt RTT 値を取得できる状態ではなかったときに返される、負の値です。
455 
456  @see GetRtt, SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
457  */
458  int32_t GetLatestRtt(void) const;
459  //! @endcond
460 
461 
462  /*!
463  @cond PRIVATE
464  @brief ローカル Station と、この Station 間で計測された RTT (Round Trip Time) の最小値と最大値を初期化します。
465 
466  @see GetRttMin, GetRttMax
467  */
468  void ResetRttMinMax();
469  //! @endcond
470 
471 
472  /*!
473  @cond PRIVATE
474  @brief ローカル Station と、この Station 間で計測された RTT (Round Trip Time) の最小値を取得します。
475 
476  @return システムによって計測された RTT の最小値が返されます。単位はミリ秒です。
477  @retval InvalidRtt RTT 値を取得できる状態ではなかったときに返される、負の値です。
478 
479  @see GetRtt, SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum, ResetRttMinMax
480  */
481  int GetRttMin() const;
482  //! @endcond
483 
484 
485  /*!
486  @cond PRIVATE
487  @brief ローカル Station と、この Station 間で計測された RTT (Round Trip Time) の最大値を取得します。
488 
489  @return システムによって計測された RTT の最大値が返されます。単位はミリ秒です。
490  @retval InvalidRtt RTT 値を取得できる状態ではなかったときに返される、負の値です。
491 
492  @see GetRtt, SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum, ResetRttMinMax
493  */
494  int GetRttMax() const;
495  //! @endcond
496 
497 
498  /*!
499  @brief システムが保持する RTT (Round Trip Time) サンプリング値の個数を取得します。
500 
501  @details システムは RTT を取得する目的で、定期的に他 Station に向けてパルスを発信し、
502  その応答に要した時間を RTT サンプリング値として保存します。
503  しかし Station がセッションに接続した直後など、パルス発信/応答の処理が
504  開始されたばかりのために、十分な数のサンプリング値が得られていない期間も存在します。
505  本 API は、GetRtt() などが返す RTT 値の算出に用いられているサンプリング値の
506  個数を返しますので、その RTT 値の信頼性/精度を知ることができます。
507 
508  @return システムが保持しているサンプリング値の個数が返されます。
509  @retval 0 RTT 値を取得できる状態ではなかった場合、ゼロが返されます。
510  @see GetRtt, SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval
511  */
512  int32_t GetRttSamplingNum(void) const;
513 
514 
515  /*!
516  @brief RTT 算出のためのパルス送信間隔を設定します。
517 
518  @param[in] msec パルス送信間隔。単位はミリ秒です。
519  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
520  @retval ResultInvalidArgument 引数に誤りがあります。非正数を指定した場合に返されます。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
521  @see GetRttPulseInterval, GetRtt, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
522  */
523  static Result SetRttPulseInterval(int32_t msec);
524 
525 
526  /*!
527  @brief RTT 算出のためのパルス送信間隔を取得します。
528 
529  @return 設定されているパルス送信間隔が返ります。単位はミリ秒です。
530  @see SetRttPulseInterval, GetRtt, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
531  */
532  static int32_t GetRttPulseInterval(void);
533 
534 
535  /*!
536  @brief RTT 算出のための初期パルス送信間隔を設定します。
537 
538  @details RTT 算出のパルス送出は、Station がセッションに参加してから開始されます。
539  そのため、セッション参加直後の段階では、RTT 算出のためのサンプリング値の個数が
540  十分ではありません。
541  そこでシステムは、サンプリング値が十分な個数になるまでは、通常よりも短い間隔で
542  パルス送出を試み、早期にサンプリング値の個数を満足させるように動作します。
543  本 API は、この初期期間におけるパルス送出間隔を設定します。
544 
545  @param[in] msec 初期パルス送信間隔。単位はミリ秒です。
546  @return 成功すれば、 IsSuccess() が true を返す Result が返されます。
547  @retval ResultInvalidArgument 引数に誤りがあります。非正数を指定した場合に返されます。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
548  @see GetInitialRttPulseInterval, GetRtt, SetRttPulseInterval, GetRttPulseInterval, GetRttSamplingNum
549  */
550  static Result SetInitialRttPulseInterval(int32_t msec);
551 
552 
553  /*!
554  @brief RTT 算出のための初期パルス送信間隔を取得します。
555 
556  @details RTT 算出のパルス送出は、Station がセッションに参加してから開始されます。
557  そのため、セッション参加直後の段階では、RTT 算出のためのサンプリング値の個数が
558  十分ではありません。
559  そこでシステムは、サンプリング値が十分な個数になるまでは、通常よりも短い間隔で
560  パルス送出を試み、早期にサンプリング値の個数を満足させるように動作します。
561  本 API は、この初期期間におけるパルス送出間隔を取得します。
562 
563  @return 設定されている初期パルス送信間隔が返ります。単位はミリ秒です。
564  @see SetInitialRttPulseInterval, GetRtt, SetRttPulseInterval, GetRttPulseInterval, GetRttSamplingNum
565  */
566  static int32_t GetInitialRttPulseInterval(void);
567 
568 
569  /*!
570  @cond PRIVATE
571  @brief この Station に設定されている StationProtocol へのポインタを返します(非 const 版)。
572 
573  @return StationProtocolへのポインタ。 StationProtocol が設定されていなければ、 NULL ポインタが返ります。
574  @see Startup
575  */
576  StationProtocol* GetStationProtocol(void)
577  {
578  return m_pStationProtocol;
579  }
580  //! @endcond
581 
582 
583  /*!
584  @cond PRIVATE
585  @brief この Station に設定されている StationProtocol へのポインタを返します( const 版)。
586 
587  @return StationProtocolへのポインタ。 StationProtocol が設定されていなければ、 NULL ポインタが返ります。
588  @see Startup
589  */
590  const StationProtocol* GetStationProtocol(void) const
591  {
592  return m_pStationProtocol;
593  }
594  //! @endcond
595 
596 
597  /*!
598  @cond PRIVATE
599  @brief 最後に送信したパケットの送信時刻を記録します。
600 
601  @details この関数は、主に KeepAliveSender から呼び出されます。
602  @param[in] t パケット送信時刻。
603  @see GetLatestPacketSentTime
604  */
605  void SetLatestPacketSentTime(const common::Time& t)
606  {
607  m_LatestPacketSentTime = t;
608  }
609  //! @endcond
610 
611 
612  /*!
613  @cond PRIVATE
614  @brief 最後に送信したパケットの送信時刻を取得します。
615 
616  @details この関数は、主に KeepAliveSender から呼び出されます。
617  @return 最後に送信したパケットの送信時刻。
618  @see SetLatestPacketSentTime
619  */
620  const common::Time& GetLatestPacketSentTime(void) const
621  {
622  return m_LatestPacketSentTime;
623  }
624  //! @endcond
625 
626 
627  /*!
628  @cond PRIVATE
629  @brief 最後に受信したパケットの受信時刻を記録します。
630 
631  @details この関数は、主に KeepAliveReceiver から呼び出されます。
632  @param[in] t パケット受信時刻。
633  @see GetLatestPacketReceivedTime
634  */
635  void SetLatestPacketReceivedTime(const common::Time& t)
636  {
637  m_LatestPacketReceivedTime = t;
638  }
639  //! @endcond
640 
641 
642  /*!
643  @cond PRIVATE
644  @brief 最後に受信したパケットの受信時刻を取得します。
645 
646  @details この関数は、主に session 層から呼び出され、キープアライブ判定に
647  用いられます。
648  @return 最後に受信したパケットの受信時刻。
649  @see SetLatestPacketReceivedTime
650  */
651  const common::Time& GetLatestPacketReceivedTime(void) const
652  {
653  return m_LatestPacketReceivedTime;
654  }
655  //! @endcond
656 
657 
658  /*!
659  @cond PRIVATE
660  @brief Station の接続/切断処理関連ジョブを強制終了、初期化します。
661  */
662  void CleanupJobs();
663  //! @endcond
664 
665 
666  /*!
667  @brief デバッグに有用な情報をプリントします。
668 
669  @param[in] flag トレースフラグの論理和。詳細は@ref TraceFlag 型を参照してください。
670  */
671  virtual void Trace(uint64_t flag) const;
672 
673 
674  static const uint32_t IdentificationTokenMaxDataSize = 32; //!< 識別トークンの最大データサイズです。
675 
676  /*!
677  @brief Station と結び付けて保存される識別トークン構造体です。
678 
679  @details 識別トークンは、接続した相手と共有されます。
680  */
682  {
683  uint8_t data[IdentificationTokenMaxDataSize]; //!< 識別トークンのデータ列です。
684  };
685 
686  /*!
687  @brief Station に結び付けて保存されるプレイヤー ID の構造体です。
688  @details
689  @if CAFE_DOC
690  Cafe では使用されません。
691  @endif
692  @if CTR_DOC
693  CTR では使用されません。
694  @endif
695  */
696  struct PlayerId
697  {
698  uint64_t id[2];
699  };
700 
703 
704  /*!
705  @brief Station に結び付けて保存されるプレイヤー情報の構造体です。
706  @details プレイヤー名、プレイヤー名の言語タイプは接続した相手と共有されます。プレイヤー ID は共有されません。
707  */
708  struct PlayerInfo
709  {
710  PlayerInfo()
711  {
712  Reset();
713  }
714 
715  /*!
716  @brief 設定をコピーします。
717  */
718  void Copy(const PlayerInfo& rhs)
719  {
722  playerId = rhs.playerId;
723  }
724 
725  /*!
726  @brief 設定をリセットします。
727  */
728  void Reset()
729  {
730  screenName.Clear();
731  nameStringLanguage = 0xff;
732  playerId.id[0] = 0;
733  playerId.id[1] = 0;
734  }
735 
736  /*!
737  @brief プレイヤー名です。名前の長さは MaxPlayerNameLength(NULL終端を含めない)以内である必要があります。
738  @if CAFE_DOC 文字コードは UTF-16BE である必要があります。 @endif
739  @if CTR_DOC 文字コードは UTF-16 である必要があります。 @endif
740  @if NIN_DOC 文字コードは UTF-8 である必要があります。 「いっしょにあそんだ人の記録」に「ゲーム中での名前」として表示されます。@endif
741  */
743  /*!
744  @brief プレイヤー名の言語タイプです。
745  @if CAFE_DOC nn::fp::Language で定義される値で指定して下さい。 @endif
746  @if CTR_DOC 本体の言語設定を使用したい場合には、nn::cfg::CTR::GetLanguage() の値を使用可能です。 @endif
747  @if NIN_DOC nn::settings::Language の enum 値を uint8_t にキャストして指定してください。@endif
748  */
750  /*!
751  @brief プレイヤー ID です。
752  @if CAFE_DOC 使用されません。@endif
753  @if CTR_DOC 使用されません。@endif
754  @if NIN_DOC アカウントシステムに登録されたユーザーの識別子(nn::account::Uid)を指定します。指定しない場合はゲストプレイヤーとして扱い、「いっしょにあそんだ人の記録」には記録しません。@endif
755  */
757  };
758 
759  /*!
760  @cond PRIVATE
761  @brief Station に結び付けて保存されるプレイヤーの登録キー構造体です。
762  */
763  static const uint32_t PlayerRegistrationKeySize = 64;
764  struct PlayerRegistrationKey
765  {
766  uint8_t data[PlayerRegistrationKeySize];
767  };
768  //! @endcond
769 
770  /*!
771  @brief Station の識別トークンを取得します。
772 
773  @details ローカル Station の場合は @ref session::Session::Startup で設定した識別トークンを取得します。
774  ローカル Station 以外の Station の場合は接続時に共有している識別トークンを取得します。
775  設定していない場合、この API の処理には成功しますが、取得した識別トークンのデータは全て NULL となります。
776 
777  識別トークンの取得に失敗した場合、格納先として指定された識別トークンの内部値を変更することはありません。
778 
779  @param[out] pToken Station の識別トークンが取得できた場合、pToken に格納されます。
780  @return 正常に識別トークンを取得できた場合、IsSuccess() が真となる Result を返します。失敗した場合、以下の Result を返します。
781  @retval ResultInvalidState 関数が実行可能な状態ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
782  @retval ResultInvalidArgument 引数で指定されたポインタが有効ではない場合に返ります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
783  @retval ResultNoData 指定された Station の識別トークンが取得できなかった場合に返ります。識別トークンの共有が完了していない可能性があります。アプリケーションで適切にハンドリングしてください。
784  */
785  Result GetIdentificationToken(IdentificationToken* pToken);
786 
787  /*!
788  @brief Station と結びつけられているプレイヤー情報を取得します。
789  @details ローカル Station の場合は @ref session::Session::Startup で設定したプレイヤー情報を取得します。
790  ローカル Station 以外の Station の場合は接続時に共有しているプレイヤー情報を取得します。
791  ただし、取得したプレイヤー情報のプレイヤー ID の値は不定のため、使用してはいけません。<br >
792  <br >
793  プレイヤー情報の取得に失敗した場合、格納先として指定された変数の内部値を変更することはありません。
794 
795  @param[in] index Station と結び付けられているプレイヤー情報リストから情報を取得したいプレイヤーのインデックス
796  @param[out] pInfo 取得するプレイヤー情報のコピー先
797  @return 正常に情報を取得できた場合、IsSuccess() が真となる Result を返します。失敗した場合、以下の Result を返します。
798  @retval ResultInvalidState 関数が実行可能な状態ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
799  @retval ResultInvalidArgument 引数で指定されたインデックスやポインタが有効ではない場合に返ります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
800  @retval ResultNoData 指定された Station の情報が取得できなかった場合に返ります。情報の共有が完了していない可能性があります。アプリケーションで適切にハンドリングしてください。
801  */
802  Result GetPlayerInfo(uint8_t index, PlayerInfo* pInfo);
803 
804  /*!
805  @brief Station のプリンシパル ID を取得します。
806  @details プリンシパル ID はセッション参加後に取得できます。
807  プリンシパル ID の取得に失敗した場合、格納先として指定されたプリンシパル ID の内部値を変更することはありません。<br />
808  本 API で取得するプリンシパル ID はネットワーク種別によって以下のように設定されます。
809  <ul>
810  @if CTR_DOC
811  <li>インターネットマッチメイクの場合、ゲームサーバーから設定されるプリンシパル ID</li>
812  @endif
813  @if CAFE_DOC
814  <li>インターネットマッチメイクの場合、ゲームサーバーから設定されるプリンシパル ID</li>
815  @endif
816  @if NIN_DOC
817  <li>インターネットマッチメイクの場合、ゲームサーバーにログインしたユーザーアカウントに連携されているネットワークサービスアカウント ID</li>
818  @endif
819  <li>ローカルマッチメイクの場合、ステーションアドレスと Tick 値を元に生成する ID(重複する可能性はほぼゼロです)</li>
820  <li>LAN マッチメイクの場合、ステーションアドレスと Tick 値を元に生成する ID(重複する可能性はほぼゼロです)</li>
821  </ul>
822 
823  @param[out] pPrincipalId Station のプリンシパル ID が取得できた場合、pPrincipalId に格納されます。
824  @return 正常にプリンシパル ID を取得できた場合、IsSuccess() が真となる Result を返します。失敗した場合、以下の Result を返します。
825  @retval ResultInvalidState 関数が実行可能な状態ではありません。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
826  @retval ResultInvalidArgument 引数で指定されたポインタが有効ではない場合に返ります。プログラミングエラーです。このエラーが返らないようにソースコードを修正してください。
827  @retval ResultNoData 指定された Station のプリンシパル ID が取得できなかった場合に返ります。ステーション情報の共有が完了していない可能性があります。アプリケーションで適切にハンドリングしてください。
828  */
829  Result GetPrincipalId(PrincipalId* pPrincipalId);
830 
831  /*!
832  @brief Station のプレイヤー数を取得します。
833  */
834  Result GetPlayerCount(uint8_t* pPlayerCount);
835 
836  /*!
837  @brief Station のマッチメイク参加者数を取得します。
838  */
839  Result GetParticipantCount(uint8_t* pParticipantCount);
840 
841  /*!
842  @cond PRIVATE
843  @brief 対象の Station との通信経路が直通接続か否かを設定します。
844  */
845  void SetConnectionRoute(bool isDirect)
846  {
847  m_IsConnectionRouteDirect = isDirect;
848  }
849  //! @endcond
850 
851  /*!
852  @cond PRIVATE
853  @brief 対象の Station との通信経路がリレー接続か否かを取得します。
854  @return リレー接続の場合は true, 接続できていない場合や通信経路がそれ以外の場合は false を返します。
855  */
856  bool IsConnectionRouteRelay() const;
857  //! @endcond
858 
859  /*!
860  @cond PRIVATE
861  @brief 対象の Station との接続経路が直通接続か否かを取得します。
862  @return 直通接続の場合は true, 接続できていない場合や通信経路がそれ以外の場合は false を返します。
863  */
864  bool IsConnectionRouteDirect() const;
865  //! @endcond
866 
867  /*!
868  @cond PRIVATE
869  */
870  bool GetDisconnectImmidiatelyFlag() const
871  {
872  return m_IsDisconnectImmidiately;
873  }
874  //! @endcond
875 
876  /*!
877  @cond PRIVATE
878  */
879  void SetDisconnectImmidiatelyFlag(bool flag)
880  {
881  m_IsDisconnectImmidiately = flag;
882  }
883  //! @endcond
884 private:
885  // Startup()とCleanup()における共通処理をまとめるために用意したヘルパ関数です。
886  // 第一引数で、スタートアップ処理か、クリーンアップ処理かを切り替えます。
887  // 第二引数以降で与えられた引数は、メンバ変数に無条件にセットします(すなわち、引数チェック無し)。
888  void helperStartupCleanup(bool bStartup, StationIndex idx, const common::StationAddress& addr, StationState state);
889 
890  bool m_IsStartedUp;
891 
892  common::StationAddress m_StationAddress;
893  StationIndex m_StationIndex;
894  StationId m_StationId;
895  StationState m_StationState;
896  ReliableSlidingWindow* m_pReliableSlidingWindow;
897  StationProtocol* m_pStationProtocol;
898  RttProtocol* m_pRttProtocol;
899  ConnectStationJob* m_pConnectStationJob;
900  DisconnectStationJob* m_pDisconnectStationJob;
901  ProcessConnectionRequestJob* m_pProcessConnectionRequestJob;
902  SequenceIdController m_SequenceIdController;
903  uint8_t m_RecvConnectionId;
904 
905  bool m_IsConnectionRouteDirect;
906 
907  common::Time m_LatestPacketSentTime;
908  common::Time m_LatestPacketReceivedTime;
909 
910  bool m_IsDisconnectImmidiately;
911 
912  uint8_t m_PlayerCount;
913 
914  Station(const Station&);
915  Station& operator=(const Station&);
916 };
917 }
918 }
919 } // end of namespace nn::pia::transport