CTR Pia  4.11.3
Game Communication Engine
transport_Transport.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: transport_Transport.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/transport/transport_Singleton.h>
20 #include <pia/transport/transport_ProtocolManager.h>
21 
22 #include <pia/common/common_Time.h>
23 #include <pia/common/common_Job.h>
24 
25 #if NN_PIA_ENABLE_FEEDBACK
26 #include <pia/common/common_Feedback.h>
27 #endif
28 
29 
30 // Forward declarations (common).
31 namespace nn
32 {
33 namespace pia
34 {
35 namespace common
36 {
37 class IPacketInput;
38 class IPacketOutput;
39 class StationAddress;
40 struct CryptoSetting;
41 }
42 }
43 }
44 
45 
46 namespace nn
47 {
48 namespace pia
49 {
50 namespace transport
51 {
52 
53 
54 // Forward declarations (transport).
55 class NetworkFactory;
56 class StationConnectionInfo;
57 class KeepAliveSender;
58 class KeepAliveReceiver;
59 class ThreadStreamManager;
60 class IRelayAddressTable;
61 class RelayRouteManager;
62 class StationPacketHandler;
63 class Station;
64 class StationIdTable;
65 
66 #if NN_PIA_ENABLE_FEEDBACK
67 #define NN_PIA_SEND_FEEDBACKDATA \
68  if (nn::pia::transport::Transport::GetInstance()) \
69  { \
70  NN_PIA_FEEDBACK(); \
71  nn::pia::transport::Transport::GetInstance()->SendFeedback(); \
72  } \
73  nn::pia::common::Feedback::Dummy
74 #endif
75 
76 /*!
77 @brief Provides core functionality of the <tt>transport</tt> module.
78 
79 @date 2015-04-24 Fixed an error in the description of the arguments passed to <tt>ConvertToStationId</tt>.
80 @date 2015-04-24 Noted that the <tt>ConvertToStationIndex</tt> and <tt>ConvertToStationId</tt> functions have different behavior when used with the Session API and the Mesh API.
81 @date 2014-11-05 Renamed the <tt>GetConnectionStatus</tt> function to <tt>CheckConnectionError</tt>.
82 @date 2014-09-18 Changed the specifications so that <tt>ResultAlreadyExists</tt> is returned if you call <tt>CreateInstance</tt> when an instance already exists.
83 @date 2014-07-17 Added the new <tt>CheckTransportStatus</tt> function.
84 @date 2014-06-26 Added the new <tt>ConvertToStationId</tt> and <tt>ConvertToStationIndex</tt> functions.
85 @date 2014-04-08 Provided the <tt>DebugSetting</tt> structure as the default constructor, and made it initialize all member variables with the default values.
86 @date 2014-04-03 Renamed the <tt>GetMasterStationConnectionInfo</tt> function to <tt>GetHostStationConnectionInfo</tt>.
87 @date 2014-04-02 Added the new <tt>SetDebugSetting</tt> function. Use this function to make debugging settings for things like latency emulation.
88 @date 2014-04-02 Removed the members related to latency emulation from the <tt>Transport::Setting</tt> structure.
89 @date 2013-11-22 Added the <tt>analysisInterval</tt> member variable to the <tt>Transport::Setting</tt> structure and made it possible to automatically print measurement results from the transport analysis feature.
90 @date 2013-05-24 Made the <tt>SetKeepAliveInterval</tt> function private. Specify with the <tt>Session::Startup</tt> function.
91 @date 2013-04-01 Removed the <tt>maxPacketCreatorBufferNum</tt> and <tt>maxPacketParserBufferNum</tt> members from the <tt>Transport::Setting</tt> struct.
92 @date 2012-12-03 The <tt>Transport::GetConnectionStatus</tt> function can now return <tt>ResultInvalidState</tt>.
93 @date 2012-11-30 Removed the <tt>Transport::MAX_SIGNATURE_KEY_SIZE</tt> constant.
94 @date 2012-11-30 Removed signature-related parameters from the version of the <tt>Transport::Setting</tt> struct constructor with parameters.
95 @date 2012-11-30 Removed signature-related member variables from the <tt>Transport::Setting</tt> struct.
96 @date 2012-11-27 Changed the specifications of the <tt>Transport::CreateInstance</tt> function. The function now returns an error <tt>Result</tt> value if the signature feature is not enabled on networks where signed packets are recommended.
97 @date 2012-07-25 Added <tt>Transport::GetLocalStationConnectionInfo</tt> and <tt>Transport::GetMasterStationConnectionInfo</tt>.
98 @date 2012-07-18 Added error handling for the <tt>Transport::GetConnectionStatus</tt> function.
99 @date 2012-07-05 Prepared a constructor for the <tt>Transport::Setting</tt> structure.
100 @date 2012-07-05 Added member variables for latency emulation to the <tt>Setting</tt> structure.
101 @date 2012-07-04 Updated descriptions of <tt>Setting</tt> structure members.
102 @date 2012-06-28 Clearly indicated which functions are thread-safe.
103 @date 2012-06-15 Added the <tt>Transport::GetConnectionStatus</tt> function.
104 @date 2012-06-15 Made the following functions private: <tt>Transport::Startup</tt>, <tt>Transport::Cleanup</tt>, and <tt>Transport::Dispatch</tt>.
105 @date 2012-06-01 Added the <tt>Transport::Startup</tt> and <tt>Transport::Cleanup</tt> functions.
106 @date 2012-05-25 Changed the <tt>Result</tt> values that the <tt>Transport::Dispatch</tt> function can return.
107 @date 2012-05-09 Extended the <tt>Transport::Setting</tt> struct to add the ability to sign packets.
108 @date 2012-04-28 Noted that the <tt>Transport::Dispatch</tt> function can return <tt>ResultInvalidState</tt>.
109 @date 2012-04-28 Revised the description of the <tt>Transport::Dispatch</tt> function.
110 @date 2012-04-25 Described memory settings using the <tt>Transport::Setting</tt> struct.
111 @date 2012-04-21 Revised the description of the <tt>Transport::Dispatch</tt> function.
112 @date 2012-04-18 The size of internal buffers can now be specified in the <tt>Transport::CreateInstance</tt> function.
113 @date 2012-04-12 Added functions related to keep-alive processing.
114 @date 2012-04-06 Initial version.
115 */
117 {
118 public:
119 /*!
120 @brief Stores parameters passed to the <tt>CreateInstance</tt> function.
121 
122 @details The buffer parameter you configure in this struct has a direct effect on the memory usage of the <tt>PiaTransport</tt> class.
123 You can set this parameter to a large value to reduce the frequency of <tt>ResultBufferIsFull</tt> errors caused by buffer exhaustion when sending and receiving data. This helps make communication function more smoothly, although of course it increases memory usage.
124 The amount of memory required by the <tt>PiaTransport</tt> class depends on the communication specifications of your application.
125 The library provides the <tt>common::WatermarkManager()</tt> class to help tune these parameters.
126 You can use this watermark feature to discover the peak buffer usage when your program actually runs. It helps application developers determine the optimum buffer size to use in the Pia library.
127 @see CreateInstance, common::WatermarkManager, ThreadStreamManager
128 
129 
130 
131 
132 
133 */
134  struct Setting
135  {
136 
137 /*!
138 @brief Instantiates the object with default parameters (default constructor). Each member variable is set to <tt>0</tt> or <tt>NULL</tt>.
139 */
140  Setting(void);
141 
142 /*!
143 @brief Instantiates the object with arguments. The values specified in the arguments are set in the variables of each member.
144 
145 @param[in] pFactory Specifies a pointer to an instance of a concrete class that inherits <tt>NetworkFactory</tt> (factory pattern).
146 @param[in] maxStationNum Specifies the maximum number of <tt>Station</tt>s that can join a single network.
147 @param[in] maxSendThreadBufferNum Specifies the number of buffers that the Pia library's sending thread uses to send packets (about 1.5 KB per buffer). You must set this value to 2 or greater.
148 @param[in] maxReceiveThreadBufferNum Specifies the number of buffers that the Pia library's receiving thread uses to receive packets (about 1.5 KB per buffer). You must set this value to 2 or greater.
149 @param[in] analysisInterval The interval at which measurement results from the <tt>TransportAnalyzer</tt> feature are automatically output to the console. The unit is seconds. When <tt>0</tt> is specified, output is not automatic, and it is left to the application to get the data.
150 */
151  Setting(
152  NetworkFactory* pFactory,
153  size_t maxStationNum = 0,
154  size_t maxSendThreadBufferNum = 0,
155  size_t maxReceiveThreadBufferNum = 0,
156  s32 analysisInterval = 0);
157 
158  NetworkFactory* pFactory; //!< Pointer to an instance of the concrete class that inherits <tt>NetworkFactory</tt> (factory pattern).
159  size_t maxStationNum; //!< Specifies the maximum number of <tt>Station</tt>s that can join a single network.
160  size_t maxSendThreadBufferNum; //!< The number of buffers that the sending thread of the Pia library uses to send packets (about 1.5 KB per buffer). You must set this value to 2 or greater.
161  size_t maxReceiveThreadBufferNum; //!< The number of buffers that the receiving thread of the Pia library uses to receive packets (about 1.5 KB per buffer). You must set this value to 2 or greater.
162  s32 analysisInterval; //!< The interval at which measurement results from the <tt>TransportAnalyzer</tt> feature are automatically output to the console. The unit is seconds. When <tt>0</tt> is specified, output is not automatic, and it is left to the application to get the data.
163  };
164 
165 
166 /*!
167 @cond PRIVATE
168 @brief Instantiates an object. Do not have the application call this constructor directly. Use the <tt>CreateInstance</tt> function instead.
169 */
170  Transport(void);
171  //! @endcond
172 
173 
174 /*!
175 @cond PRIVATE
176 @brief Destroys the object.
177 */
178  ~Transport(void);
179  //! @endcond
180 
181 
182 /*!
183 @brief Creates a <tt>Transport</tt> class instance (singleton pattern).
184 
185 @param[in] setting Specifies the <tt>Setting</tt> struct that parameters are stored in.
186 
187 @return Returns a <tt>Result</tt> value that indicates success if the instance is created successfully. You must make sure that the implementation of this function in your application does not return any errors.
188 @retval ResultNotInitialized Specifies that the <tt>transport</tt> module is not initialized. Programming error. Fix your program so that this error is not returned.
189 @retval ResultInvalidState Specifies that the timing at which the <tt>CreateInstance</tt> function was called is incorrect. Make this call between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions. Programming error. Fix your program so that this error is not returned.
190 @retval ResultAlreadyExists Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
191 @retval ResultInvalidArgument Specifies that an argument is invalid. Programming error. Fix your program so that this error is not returned.
192 @retval ResultAllocationFailed Specifies that the function failed to allocate memory. You must either increase the memory provided to Pia with the <tt>common::Initialize</tt> function or try setting parameters that do not consume as much memory. Programming error. Fix your program so that this error is not returned.
193 @see DestroyInstance, GetInstance, Setting
194 */
195  static nn::Result CreateInstance(const Transport::Setting& setting);
196 
197 
198 /*!
199 @brief Destroys the <tt>Transport</tt> class instance (singleton pattern).
200 If no instances exist, this function does nothing.
201 
202 @see CreateInstance, GetInstance
203 */
204  static void DestroyInstance(void);
205 
206 
207 /*!
208 @brief Gets the <tt>Transport</tt> class instance (singleton pattern).
209 This function returns a <tt>NULL</tt> pointer if the instance has not yet been created using the <tt>CreateInstance()</tt> function.
210 This function is thread-safe.
211 
212 @return Returns a pointer to a <tt>Transport</tt> instance.
213 @see CreateInstance, DestroyInstance
214 
215 */
216  static Transport* GetInstance(void)
217  {
218  return s_pInstance;
219  }
220 
221 
222 /*!
223 @cond PRIVATE
224 @brief Executes the startup procedure.
225 
226 @details Call this function after the <tt>transport::EndSetup</tt> function has been called and the initialization process of the <tt>transport</tt> module has ended.
227 @param[in] cpRelayNodeAddress Specifies a pointer to the address of the relay node.
228 It is okay to use a pointer to a temporary instance.
229 Specify <tt>NULL</tt> if you are not using relay nodes.
230 @param[in] cpCryptoSetting The pointer to the encryption settings.
231 Communication is not encrypted if <tt>NULL</tt> is specified.
232 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
233 @retval ResultInvalidState It could be that either the <tt>Startup</tt> function has already been called or that it is being called between calls to the <tt>transport::BeginSetup</tt> and <tt>transport::EndSetup</tt> functions. Programming error. Fix your program so that this error is not returned.
234 @see Cleanup, transport::EndSetup
235 
236 
237 
238 */
239  nn::Result Startup(const common::StationAddress* cpRelayNodeAddress = NULL, const common::CryptoSetting* cpCryptoSetting = NULL);
240  //! @endcond
241 
242 
243 /*!
244 @cond PRIVATE
245 @brief Executes the cleanup procedure.
246 
247 @details Call this function before finalizing the <tt>transport</tt> module.
248 
249 @see Startup
250 */
251  void Cleanup(void);
252  //! @endcond
253 
254 
255 /*!
256 @brief Generates an instance of a protocol of type <tt>T</tt>.
257 
258 @details @tparam T Specifies the protocol type.
259 @param[in] port Specifies the value of the protocol port.
260 
261 @return Returns a handle to the generated protocol. If the same protocol ID already exists, <tt>0</tt> is returned.
262 @see DestroyProtocol, GetProtocol
263 */
264  template <typename T>
265  u32 CreateProtocol(u16 port = 0)
266  {
267  return m_ProtocolManager.CreateProtocol<T>(port);
268  }
269 
270 
271 /*!
272 @brief Destroys the protocol instance.
273 
274 @param[in] protocolHandle Specifies the handle for the protocol to delete.
275 @see CreateProtocol, GetProtocol
276 */
277  void DestroyProtocol(u32 protocolHandle)
278  {
279  m_ProtocolManager.DestroyProtocol(protocolHandle);
280  }
281 
282 
283 /*!
284 @brief Gets an instance of a protocol of type <tt>T</tt>.
285 
286 @details @tparam T Specifies the protocol type.
287 @param[in] protocolHandle Specifies the handle for the protocol to get.
288 
289 @return Returns the address of the protocol instance. Returns <tt>NULL</tt> if the protocol for the specified handle does not exist or is not of type <tt>T</tt>.
290 @see CreateProtocol, DestroyProtocol
291 */
292  template <typename T>
293  T* GetProtocol(u32 protocolHandle)
294  {
295  return m_ProtocolManager.GetProtocol<T>(protocolHandle);
296  }
297 
298 
299 /*!
300 @brief Gets the connection status of the <tt>transport</tt> module.
301 
302 @details This function is thread-safe.
303 
304 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> value returns <tt>true</tt> if there are no problems with the network connection.
305 @retval ResultInvalidState Specifies that the application may not have called an appropriate initialization or setup function.
306 This <tt>Result</tt> is returned, for example, if you attempt to connect to the Internet when the socket library has not been initialized.
307 Programming error. Fix your program so that this error is not returned.
308 @cond CTR_DOC
309 @retval ResultNetworkConnectionIsLost Indicates that the network connection was lost. The wireless switch may be turned off or there may be a problem with the access point.
310 If this error is returned in a local connection environment, reinitialize <tt>PiaLocal</tt> and the higher-level modules.
311 If this error is returned in an Internet connection environment, connect to the Internet again (<tt>nn::ac::Connect</tt>). You could also reinitialize, as with a local connection environment.
312 Handle appropriately in the application.
313 @endcond
314 @cond CAFE_DOC
315 @retval ResultNetworkConnectionIsLost Indicates that the network connection was lost.
316 One possible cause is a problem with the access point.
317 If this error is returned in an Internet connection environment, connect to the Internet again (<tt>nn::ac::Connect</tt>).
318 Reconnect to AC.
319 @endcond
320 
321 @see util::NetworkErrorCodeConverter::Convert
322 
323 
324 
325 */
326  nn::Result CheckConnectionError(void) const
327  {
328  return m_ConnectionError;
329  }
330 
331 
332 /*!
333 @cond PRIVATE
334 @brief Gets the last time that the <tt>dispatch</tt> function was called.
335 
336 @return Returns the last time that the <tt>dispatch</tt> function was called.
337 @see dispatch
338 */
339  const common::Time& GetDispatchedTime(void) const
340  {
341  return m_DispatchedTime;
342  }
343  //! @endcond
344 
345 
346 /*!
347 @brief Gets the maximum number of connections (<tt>Station</tt> instances) set when <tt>CreateInstance</tt> was called.
348 
349 @details This function is thread-safe.
350 
351 @return Returns the maximum number of stations that can be connected to.
352 @see CreateInstance
353 */
354  size_t GetMaxStationNum(void) const
355  {
356  return m_MaxStationNum;
357  }
358 
359 
360 /*!
361 @cond PRIVATE
362 @brief Gets the protocol manager.
363 
364 @return Returns the address of the protocol manager.
365 */
366  ProtocolManager* GetProtocolManager()
367  {
368  return &m_ProtocolManager;
369  }
370  //! @endcond
371 
372 
373 /*!
374 @cond PRIVATE
375 @brief Sets the interval at which to send keep-alive packets.
376 
377 @param[in] msec Specifies the interval at which to send keep-alive packets. The value is in milliseconds.
378 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.
379 @retval ResultInvalidArgument Specifies that there is an error in one or more arguments (for example, an argument is negative). Programming error. Fix your program so that this error is not returned.
380 @see GetKeepAliveInterval
381 */
382  nn::Result SetKeepAliveInterval(s32 msec);
383  //! @endcond
384 
385 
386 /*!
387 @brief Gets the interval at which to send keep-alive packets.
388 
389 @details This function is thread-safe.
390 
391 @return Returns the sending interval for keep-alive packets. The value is in milliseconds.
392 @see SetKeepAliveInterval
393 */
394  s32 GetKeepAliveInterval(void) const;
395 
396 
397 /*!
398 @brief Enables the keep-alive process.
399 
400 @see DisableKeepAlive, IsKeepAliveEnabled
401 */
402  void EnableKeepAlive(void);
403 
404 
405 /*!
406 @brief Disables the keep-alive process.
407 
408 @see EnableKeepAlive, IsKeepAliveEnabled
409 */
410  void DisableKeepAlive(void);
411 
412 
413 /*!
414 @brief Gets whether the keep-alive process is enabled.
415 
416 @details This function is thread-safe.
417 
418 @return Returns <tt>true</tt> if it is enabled, and <tt>false</tt> if it is disabled.
419 @see EnableKeepAlive, DisableKeepAlive
420 */
421  bool IsKeepAliveEnabled(void) const;
422 
423 
424 /*!
425 @brief Gets the address of the local device (<tt>@ref StationConnectionInfo</tt>).
426 
427 @details The address that is obtained when you are not connected to the network is undefined.
428 
429 @param[out] pInfoOut Specifies a pointer to the object that holds the local address.
430 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.
431 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
432 @see GetHostStationConnectionInfo
433 */
434  nn::Result GetLocalStationConnectionInfo(StationConnectionInfo* pInfoOut);
435 
436 
437 /*!
438 @brief Gets the address of the session host (<tt>@ref StationConnectionInfo</tt>).
439 
440 @details The address that is obtained when you are not connected to the network is undefined.
441 
442 @param[out] pInfoOut Specifies a pointer to the object that holds the address obtained for the session host.
443 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.
444 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
445 @see GetLocalStationConnectionInfo
446 */
447  nn::Result GetHostStationConnectionInfo(StationConnectionInfo* pInfoOut);
448 
449 
450 /*!
451 @cond PRIVATE
452 @brief Gets a pointer to the instance of the relay address table.
453 */
454  IRelayAddressTable* GetRelayAddressTable(void)
455  {
456  return m_pRelayAddressTable;
457  }
458  //! @endcond
459 
460 
461  /// @cond PRIVATE
462 /*!
463 @brief Gets a pointer to the instance of the relay request route manager class.
464 */
465  RelayRouteManager* GetRelayRouteManagerPtr(void)
466  {
467  return m_pRelayRouteManager;
468  }
469 
470 /*!
471 @brief Sets a pointer to the instance of the relay request route manager class.
472 */
473  void SetRelayRouteManagerPtr(RelayRouteManager* ptr)
474  {
475  m_pRelayRouteManager = ptr;
476  }
477 //! @endcond
478 
479 
480 #if NN_PIA_ENABLE_FEEDBACK
481  /// @cond PRIVATE
482 /*!
483 @brief Sends feedback data.
484 
485 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
486 @retval ResultInvalidState Indicates that the function was called at the wrong time. The <tt>Transport</tt> instance may not have been completely initialized or set up. Programming error. Fix your program so that this error is not returned.
487 */
488  nn::Result SendFeedback(void);
489 
490 /*!
491 @brief Sets the RTT value in the feedback data.
492 */
493  void SetFeedbackNetworkRtt();
494 /// @endcond
495 #endif // end of NN_PIA_ENABLE_FEEDBACK
496 
497  /// @cond PRIVATE
498  void SetMonitoringNetworkRtt(bool isBegin);
499  //! @endcond
500 
501  /// @cond PRIVATE
502  StationPacketHandler* GetStationPacketHandler(void)
503  {
504  return m_pPacketHandler;
505  }
506  //! @endcond
507 
508 
509 /*!
510 @brief Converts a <tt>StationId</tt> to a <tt>@ref StationIndex</tt>.
511 
512 @details The function returns a failure <tt>Result</tt> if the local station is not participating in the session or the function is called during a joint session.
513 @details This function can be called inside the session state-change event callback to which the EVENT_JOIN and EVENT_LEAVE events are reported.
514 @details This function works differently depending on whether it is used with the Session API or the Mesh API.
515 When used with the Mesh API, the conversion succeeds even if a <tt>StationId</tt> that is not a mesh participant is specified.
516 
517 @param[out] pIdx A pointer to where the converted <tt>@ref StationIndex</tt> is stored.
518 @param[in] id The <tt>StationId</tt> to convert.
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. Programming error. Fix your program so that this error is not returned.
521 @retval ResultInvalidState Not in a state where the conversion process can be run. The setup for <tt>session</tt> might not have been completed. Programming error. Fix your program so that this error is not returned.
522 @retval ResultNotFound Indicates that the station specified in the <tt>@ref nn::pia::StationId "StationId"</tt> is not participating in the session. Handle appropriately in the application.
523 @retval ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.
524 @see ConvertToStationId, session::Session::SessionEventCallback
525 
526 
527 */
528  nn::Result ConvertToStationIndex(StationIndex* pIdx, StationId id) const;
529 
530 
531 /*!
532 @cond PRIVATE
533 @brief Converts <tt>StationId</tt> to <tt>@ref StationIndex</tt>. No checks of arguments or states are performed.
534 
535 @details Because this function omits various checks, if it is called haphazardly, you run the risk of crashing the program with a memory access violation or some other issue.
536 
537 @param[in] id The <tt>StationId</tt> to convert.
538 @return <tt>STATION_INDEX_INVALID</tt> is returned when conversion fails.
539 */
540  StationIndex ConvertToStationIndexUnsafe(StationId id) const;
541  //! @endcond
542 
543 
544 /*!
545 @brief Converts a <tt>@ref nn::pia::StationId</tt> to a <tt>StationId</tt>.
546 
547 @details The function returns a failure <tt>Result</tt> if the local station is not participating in the session or the function is called during a joint session.
548 @details This function can be called inside the session state-change event callback to which the EVENT_JOIN and EVENT_LEAVE events are reported.
549 @details This function works differently depending on whether it is used with the Session API or the Mesh API.
550 When used with the Mesh API, the conversion succeeds even if a <tt>StationIndex</tt> that is not a mesh participant is specified.
551 
552 @param[out] pId Pointer to where the converted <tt>StationId</tt> is stored.
553 @param[in] idx The <tt>@ref StationIndex</tt> to convert.
554 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
555 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
556 @retval ResultInvalidState Not in a state where the conversion process can be run. The setup for <tt>session</tt> might not have been completed. Programming error. Fix your program so that this error is not returned.
557 @retval ResultNotFound Indicates that the station specified in the <tt>@ref nn::pia::StationIndex "StationIndex"</tt> is not participating in the session. Handle appropriately in the application.
558 @retval ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.
559 @see ConvertToStationIndex, session::Session::SessionEventCallback
560 
561 
562 */
563  nn::Result ConvertToStationId(StationId* pId, StationIndex idx) const;
564 
565 
566 /*!
567 @cond PRIVATE
568 @brief Converts <tt>@ref StationIndex</tt> to <tt>StationId</tt>. No checks of arguments or states are performed.
569 
570 @details Because this function omits various checks, if it is called haphazardly, you run the risk of crashing the program with a memory access violation or some other issue.
571 
572 @param[in] idx The <tt>StationIndex</tt> to convert.
573 @return <tt>STATION_ID_INVALID</tt> is returned when conversion fails.
574 */
575  StationId ConvertToStationIdUnsafe(StationIndex idx) const;
576  //! @endcond
577 
578 
579 /*!
580 @brief Checks the state of <tt>Transport</tt>, and determines whether sending and receiving processes can be executed in that state.
581 
582 @return Returns a <tt>Result</tt> value for which <tt>IsSuccess()</tt> returns <tt>true</tt> if the <tt>session</tt> module is finished being set up and the various API functions can be called without issue.
583 @retval ResultInvalidState The setup of the <tt>session</tt> module is not complete. Programming error. Fix your program so that this error is not returned.
584 @retval ResultTemporaryUnavailable The API function is temporarily unavailable because the joint session process is in progress. Handle appropriately in the application.
585 @see ConvertToStationIndex, ConvertToStationId
586 
587 */
588  nn::Result CheckTransportStatus() const
589  {
590  PIA_ASSERT((m_TransportStatus.IsSuccess())
591  || (ResultInvalidState::Includes(m_TransportStatus))
592  || (ResultTemporaryUnavailable::Includes(m_TransportStatus)));
593  return m_TransportStatus;
594  }
595 
596 
597 /*!
598 @cond PRIVATE
599 @brief Sets the <tt>Transport</tt> state. Call this function from <tt>session</tt>.
600 
601 @param[in] state Sets the <tt>Transport</tt> state with a <tt>Result</tt> value. Three kinds of <tt>Result</tt> values can be set: <tt>ResultInvalidState</tt>, <tt>ResultTemporaryUnavailable</tt> and <tt>ResultSuccess()</tt>.
602 Pass <tt>ResultSuccess</tt> to the argument when the <tt>session</tt> preparations are complete, <tt>ResultTemporaryUnavailable</tt> when a joint session process starts, and <tt>ResultInvalidState</tt> when destroying the <tt>session</tt>.
603 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if the call succeeds.
604 @retval ResultInvalidArgument Specifies that an argument is invalid. These three <tt>Result</tt> values are the only values that can be specified for <tt>state</tt>. Programming error. Fix your program so that this error is not returned.
605 
606 
607 
608 */
609  nn::Result SetTransportStatus(nn::Result state);
610  //! @endcond
611 
612 
613  // Controls whether to convert the <tt>StationId</tt> by using the <tt>StationIdTable</tt> class, or by converting directly.
614  void EnableStationIdTable()
615  {
616  m_bEnableStationIdTable = true;
617  }
618  void DisableStationIdTable()
619  {
620  m_bEnableStationIdTable = false;
621  }
622  bool IsEnableStationIdTable() const
623  {
624  return m_bEnableStationIdTable;
625  }
626 
627  // <tt>session</tt> is supposed to get an instance of the conversion table class with this API function, and then execute updates and similar processes.
628  //
629  const StationIdTable* GetStationIdTable() const
630  {
631  return m_pStationIdTable;
632  }
633  StationIdTable* GetStationIdTable()
634  {
635  return m_pStationIdTable;
636  }
637 
638 /*!
639 @brief Structure that collects the parameters to pass to the <tt>SetDebugSetting</tt> function.
640 */
642  {
644  : sendThreadLatencyEmulationPacketNum(0),
645  receiveThreadLatencyEmulationPacketNum(0),
646  bPacketLossEmulation(false)
647  {
648  } //!< Default constructor. Initializes all of the member variables.
649 
650  size_t sendThreadLatencyEmulationPacketNum; //!< The number of buffers used by the receive-latency emulation feature (about 1.5 KB per buffer).
651  size_t receiveThreadLatencyEmulationPacketNum; //!< The number of buffers used by the receive-latency emulation feature (about 1.5 KB per buffer).
652  bool bPacketLossEmulation; //!< Set to <tt>true</tt> when using the packet loss emulation feature.
653  };
654 
655 
656 /*!
657 @brief Enables debugging features.
658 
659 @details Enables debugging features based on the content set in the arguments.
660 Never call this API function in a product ROM.
661 @details When you use this API function, you must call it before calling the <tt>Transport::CreateInstance</tt> function.
662 
663 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
664 @retval ResultInvalidState Returned if this function is called at the wrong time. Programming error. Fix your program so that this error is not returned.
665 
666 */
667  static nn::Result SetDebugSetting(const struct DebugSetting& setting);
668 
669 
670 /*!
671 @brief Prints information that is useful for debugging.
672 
673 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
674 */
675  virtual void Trace(u64 flag) const;
676 
677  //n1589: Needed for <tt>NexFacade</tt>.
678  common::IPacketInput* GetInputStream(void);
679  common::IPacketOutput* GetOutputStream(void);
680 
681  void OutputStreamUpdateEvent(void);
682 
683  // Disconnection event.
684  enum DisconnectionEventType
685  {
686  EVENT_LEAVE, // Normal departure from a session.
687  EVENT_REJOIN // Leave temporarily to join another session.
688  };
689 
690  // Event listener.
691  typedef DisconnectionEventType (*DisconnectionEventListener)(void* pStationIdTableEntry);
692 
693  void RegisterEventListener(DisconnectionEventListener func)
694  {
695  m_EventListener = func;
696  }
697  DisconnectionEventListener GetEventListener()
698  {
699  return m_EventListener;
700  }
701 
702 private:
703 /*!
704 @cond PRIVATE
705 @brief This is a dispatch function.
706 
707 @details Use this function to pass data between the <tt>PiaTransport</tt> sending and receiving threads, or execute the send or receive processes for a particular protocol.
708 This function never blocks waiting for data to be sent or received, because it does not call send or receive functions in the wireless module. (The calls to sending and receiving functions in the wireless module are made in the <tt>PiaTransport</tt> sending and receiving threads.)
709 The assumption is that this function will be called at least once for each game frame.
710 
711 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
712 @retval ResultInvalidState Specifies that protocol initialization or some other process may not be finished. Programming error. Fix your program so that this error is not returned.
713 
714 
715 
716 
717 */
718  nn::Result dispatch(void);
719  //! @endcond
720 
721 
722 /*!
723 @cond PRIVATE
724 @brief Initializes the <tt>Transport</tt> instance.
725 
726 @details Initializes the factory to use and configures the maximum station count.
727 
728 @param[in] setting Specifies the <tt>Setting</tt> struct that parameters are stored in.
729 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
730 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
731 @see finalize
732 */
733  nn::Result initialize(const Transport::Setting& setting);
734  //! @endcond
735 
736 
737 /*!
738 @cond PRIVATE
739 @brief Finalizes the instance.
740 @see initialize
741 */
742  void finalize(void);
743  //! @endcond
744 
745 
746 /*!
747 @brief This copy constructor is private.
748 */
749  Transport(const Transport&);
750 
751 /*!
752 @brief This assignment operator is private.
753 */
754  Transport& operator=(const Transport&);
755 
756 
757 /*!
758 @brief Updates the time immediately following a call to the <tt>Dispatch</tt> function.
759 
760 @details To reduce CPU load, only call this once per call to the <tt>Dispatch</tt> function.
761 This time is used for keep-alive and other processing.
762 Updating the time only once per dispatch is typically enough because a high level of accuracy is not required.
763 @see GetDispatchedTime
764 */
765  void updateDispatchedTime(void)
766  {
767  m_DispatchedTime = common::Time::GetTime();
768  }
769 
770 
771  void updateTransportAnalyzer(void);
772 
773 
774  // Job to call <tt>dispatch</tt>.
775  class DispatchJob : public common::Job
776  {
777  protected:
778  virtual ExecuteResult ExecuteCore()
779  {
780  Transport::GetInstance()->dispatch();
781  return Job::EXECUTE_STATE_WAIT_NEXT;
782  }
783  };
784 
785  common::Time m_DispatchedTime;
786 
787  ProtocolManager m_ProtocolManager;
788  StationPacketHandler* m_pPacketHandler;
789 
790  size_t m_MaxStationNum;
791 
792  bool m_StartupFlag;
793 
794  nn::Result m_ConnectionError;
795  DispatchJob m_DispatchJob;
796 
797  IRelayAddressTable* m_pRelayAddressTable;
798  RelayRouteManager* m_pRelayRouteManager;
799 
800 #if NN_PIA_ENABLE_FEEDBACK
801  u32 m_FeedbackSenderProtocolHandle;
802 #endif
803 
804  s32 m_AnalysisInterval; // The interval, in seconds, for automatic calls to the <tt>TransportAnalyzer::Update</tt> function. In seconds.
805  common::Time m_AnalysisUpdatedTime; // The time when the <tt>TransportAnalyzer::Update</tt> function was last called.
806 
807  DisconnectionEventListener m_EventListener;
808 
809  StationIdTable* m_pStationIdTable;
810  bool m_bEnableStationIdTable;
811 
812  nn::Result m_TransportStatus; // The state of <tt>Transport</tt>, controlled by <tt>session</tt>.
813 
814  static struct DebugSetting s_DebugSetting;
815 
816  static Transport* s_pInstance;
817 };
818 }
819 }
820 } // end of namespace nn::pia::transport
size_t receiveThreadLatencyEmulationPacketNum
The number of buffers used by the receive-latency emulation feature (about 1.5 KB per buffer)...
Definition: transport_Transport.h:651
static Transport * GetInstance(void)
Gets the Transport class instance (singleton pattern). This function returns a NULL pointer if the in...
Definition: transport_Transport.h:216
Class that represents time.
Definition: common_Time.h:39
StationIndex
Enumerates StationIndex values.
Definition: platformCtr.h:44
Definition of the StationId identifying the station within the session.
Definition: types.h:33
size_t maxSendThreadBufferNum
The number of buffers that the sending thread of the Pia library uses to send packets (about 1...
Definition: transport_Transport.h:160
Definition: assert.h:115
size_t sendThreadLatencyEmulationPacketNum
The number of buffers used by the receive-latency emulation feature (about 1.5 KB per buffer)...
Definition: transport_Transport.h:650
T * GetProtocol(u32 protocolHandle)
Gets an instance of a protocol of type T.
Definition: transport_Transport.h:293
s32 analysisInterval
The interval at which measurement results from the TransportAnalyzer feature are automatically output...
Definition: transport_Transport.h:162
u32 CreateProtocol(u16 port=0)
Generates an instance of a protocol of type T.
Definition: transport_Transport.h:265
size_t maxReceiveThreadBufferNum
The number of buffers that the receiving thread of the Pia library uses to receive packets (about 1...
Definition: transport_Transport.h:161
void DestroyProtocol(u32 protocolHandle)
Destroys the protocol instance.
Definition: transport_Transport.h:277
Provides core functionality of the transport module.
Definition: transport_Transport.h:116
DebugSetting()
Default constructor. Initializes all of the member variables.
Definition: transport_Transport.h:643
nn::Result CheckConnectionError(void) const
Gets the connection status of the transport module.
Definition: transport_Transport.h:326
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
Represents an address used to uniquely identify stations.
Definition: transport_StationConnectionInfo.h:35
bool bPacketLossEmulation
Set to true when using the packet loss emulation feature.
Definition: transport_Transport.h:652
Stores parameters passed to the CreateInstance function.
Definition: transport_Transport.h:134
nn::Result CheckTransportStatus() const
Checks the state of Transport, and determines whether sending and receiving processes can be executed...
Definition: transport_Transport.h:588
NetworkFactory * pFactory
Pointer to an instance of the concrete class that inherits NetworkFactory (factory pattern)...
Definition: transport_Transport.h:158
size_t maxStationNum
Specifies the maximum number of Stations that can join a single network.
Definition: transport_Transport.h:159
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40
Structure that collects the parameters to pass to the SetDebugSetting function.
Definition: transport_Transport.h:641
size_t GetMaxStationNum(void) const
Gets the maximum number of connections (Station instances) set when CreateInstance was called...
Definition: transport_Transport.h:354
static Time GetTime()
Gets a Time instance representing the current time.
Definition: common_Time.h:78
A structure for encryption settings.
Definition: common_CryptoSetting.h:33