CTR Pia  4.11.3
Game Communication Engine
transport_Station.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: transport_Station.h
4 
5  Copyright Nintendo. All rights reserved.
6 
7  These coded instructions, statements, and computer programs contain
8  proprietary information of Nintendo of America Inc. and/or Nintendo
9  Company Ltd., and are protected by Federal copyright law. They may
10  not be disclosed to third parties or copied or duplicated in any form,
11  in whole or in part, without the prior written consent of Nintendo.
12  *---------------------------------------------------------------------------*/
13 
14 
15 #pragma once
16 
17 #include <pia/transport/transport_definitions.h>
18 
19 #include <pia/common/common_StationAddress.h>
20 #include <pia/common/common_PacketDefine.h>
21 #include <pia/common/common_Time.h>
22 
23 #include <pia/transport/transport_SequenceIdController.h>
24 
25 
26 // Forward declarations.
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 // Forward declarations.
48 class StationProtocol;
49 class StationProtocolReliable;
50 class ConnectStationJob;
51 class DisconnectStationJob;
52 class ProcessConnectionRequestJob;
53 class ReliableSlidingWindow;
54 class NetworkFactory;
55 
56 
57 /*!
58 @brief Represents a station. A station refers to a machine participating in a Pia session.
59 
60 @date 2015-02-19 Made the <tt>GetStationIndex</tt> function public.
61 @date 2013-10-16 Added <tt>GetRttSamplingNum</tt> to get the number of samples to use for calculating RTT.
62 @date 2013-08-08 Added <tt>SetInitialRttPulseInterval</tt> and <tt>GetInitialRttPulseInterval</tt>.
63 @date 2013-05-01 Added the <tt>GetIdentificationToken</tt>, <tt>GetPlayerName</tt>, and <tt>GetPrincipalId</tt> functions.
64 @date 2013-03-28 Added definitions for <tt>Station::IdentificationInfo</tt> and <tt>Station::PlayerName</tt>.
65 @date 2013-01-22 Added the <tt>GetRtt</tt> function that allows users to specify the number of samples to use when calculating RTT.
66 @date 2013-01-17 Added the <tt>SetRttPulseInterval</tt> and <tt>GetRttPulseInterval</tt> member functions for setting and getting the pulse interval used when calculating RTT.
67 @date 2012-06-28 Clearly indicated which functions are thread-safe.
68 @date 2012-06-21 Made functions and constants, the use of which were not necessary for applications, private.
69 @date 2012-06-14 Added <tt>Station::GetRtt</tt> function and <tt>Station::INVALID_RTT</tt> definition.
70 @date 2012-05-30 Made the send and receive functions private.
71 @date 2012-05-01 Added a definition for <tt>Station::IdentificationToken</tt>.
72 @date 2012-04-28 Fixed an error in the notation of the return values for the <tt>Station::Startup</tt> function.
73 @date 2012-04-06 Initial version.
74 */
76 {
77  friend class StationProtocolReliable;
78 
79 public:
80  static const size_t MAX_DATA_SIZE = common::PROTOCOL_MESSGAE_PAYLOAD_SIZE_MAX; // Maximum data size that can be sent or received with <tt>Send/Receive</tt>. The value is in bytes.
81  static const s32 INVALID_RTT = -1; //!< An invalid value that the <tt>GetRtt</tt> function can return.
82 
83 /*!
84 @brief Enumerates <tt>Station</tt> states.
85 */
87  {
88  STATE_INVALID, //!< Indicates an invalid <tt>StationState</tt>.
89  STATE_INITIAL, //!< Indicates that this station has already been initialized.
90  STATE_CREATING_SESSION, //!< Indicates a state in which a request has been made to connect to this station, and that the connection process has started.
91  STATE_JOINING_SESSION, //!< Indicates a state in which a request to connect from this station has been received, and that the connection process has started.
92  STATE_WAITING_CONNECTION, //!< Indicates a state of waiting for communication with this station to be established.
93  STATE_PARTICIPATING, //!< Indicates a state in which communication with this station is possible.
94  STATE_LEAVING, //!< Indicates a state in which communication with this station is being disconnected.
95  STATE_MAX = STATE_LEAVING //!< This is a sentinel value indicating the maximum value of <tt>StationState</tt>.
96  };
97 
98 
99 /*!
100 @cond PRIVATE
101 @brief Instantiates the object with default parameters (default constructor).
102 
103 @details The <tt>StationIndex</tt> of the instance is set to <tt>STATION_INDEX_INVALID</tt>.
104 */
105  Station(void);
106  //! @endcond
107 
108 
109 /*!
110 @cond PRIVATE
111 @brief Destroys the object.
112 */
113  ~Station(void);
114  //! @endcond
115 
116 
117 /*!
118 @cond PRIVATE
119 @brief Initializes the <tt>Station</tt> instance.
120 
121 @param[in] pFactory Specifies the concrete class that inherits <tt>NetworkFactory</tt>. Job instances are generated using this factory.
122 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
123 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
124 @see Finalize
125 */
126  nn::Result Initialize(NetworkFactory* pFactory);
127  //! @endcond
128 
129 
130 /*!
131 @cond PRIVATE
132 @brief Destroys the <tt>Station</tt> instance.
133 
134 @see Initialize
135 */
136  void Finalize(void);
137  //! @endcond
138 
139 
140 /*!
141 @brief Gets the <tt>StationIndex</tt>.
142 
143 @details This function is thread-safe.
144 @details Don't call this function when the application is using the joint session feature.
145 This results in undefined operations.
146 
147 @return Returns the <tt>StationIndex</tt> set in the instance.
148 */
150  {
151  return m_StationIndex;
152  }
153 
154 
155 /*!
156 @cond PRIVATE
157 @brief Sets the <tt>StationIndex</tt>.
158 @details Use this function in conjunction with <tt>SetStationId</tt>.
159 If possible, call this function at nearly the same time as <tt>SetStationId</tt>. The goal is to preserve the consistency of <tt>StationIndex</tt> and <tt>StationId</tt> as they are in the <tt>Station</tt> instance.
160 
161 It is likely that situations will arise where <tt>StationIndex</tt> will be set before <tt>StationId</tt>. When that happens, make sure that you subsequently call <tt>SetStationId</tt>.
162 
163 
164 @param[in] idx Specifies the <tt>StationIndex</tt> to set in this instance.
165 @see GetStationIndex, SetStationId
166 */
167  void SetStationIndex(StationIndex idx);
168  //! @endcond
169 
170 
171 /*!
172 @brief Gets the <tt>StationId</tt>.
173 
174 @return Returns the <tt>StationId</tt> corresponding to the <tt>Station</tt> instance.
175 */
177  {
178  return m_StationId;
179  }
180 
181 
182 /*!
183 @cond PRIVATE
184 @brief Sets the <tt>StationId</tt>.
185 @details Use this function in conjunction with <tt>SetStationIndex</tt>.
186 If possible, call this function at nearly the same time as <tt>SetStationIndex</tt>. The goal is to preserve the consistency of <tt>StationIndex</tt> and <tt>StationId</tt> as they are in the <tt>Station</tt> instance.
187 
188 It is likely that situations will arise where <tt>StationIndex</tt> will be set before <tt>StationId</tt>. When that happens, make sure that you subsequently call <tt>SetStationId</tt>.
189 
190 
191 @param[in] id Specifies the <tt>StationId</tt> to set in this instance.
192 @see GetStationId, SetStationIndex
193 */
194  void SetStationId(StationId id);
195  //! @endcond
196 
197 
198 /*!
199 @brief Gets the station address.
200 
201 @return Returns a const reference for the <tt>StationAddress</tt> that is set.
202 */
204  {
205  return m_StationAddress;
206  }
207 
208 
209 /*!
210 @cond PRIVATE
211 @brief Sets the station address.
212 
213 @param[in] addr Specifies the <tt>StationAddress</tt> to set in this instance.
214 @see GetStationAddress
215 */
216  void SetStationAddress(const common::StationAddress& addr)
217  {
218  m_StationAddress = addr;
219  }
220  //! @endcond
221 
222 
223 /*!
224 @cond PRIVATE
225 @brief Gets a pointer to the <tt>ConnectStationJob</tt> instance (non-<tt>const</tt> version).
226 @return Returns a pointer to the <tt>ConnectStationJob</tt> instance.
227 */
228  ConnectStationJob* GetConnectStationJob(void)
229  {
230  return m_pConnectStationJob;
231  }
232  //! @endcond
233 
234 
235 /*!
236 @cond PRIVATE
237 @brief Gets a pointer to the <tt>ConnectStationJob</tt> instance (<tt>const</tt> version).
238 @return Returns a <tt>const</tt> pointer to the <tt>ConnectStationJob</tt> instance.
239 */
240  const ConnectStationJob* GetConnectStationJob(void) const
241  {
242  return m_pConnectStationJob;
243  }
244  //! @endcond
245 
246 
247 /*!
248 @cond PRIVATE
249 @brief Gets a pointer to the <tt>DisconnectStationJob</tt> instance (non-<tt>const</tt> version).
250 @return Returns a pointer to the <tt>DisconnectStationJob</tt> instance.
251 */
252  DisconnectStationJob* GetDisconnectStationJob(void)
253  {
254  return m_pDisconnectStationJob;
255  }
256  //! @endcond
257 
258 
259 /*!
260 @cond PRIVATE
261 @brief Gets a pointer to the <tt>DisconnectStationJob</tt> instance (<tt>const</tt> version).
262 @return Returns a <tt>const</tt> pointer to the <tt>DisconnectStationJob</tt> instance.
263 */
264  const DisconnectStationJob* GetDisconnectStationJob(void) const
265  {
266  return m_pDisconnectStationJob;
267  }
268  //! @endcond
269 
270 
271 /*!
272 @cond PRIVATE
273 @brief Gets a pointer to the <tt>ProcessConnectionRequestJob</tt> instance (non-<tt>const</tt> version).
274 @return Returns a pointer to the <tt>ProcessConnectionRequestJob</tt> instance.
275 */
276  ProcessConnectionRequestJob* GetProcessConnectionRequestJob(void)
277  {
278  return m_pProcessConnectionRequestJob;
279  }
280  //! @endcond
281 
282 /*!
283 @cond PRIVATE
284 @brief Gets a pointer to the <tt>ProcessConnectionRequestJob</tt> instance (<tt>const</tt> version).
285 @return Returns a <tt>const</tt> pointer to the <tt>ProcessConnectionRequestJob</tt> instance.
286 */
287  const ProcessConnectionRequestJob* GetProcessConnectionRequestJob(void) const
288  {
289  return m_pProcessConnectionRequestJob;
290  }
291  //! @endcond
292 
293 
294 /*!
295 @brief Gets a pointer to the <tt>SequenceIdController</tt> instance (non-<tt>const</tt> version).
296 This function is thread-safe.
297 @return Returns a pointer to the <tt>SequenceIdController</tt> instance.
298 */
300  {
301  return &m_SequenceIdController;
302  }
303 
304 
305 /*!
306 @brief Gets a pointer to the <tt>SequenceIdController</tt> instance (<tt>const</tt> version).
307 This function is thread-safe.
308 @return Returns a <tt>const</tt> pointer to the <tt>SequenceIdController</tt> instance.
309 */
311  {
312  return &m_SequenceIdController;
313  }
314 
315 
316 /*!
317 @cond PRIVATE
318 @brief Gets the <tt>ConnectionId</tt> for the sending station.
319 @return Returns the <tt>ConnectionId</tt> for the sending station.
320 */
321  u8 GetSendingConnectionId(void) const
322  {
323  return m_SendConnectionId;
324  }
325  //! @endcond
326 
327 
328 /*!
329 @cond PRIVATE
330 @brief Sets the <tt>ConnectionId</tt> for the sending station.
331 @param[in] id Specifies the <tt>ConnectionId</tt> for sending to set in this instance.
332 */
333  void SetSendingConnectionId(u8 id)
334  {
335  m_SendConnectionId = id;
336  }
337  //! @endcond
338 
339 
340 /*!
341 @cond PRIVATE
342 @brief Gets the <tt>ConnectionId</tt> for the station to receive data.
343 @return Returns the<tt>ConnectionId</tt> of the receiving station.
344 */
345  u8 GetReceivingConnectionId(void) const
346  {
347  return m_RecvConnectionId;
348  }
349  //! @endcond
350 
351 
352 /*!
353 @cond PRIVATE
354 @brief Sets the <tt>ConnectionId</tt> for the station to receive data.
355 @param[in] id Specifies the <tt>ConnectionId</tt> for receiving to set in this instance.
356 */
357  void SetReceivingConnectionId(u8 id)
358  {
359  m_RecvConnectionId = id;
360  }
361  //! @endcond
362 
363 
364 /*!
365 @brief Gets the state of the <tt>Station</tt> instance.
366 
367 @details This function is thread-safe.
368 
369 @return Returns the state of the <tt>Station</tt>.
370 */
371  StationState GetState(void) const
372  {
373  return m_StationState;
374  }
375 
376 
377 /*!
378 @cond PRIVATE
379 @brief Sets the state of the <tt>Station</tt>.
380 
381 @param[in] state Specifies the state to set.
382 @see GetState
383 */
384  void SetState(StationState state)
385  {
386  m_StationState = state;
387  }
388  //! @endcond
389 
390 
391 /*!
392 @cond PRIVATE
393 @brief Performs <tt>Station</tt> startup processing.
394 @details After calling this function, set the <tt>StationId</tt> using the <tt>SetStationId</tt> function. Preserve the consistency between <tt>StationIndex</tt> and <tt>StationId</tt>.
395 
396 @details After this function is called, the <tt>StationId</tt> for this instance is set to <tt>STATION_ID_INVALID</tt>.
397 
398 @param[in] pStationProtocol Specifies a pointer to the <tt>StationProtocol</tt> to set in this instance.
399 @param[in] idx Specifies the <tt>StationIndex</tt> to set in this instance.
400 @param[in] addr Specifies the <tt>StationAddress</tt> object to set in this instance.
401 @return Returns <tt>true</tt> if successful; otherwise returns <tt>false</tt>.
402 @see Cleanup, SetStationId
403 */
404  bool Startup(StationProtocol* pStationProtocol, StationIndex idx, const common::StationAddress& addr);
405  //! @endcond
406 
407 
408 /*!
409 @cond PRIVATE
410 @brief Performs <tt>Station</tt> startup processing.
411 The <tt>StationIndex</tt> of the instance is set to <tt>STATION_INDEX_INVALID</tt>.
412 @details After this function is called, the <tt>StationId</tt> for this instance is set to <tt>STATION_ID_INVALID</tt>.
413 
414 @param[in] pStationProtocol Specifies a pointer to the <tt>StationProtocol</tt> to set in this instance.
415 @param[in] addr Specifies the <tt>StationAddress</tt> object to set in this instance.
416 @return Returns <tt>true</tt> if successful; otherwise returns <tt>false</tt>.
417 @see Cleanup
418 */
419  bool Startup(StationProtocol* pStationProtocol, const common::StationAddress& addr);
420  //! @endcond
421 
422 
423 /*!
424 @cond PRIVATE
425 @brief Performs <tt>Station</tt> startup processing.
426 The <tt>StationIndex</tt> of this instance is set to <tt>STATION_INDEX_INVALID</tt> and <tt>StationAddress</tt> is set to the same state as if the <tt>StationAddress::Clear</tt> function had been run.
427 
428 @details After this function is called, the <tt>StationId</tt> for this instance is set to <tt>STATION_ID_INVALID</tt>.
429 
430 @param[in] pStationProtocol Specifies a pointer to the <tt>StationProtocol</tt> to set in this instance.
431 @return Returns <tt>true</tt> if successful; otherwise returns <tt>false</tt>.
432 @see Cleanup
433 */
434  bool Startup(StationProtocol* pStationProtocol);
435  //! @endcond
436 
437 
438 /*!
439 @cond PRIVATE
440 @brief Cleans up the <tt>Station</tt> instance.
441 This function is paired with the <tt>Startup</tt> function. The content set by the <tt>Startup</tt> function is cleared.
442 
443 @see Startup
444 */
445  void Cleanup(void);
446  //! @endcond
447 
448 
449 /*!
450 @brief Gets the round-trip time (RTT) between the local <tt>Station</tt> and this <tt>Station</tt>.
451 
452 @details The system sends pulses to other stations periodically to get the round-trip time (RTT).
453 At particular times, however, the system may have never sent pulses to or received responses from other stations. One example is when it has just connected to the session.
454 At these times, the <tt>GetRtt</tt> function returns <tt>INVALID_RTT</tt>, but if you call the <tt>GetRtt</tt> function after a short time has passed, the correct value is returned.
455 This function returns the median value of multiple samples.
456 The value obtained from this function is relatively stable and not easily affected by minor changes in network environment.
457 
458 @return Returns the RTT value. The value is in milliseconds.
459 @retval INVALID_RTT Specifies a negative value that indicates that the RTT value cannot be obtained in this state.
460 @see SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
461 
462 
463 
464 */
465  s32 GetRtt(void) const;
466 
467 
468 /*!
469 @brief Gets the round-trip time (RTT) between the local <tt>Station</tt> and this <tt>Station</tt>. You can specify the number of samples to use for calculating RTT.
470 
471 @details The system stores several samples obtained from RTT pulse transmissions and responses.
472 The version of the <tt>GetRtt</tt> function that does not take arguments returns the median value for all stored sample values. The version that takes an argument returns the median value for the specified number of samples.
473 When specified, the latest samples are used. If you specify a small value, the RTT value strongly reflects the most recent network connection status.
474 However, if the value of the argument is too small, the RTT value is susceptible to fluctuation.
475 @param[in] samplingNum Specifies the number of most recent samples to use in calculating the RTT.
476 @return Returns the RTT value. The value is in milliseconds.
477 @retval INVALID_RTT Specifies a negative value that indicates that the RTT value cannot be obtained in this state.
478 @see SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
479 
480 
481 */
482  s32 GetRtt(size_t samplingNum) const;
483 
484 
485 /*!
486 @cond PRIVATE
487 @brief Gets the most recent round-trip time (RTT) measured between the local station and this one.
488 
489 @return Returns the most recent RTT value measured by the system. The value is in milliseconds.
490 @retval INVALID_RTT Specifies a negative value that indicates that the RTT value cannot be obtained in this state.
491 
492 @see GetRtt, SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
493 */
494  s32 GetLatestRtt(void) const;
495  //! @endcond
496 
497 
498 /*!
499 @brief Gets the number of RTT (Round Trip Time) samples held by the system.
500 
501 @details The system sends pulses to other stations periodically to get the round-trip time (RTT), and the time required for the response is saved as an RTT sample.
502 At particular times, however, the system cannot obtain a sufficient number of samples because it has just begun sending pulses and receiving responses. One example is when it has just connected to the session.
503 This function returns the number of samples that are used by functions such as <tt>GetRtt</tt> to calculate the RTT value. It gives an idea of the reliability and precision of the RTT value.
504 
505 @return Returns the number of samples held by the system.
506 @retval 0 A value of <tt>0</tt> specifies a state in which the RTT value could not be obtained.
507 @see GetRtt, SetRttPulseInterval, GetRttPulseInterval, SetInitialRttPulseInterval, GetInitialRttPulseInterval
508 
509 
510 
511 */
512  size_t GetRttSamplingNum(void) const;
513 
514 
515 /*!
516 @brief Sets the interval for sending pulses for RTT calculation.
517 
518 @param[in] msec Specifies the interval at which to send pulses. The value is in milliseconds.
519 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
520 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Returned if a non-positive integer is specified. Programming error. Fix your program so that this error is not returned.
521 @see GetRttPulseInterval, GetRtt, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
522 */
523  static nn::Result SetRttPulseInterval(s32 msec);
524 
525 
526 /*!
527 @brief Gets the interval for sending pulses for RTT calculation.
528 
529 @return Returns the specified interval for sending pulses. The value is in milliseconds.
530 @see SetRttPulseInterval, GetRtt, SetInitialRttPulseInterval, GetInitialRttPulseInterval, GetRttSamplingNum
531 */
532  static s32 GetRttPulseInterval(void);
533 
534 
535 /*!
536 @brief Sets the interval for sending the initial pulse for RTT calculation.
537 
538 @details The pulse for calculating the RTT is sent starting when the station joins a session.
539 There are not enough samples available to calculate the RTT immediately after a station joins a session.
540 The system sends pulses at a shorter interval than usual until enough samples are available to quickly get the number of samples required.
541 This member function sets the interval at which pulses are set during this initial period.
542 
543 @param[in] msec Specifies the interval at which to send pulses initially. The value is in milliseconds.
544 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
545 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Returned if a non-positive integer is specified. Programming error. Fix your program so that this error is not returned.
546 @see GetInitialRttPulseInterval, GetRtt, SetRttPulseInterval, GetRttPulseInterval, GetRttSamplingNum
547 
548 
549 */
550  static nn::Result SetInitialRttPulseInterval(s32 msec);
551 
552 
553 /*!
554 @brief Gets the interval for sending initial pulses for RTT calculation.
555 
556 @details The pulse for calculating the RTT is sent starting when the station joins a session.
557 There are not enough samples available to calculate the RTT immediately after a station joins a session.
558 The system sends pulses at a shorter interval than usual until enough samples are available to quickly get the number of samples required.
559 This member function gets the interval at which pulses are set during this initial period.
560 
561 @return Returns the specified interval for sending pulses. The value is in milliseconds.
562 @see SetInitialRttPulseInterval, GetRtt, SetRttPulseInterval, GetRttPulseInterval, GetRttSamplingNum
563 
564 
565 */
566  static s32 GetInitialRttPulseInterval(void);
567 
568 
569 /*!
570 @cond PRIVATE
571 @brief Gets a pointer to the <tt>StationProtocol</tt> instance stored in this <tt>Station</tt> instance (non-<tt>const</tt> version).
572 
573 @return Returns a pointer to a <tt>StationProtocol</tt> instance. Returns a <tt>NULL</tt> pointer if no <tt>StationProtocol</tt> instance has been configured.
574 @see Startup
575 */
576  StationProtocol* GetStationProtocol(void)
577  {
578  return m_pStationProtocol;
579  }
580  //! @endcond
581 
582 
583 /*!
584 @cond PRIVATE
585 @brief Gets a pointer to the <tt>StationProtocol</tt> instance stored in this <tt>Station</tt> instance (<tt>const</tt> version).
586 
587 @return Returns a pointer to a <tt>StationProtocol</tt> instance. Returns a <tt>NULL</tt> pointer if no <tt>StationProtocol</tt> instance has been configured.
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 Records the last time that a packet was sent.
600 
601 @details This function is mainly called from <tt>KeepAliveSender</tt>.
602 @param[in] t Specifies the time the packet was sent.
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 Gets the last time that a packet was sent.
615 
616 @details This function is mainly called from <tt>KeepAliveSender</tt>.
617 @return Returns the time that a packet was last sent.
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 Records the last time that a packet was received.
630 
631 @details This function is mainly called from <tt>KeepAliveReceiver</tt>.
632 @param[in] t Specifies the time the packet was received.
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 Gets the last time that a packet was received.
645 
646 @details This function is mainly called from the session layer. It is used for keep-alive determinations.
647 @return Returns the last time that a packet was received.
648 @see SetLatestPacketReceivedTime
649 
650 */
651  const common::Time& GetLatestPacketReceivedTime(void) const
652  {
653  return m_LatestPacketReceivedTime;
654  }
655  //! @endcond
656 
657 
658 /*!
659 @cond PRIVATE
660 @brief Forcibly finalizes and initializes station connection and disconnection jobs.
661 */
662  void CleanupJobs();
663  //! @endcond
664 
665 
666 /*!
667 @brief Prints information that is useful for debugging.
668 
669 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
670 */
671  virtual void Trace(u64 flag) const;
672 
673 
674  static const size_t IDENTIFICATION_TOKEN_MAX_DATA_SIZE = 32; //!< Specifies the maximum data size for an identification token.
675  static const size_t PLAYER_NAME_MAX_DATA_SIZE = 17; //!< Specifies the maximum data size for a player name. The final character is for the terminating null character.
676 
677 /*!
678 @brief Stores the ID token associated with a <tt>Station</tt>.
679 
680 @details The ID token is shared with connected stations.
681 */
683  {
684  bit8 data[IDENTIFICATION_TOKEN_MAX_DATA_SIZE]; //!< The ID token data array.
685  };
686 
687 /*!
688 @brief Stores the player name struct associated with a <tt>Station</tt>.
689 
690 @details The name is shared with connected stations.
691 */
692  struct PlayerName
693  {
694  s16 data[PLAYER_NAME_MAX_DATA_SIZE]; //!< Specifies the player name as a data array.
695  u8 length; //!< Specifies the length of the player name. The name must be no longer than 16 characters (not including the terminating <tt>null</tt> character).
696  u8 language; //!< Specifies the language of the player name. @if CAFE_DOC Use one of the values defined in <tt>nn::fp::Language</tt>. @endif @if CTR_DOC You can use the value returned by the <tt>nn::cfg::CTR::GetLanguage</tt> function if you want to use the language setting of the system. @endif
697  };
698 
699 /*!
700 @cond PRIVATE
701 @brief Stores ID information (the token and name) associated with a <tt>Station</tt>.
702 */
703  struct IdentificationInfo
704  {
705  IdentificationToken token;
706  PlayerName name;
707  u8 platform;
708  u32 gid;
709  };
710  //! @endcond
711 
712 /*!
713 @brief Gets the ID token of the station.
714 
715 @details If called by the local station, this function gets the ID token set in the <tt>@ref session::Session::Startup</tt> function.
716 If called by a station other than the station, this function gets the ID token shared at time of connection.
717 If no token has been configured, this function succeeds but the obtained ID token data is filled with <tt>NULL</tt> values.
718 
719 The values of the ID token specified as an out parameter never change if the function fails to acquire an ID token.
720 
721 @param[out] pToken Specifies the ID token of the <tt>Station</tt> if it was successfully retrieved.
722 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the ID token is successfully retrieved. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
723 @retval ResultInvalidState Specifies that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
724 @retval ResultInvalidArgument Specifies that an invalid pointer was specified as an argument. Programming error. Fix your program so that this error is not returned.
725 @retval ResultNoData Specifies that the function was not able to obtain the ID token of the specified station. The sharing of the ID token might not have been completed. Handle appropriately in the application.
726 */
727  nn::Result GetIdentificationToken(IdentificationToken* pToken);
728 
729 /*!
730 @brief Gets the name of the station.
731 
732 @details For a local station, gets the name set in the <tt>@ref session::Session::Startup</tt> function.
733 For a non-local station, gets the name shared on connection.
734 
735 The value of the name specified as an out parameter never changes if the function fails to acquire a name.
736 
737 @param[out] pName Specifies the name of the <tt>Station</tt> if successfully retrieved.
738 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the name is successfully retrieved. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
739 @retval ResultInvalidState Specifies that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
740 @retval ResultInvalidArgument Specifies that an invalid pointer was specified as an argument. Programming error. Fix your program so that this error is not returned.
741 @retval ResultNoData Specifies that the function was not able to get the name of the specified station. The sharing of the name might not have been completed. Handle appropriately in the application.
742 */
743  nn::Result GetPlayerName(PlayerName* pName);
744 
745 /*!
746 @brief Gets the principal ID of the station.
747 
748 @details For a local station, gets the principal ID specified in the <tt>nn::nex::Credentials</tt> function.
749 You can get this value after the <tt>@ref inet::NexFacade::StartNatSessionAsync</tt> asynchronous process completes.
750 
751 For a non-local station, gets the principal ID shared on connection.
752 
753 The value of the principal ID specified as an out parameter never changes if the function fails to acquire the principal ID.
754 
755 @param[out] pPrincipalId Specifies the principal ID of the <tt>Station</tt> if successfully retrieved.
756 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the name is successfully retrieved. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
757 @retval ResultInvalidState Specifies that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
758 @retval ResultInvalidArgument Specifies that an invalid pointer was specified as an argument. Programming error. Fix your program so that this error is not returned.
759 @retval ResultNoData Specifies that the function was not able to obtain the principal ID of the specified station. The sharing of the ID token might not have been completed. Handle appropriately in the application.
760 */
761  nn::Result GetPrincipalId(u32* pPrincipalId);
762 
763 /*!
764 @cond PRIVATE
765 @brief Sets whether the connection route to the target <tt>Station</tt> is a direct connection.
766 */
767  void SetConnectionRoute(bool isDirect)
768  {
769  m_ConnectionRouteIsDirect = isDirect;
770  }
771  //! @endcond
772 
773 /*!
774 @cond PRIVATE
775 @brief Gets whether the connection route to the target <tt>Station</tt> is a relay connection.
776 @return Returns <tt>true</tt> if it is a relay connection, and <tt>false</tt> otherwise.
777 */
778  bool IsConnectionRouteRelay() const;
779  //! @endcond
780 
781 /*!
782 @cond PRIVATE
783 @brief Gets whether the connection route to the target <tt>Station</tt> is a direct connection.
784 @return Returns <tt>true</tt> if it is a direct connection, and <tt>false</tt> otherwise.
785 */
786  bool IsConnectionRouteDirect() const;
787  //! @endcond
788 
789 
790 #if NN_PIA_EXPERIMENT_HANDSHAKE_CHECK
791 /*!
792 @cond PRIVATE
793 @brief Returns whether the target station has participated in the session.
794 @return Returns <tt>true</tt> when participating and <tt>false</tt> otherwise.
795 @see SetJoinFlag
796 */
797  bool GetJoinFlag() const { return m_JoinFlag; }
798  //! @endcond
799 
800 /*!
801 @cond PRIVATE
802 @brief Sets whether the target station has participated in the session.
803 Expect it to be called when the <tt>Join</tt> and <tt>Leave</tt> events occur.
804 @param[in] flag Set to <tt>true</tt> when marking as "participated," and to <tt>false</tt> when marking as "not participated."
805 @see GetJoinFlag
806 */
807  void SetJoinFlag(bool flag) { m_JoinFlag = flag; }
808  //! @endcond
809 #endif // end of NN_PIA_EXPERIMENT_HANDSHAKE_CHECK
810 
811 /*!
812  @cond PRIVATE
813 */
814  bool GetDisconnectImmidiatelyFlag() const { return m_DisconnectImmidiately; }
815  //! @endcond
816 
817 /*!
818  @cond PRIVATE
819 */
820  void SetDisconnectImmidiatelyFlag(bool flag) { m_DisconnectImmidiately = flag; }
821  //! @endcond
822 private:
823  // A helper function prepared to bring together the common processes that occur in the <tt>Startup</tt> and <tt>Cleanup</tt> functions.
824  // The first argument switches it between the startup and cleanup processes.
825  // The second and subsequent arguments are set unconditionally to member variables (that is, there is no argument check).
826  void helperStartupCleanup(bool bStartup, StationProtocol* pStationProtocol, StationIndex idx, const common::StationAddress& addr, StationState state);
827 
828  common::StationAddress m_StationAddress;
829  StationIndex m_StationIndex;
830  StationId m_StationId;
831  StationState m_StationState;
832  ReliableSlidingWindow* m_pReliableSlidingWindow;
833  StationProtocol* m_pStationProtocol;
834  ConnectStationJob* m_pConnectStationJob;
835  DisconnectStationJob* m_pDisconnectStationJob;
836  ProcessConnectionRequestJob* m_pProcessConnectionRequestJob;
837  SequenceIdController m_SequenceIdController;
838  u8 m_SendConnectionId;
839  u8 m_RecvConnectionId;
840 
841  bool m_ConnectionRouteIsDirect;
842 
843  common::Time m_LatestPacketSentTime;
844  common::Time m_LatestPacketReceivedTime;
845 
846  bool m_DisconnectImmidiately;
847 
848 #if NN_PIA_EXPERIMENT_HANDSHAKE_CHECK
849  bool m_JoinFlag;
850 #endif
851 };
852 }
853 }
854 } // end of namespace nn::pia::transport
void Finalize(void)
Finalizes the common module.
Indicates a state of waiting for communication with this station to be established.
Definition: transport_Station.h:92
Indicates a state in which communication with this station is possible.
Definition: transport_Station.h:93
StationState
Enumerates Station states.
Definition: transport_Station.h:86
Class that represents time.
Definition: common_Time.h:39
StationState GetState(void) const
Gets the state of the Station instance.
Definition: transport_Station.h:371
StationIndex
Enumerates StationIndex values.
Definition: platformCtr.h:44
Definition of the StationId identifying the station within the session.
Definition: types.h:33
Manages the sequence ID of the packet. In conjunction with this, includes a profiling feature for pac...
Definition: transport_SequenceIdController.h:38
Definition: assert.h:115
u8 language
Specifies the language of the player name. You can use the value returned by the nn::cfg::CTR::GetLan...
Definition: transport_Station.h:696
Represents a station. A station refers to a machine participating in a Pia session.
Definition: transport_Station.h:75
StationIndex GetStationIndex(void) const
Gets the StationIndex.
Definition: transport_Station.h:149
Indicates a state in which a request to connect from this station has been received, and that the connection process has started.
Definition: transport_Station.h:91
Stores the player name struct associated with a Station.
Definition: transport_Station.h:692
const common::StationAddress & GetStationAddress(void) const
Gets the station address.
Definition: transport_Station.h:203
Represents an address used to uniquely identify stations. .
Definition: common_StationAddress.h:43
An interface (factory pattern) for generating the classes needed by the network.
Definition: transport_NetworkFactory.h:89
u8 length
Specifies the length of the player name. The name must be no longer than 16 characters (not including...
Definition: transport_Station.h:695
nn::Result Initialize(void *pMem, u32 size)
Initializes the common module.
Stores the ID token associated with a Station.
Definition: transport_Station.h:682
StationId GetStationId(void) const
Gets the StationId.
Definition: transport_Station.h:176
Indicates a state in which a request has been made to connect to this station, and that the connectio...
Definition: transport_Station.h:90
Indicates a state in which communication with this station is being disconnected. ...
Definition: transport_Station.h:94
SequenceIdController * GetSequenceIdController(void)
Gets a pointer to the SequenceIdController instance (non-const version). This function is thread-safe...
Definition: transport_Station.h:299
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40
Indicates an invalid StationState.
Definition: transport_Station.h:88
Indicates that this station has already been initialized.
Definition: transport_Station.h:89
const SequenceIdController * GetSequenceIdController(void) const
Gets a pointer to the SequenceIdController instance (const version). This function is thread-safe...
Definition: transport_Station.h:310