CTR Pia  4.11.3
Game Communication Engine
session_Mesh.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: session_Mesh.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/common/common_RootObject.h>
18 #include <pia/common/common_CallContext.h>
19 #include <pia/common/common_SignatureSetting.h>
20 
21 #include <pia/session/session_definitions.h>
22 #include <pia/session/session_types.h>
23 
24 #include <pia/transport/transport_Station.h>
25 #include <pia/transport/transport_StationLocationContainer.h>
26 #include <pia/transport/transport_StationConnectionInfo.h>
27 
28 namespace nn
29 {
30 namespace nex
31 {
32 class StationURL;
33 }
34 }
35 
36 namespace nn
37 {
38 namespace pia
39 {
40 namespace common
41 {
42 struct CryptoSetting;
43 class MonitoringDataSender;
44 }
45 }
46 }
47 
48 namespace nn
49 {
50 namespace pia
51 {
52 namespace transport
53 {
54 class StationProtocol;
55 class ConnectStationJob;
56 class DisconnectStationJob;
57 class ProcessConnectionRequestJob;
58 class MissingStationHandler;
59 class NetworkFactory;
60 #if NN_PIA_EXPERIMENT_BAND_WIDTH_CHECK
61 class BandwidthCheckerProtocol;
62 #endif
63 }
64 }
65 }
66 
67 namespace nn
68 {
69 namespace pia
70 {
71 namespace session
72 {
73 
74 class CreateMeshJob;
75 class JoinMeshJob;
76 class LeaveMeshJob;
77 class ProcessJoinRequestJob;
78 class ProcessUpdateMeshJob;
79 class DestroyMeshJob;
80 class ProcessDestroyMeshJob;
81 class ProcessHostMigrationJob;
82 class LeaveWithHostMigrationJob;
83 class SignatureSettingStorage;
84 #if NN_PIA_EXPERIMENT_RELAY_CONNECTION_TOPOLOGY
85 class RelayRouteManageJob;
86 #endif
87 class KickoutManageJob;
88 class MeshProtocol;
89 class SyncClockProtocol;
90 class MeshEventListener;
91 
92 static const u16 PIA_SESSION_STATION_MAX_DEFAULT = 4;
93 
94 /*!
95  @class nn::pia::session::Mesh
96  @brief Contains member functions that manage connections with other devices.
97 
98  @details This class implements the singleton pattern. Only a single instance can be created.
99 
100  @attention This class is for directly manipulating meshes. Do not use the <tt>Mesh</tt> class when using sessions. Do not use the <tt>Session</tt> class when directly manipulating meshes.
101 
102  @details Some of the internal processes of the <tt>Mesh</tt> class are registered as jobs in <tt>@ref nn::pia::common::Scheduler</tt>. To use the <tt>Mesh</tt> features, you must make periodic calls to
103  <tt>@ref nn::pia::common::Scheduler::Dispatch</tt>.
104 
105  @date 2015-05-20 Added the <tt>Mesh::GetUplinkBitRate</tt> function.
106  @date 2015-05-20 Added the <tt>bitRateCheckMode</tt> member to the <tt>Setting</tt> structure to enable configuration of the bit rate detection feature.
107  @date 2015-05-20 Added the <tt>uplinkBitRateLowerLimit</tt> and <tt>bitRateCheckPacketSize</tt> members to the <tt>StartupSetting</tt> structure to enable configuration of the bit rate detection feature.
108  @date 2015-05-11 Provided the <tt>StartupSetting</tt> structure to consolidate the arguments when calling the <tt>Startup()</tt> function.
109  @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.
110  @date 2014-09-17 Changed the <tt>Result</tt> returned when a <tt>StationId</tt> that has already been kicked out is specified for <tt>Mesh::KickoutStation</tt>.
111  @if CTR_DOC
112  @date 2014-05-30 Changed the notations for the cautions when local communication for <tt>Mesh::Startup</tt> and host migration are enabled.
113  @endif
114  @date 2014-05-15 Added the <tt>Mesh::CheckConnection</tt> function that returns a <tt>Result</tt> indicating whether <tt>Mesh</tt> is in a communicable state.
115  @if CTR_DOC
116  @date 2014-05-02 Added a note to the description of <tt>Mesh::Startup(const transport::Station::PlayerName*, const common::CryptoSetting*, const common::SignatureSetting&, const transport::Station::IdentificationToken*)</tt> about the affect of the UdsNode connection monitoring feature when the host migration feature is enabled for local communication.
117  @date 2014-04-17 Added a note to the description of <tt>Mesh::Startup(u32, u32, const transport::Station::PlayerName*, const common::CryptoSetting*, const common::SignatureSetting&, const transport::Station::IdentificationToken*)</tt> about the affect of the UdsNode connection monitoring feature when the host migration feature is enabled for local communication.
118  @endif
119  @date 2014-02-10 Added a note to the descriptions of both <tt>Mesh::RelayEmulation</tt> and <tt>Mesh::ResetRelayEmulation</tt> about when the functions can be called.
120  @date 2014-02-03 Organized the results that are returned when <tt>Mesh::JoinMeshAsync</tt> or asynchronous processes fail, and increased the number of reasons for distinguishable asynchronous process failures.
121  @date 2013-12-18 Removed the synchronous processing version of <tt>Mesh::CreateMesh</tt>.
122  @date 2013-12-11 Fixed a bug where the asynchronous processing result was different from the actual reason for failure when <tt>Mesh::JoinMesh</tt> failed because its request was rejected due to the internal state of the host's library.
123  @date 2013-12-04 Added an overload with arguments to <tt>Mesh::Startup</tt> to pass a structure for the encryption settings.
124  @if CAFE_DOC
125  @date 2013-10-07 <tt>ResultInvalidArgument</tt> was being returned when a player name with an undefined language code was passed to <tt>Mesh::Startup</tt>, but this was changed to not return an error when the language code is undefined.
126  @endif
127  @date 2013-08-09 Fixed a bug where the internal state would become inconsistent if <tt>Mesh::DestroyMesh</tt> was called while joining a mesh, or if a station called <tt>Mesh::KickoutStation</tt> on itself.
128  @date 2013-08-09 Corrected the descriptions of the return values of <tt>Mesh::GetConnectionRoute</tt> and <tt>Mesh::RelayEmulation</tt>. (No changes were made to conditions that result in an error or <tt>Result</tt> types.)
129  @date 2013-08-06 Fixed a bug where meshes would disconnect during host migration if the single-candidate host migration feature was enabled while a relay type network topology was also enabled.
130  @date 2013-07-26 Removed <tt>Mesh::GetIdentificationToken</tt>.
131  @date 2013-07-10 Changed the specifications of <tt>Mesh::Startup</tt> about the timeout used with the <tt>Mesh::JoinMesh</tt> process so that it cannot be changed by applications.
132  @date 2013-07-10 Removed some <tt>Result</tt> types that can be returned when asynchronous processing of <tt>Mesh::JoinMesh</tt> fails.
133  @date 2013-06-25 Added the <tt>Mesh::RelayEmulation</tt> and <tt>Mesh::ResetRelayEmulation</tt> functions for debugging the relay feature.
134  @date 2013-06-25 Added an overload to <tt>Mesh::CreateInstance</tt> allowing you to enable or disable the use of debugging of the relay feature.
135  @date 2013-06-18 Changed the specification to check whether lower modules can use host migration when <tt>Mesh::Startup</tt> is called while host migration is enabled.
136  @date 2013-06-13 Fixed a bug where calls to <tt>Mesh::LeaveMesh</tt> would fail if they were called at the same time a station was being kicked from the mesh using <tt>Mesh::KickoutStation</tt>.
137  @date 2013-05-28 Changed the default timeout for <tt>Mesh::JoinMesh</tt> processing (defined by the <tt>NN_PIA_SESSION_JOIN_TIMEOUT_DEFAULT</tt> constant) from 20,000 milliseconds to 30,000 milliseconds.
138  @date 2013-05-15 Added the <tt>Mesh::KickoutStation</tt> function for kicking out an arbitrary station from the mesh.
139  @date 2013-05-15 Added the <tt>Mesh::DisconnectReason</tt> enumerated type to represent reasons why a station is unable to connect to a mesh, and the <tt>Mesh::GetDisconnectReason</tt> function to get this reason.
140  @date 2013-04-24 Added the <tt>Mesh::GetConnectionRoute</tt> function for debugging relaying.
141  @date 2013-04-19 Fixed a bug where the state could become inconsistent if a host migration started while another station was joining the mesh, under certain timing and other conditions.
142  @date 2013-04-08 Added available settings to use as the network topology for the meshes built using the <tt>Mesh</tt> class.
143  @date 2013-04-08 Added the following functions for changing settings when relaying is enabled: <tt>Mesh::SetMaxNumOfRelayRoutesAssignedToStation</tt> and <tt>Mesh::SetMaxRtt</tt>.
144  @date 2013-03-29 Changed the <tt>Mesh::Startup</tt> function to set the player name.
145  @date 2013-03-14 Added an asynchronous version of the <tt>Mesh::CreateMesh</tt> function.
146  @date 2013-01-08 Fixed a low-frequency bug where other clients could get into an inconsistent state if a client left a mesh and then tried to join the same one again.
147  @date 2012-12-20 Fixed a bug where an inconsistent internal state could occur if the other client disconnected at certain times while a new client was joining the mesh.
148  @date 2012-12-19 Reviewed the value of <tt>nn::pia::session::NN_PIA_SESSION_KEEP_ALIVE_INTERVAL_DEFAULT</tt> (the default setting for the interval at which to send keep-alives), and changed it from 2000 to 1000.
149  @date 2012-12-18 Fixed a bug where clients already in a mesh could be dropped if a new client failed to join it.
150  @date 2012-12-18 Added a <tt>Result</tt> type that can be returned when asynchronous processing of a <tt>Mesh::JoinMesh</tt> fails.
151  @date 2012-12-10 Fixed a timing bug where host migration could fail when it was expected to succeed.
152  @date 2012-12-10 Fixed a bug where local host migration would fail for everyone unless it succeeded for all the remaining clients.
153  @date 2012-12-10 Fixed a bug where some clients were highly likely to fail to join a mesh when multiple clients tried to join at the same time.
154  @date 2012-11-30 Changed the specifications to configure the packet-signing feature when calling the <tt>Mesh::Startup</tt> function. The parameter specification was changed.
155  @date 2012-11-26 Fixed a bug where the internal status of the mesh host could become inconsistent when a client failed to join the session, depending on the progress status of other processes.
156  @date 2012-11-13 Fixed a bug where the mesh client could never detect an abnormal connection status if communication with another client was lost.
157  @date 2012-10-29 Categorized member functions to improve readability of the API reference.
158  @date 2012-08-22 Fixed a bug in the link between the server matchmaking process for Internet communication and the mesh participation process.
159  @date 2012-08-22 As a result of this fix, communication with <tt>PiaMesh</tt> in earlier versions is no longer compatible.
160  @date 2012-08-20 Fixed a bug where disconnect events with the same <tt>StationIndex</tt> were duplicated in events sent in a callback for a mesh state change notification.
161  @date 2012-08-07 Fixed a bug where continuing host migration by using local communication frequently failed.
162  @date 2012-07-18 Made minor amendments to the descriptions of the <tt>Mesh::Startup</tt>, <tt>Mesh::Cleanup</tt>, and related functions.
163  @date 2012-07-10 Improved the speed and accuracy of host migration failure assessments during host migration.
164  @date 2012-07-05 Added a <tt>Mesh::Startup</tt> overload that enables you to specify any settings, such as the timeout period for the mesh participation process.
165  @date 2012-07-03 Added a <tt>Result</tt> type that can be returned when asynchronous processing of a <tt>Mesh::JoinMesh</tt> fails.
166  @date 2012-07-02 Fixed a bug where when running a <tt>Mesh::DestroyMesh</tt>, the mesh destroy message sometimes did not reach the client.
167  @date 2012-06-11 Fixed a bug where a station could not join a session using the <tt>Mesh::JoinMesh</tt> function if another station left the mesh while the function was executing.
168  @date 2012-05-30 Fixed a bug where clients did not receive notifications when the mesh host called the <tt>Mesh::DestroyMesh</tt> function.
169  @date 2012-05-30 Fixed a bug where disconnecting from a peer at nearly the same time the <tt>Mesh::LeaveMesh</tt> function starts would result in a timeout wait even though the peer had already disconnected.
170  @date 2012-05-22 Implemented host migration. To enable or disable the host migration feature, use the <tt>Mesh::Setting</tt> structure, which is passed when you create a <tt>Mesh</tt> instance.
171  @date 2012-05-22 Added the <tt>Mesh::LeaveMeshWithHostMigration</tt> function.
172  @date 2012-05-22 Added host migration-related events to the events that are notified with the state change notification callback for the mesh.
173  @date 2012-05-22 Changed the name of the event enumerated type from <tt>Event</tt> to <tt>EventType</tt> for the state change notification callback for the mesh.
174  @date 2012-05-15 Added a function to get and set the synchronization pulse interval of the synchronization clock.
175  @date 2012-05-11 Added the <tt>GetTime</tt> function, which can get the elapsed time (called the synchronization clock) from the time that the mesh was created.
176  @date 2012-05-01 Added the <tt>Mesh::Startup</tt> function.
177  @date 2012-05-01 Implemented the shared identification token feature.
178  @date 2012-04-24 Added a feature to notify, in a callback, the changes to mesh information when joining or leaving stations.
179  @date 2012-04-16 Changed the maximum specification value of connectible stations from <tt>10</tt> to <tt>12</tt>.
180  @date 2012-04-12 Listed <tt>const</tt> information for functions in which the internal state does not change.
181  @date 2012-04-12 Changed <tt>Mesh::DestroyMesh</tt> so that it is an asynchronous process.
182  @date 2012-04-12 Added an enumerated type to indicate the <tt>Mesh</tt> state and a function for getting the state.
183  @date 2012-04-12 Implemented a keep-alive feature.
184  @date 2012-04-06 Initial version.
185 */
187 {
188  friend class CreateMeshJob;
189  friend class JoinMeshJob;
190  friend class LeaveMeshJob;
191  friend class ProcessJoinRequestJob;
192  friend class ProcessUpdateMeshJob;
193  friend class DestroyMeshJob;
194  friend class ProcessDestroyMeshJob;
195  friend class ProcessHostMigrationJob;
196  friend class LeaveWithHostMigrationJob;
197  friend class KickoutManageJob;
198  friend class MeshProtocol;
199  friend class MeshEventListener;
200 
201 public:
202 /*!
203  @brief This structure stores settings passed to <tt>@ref nn::pia::session::Mesh::CreateInstance</tt>.
204 */
205  struct Setting
206  {
207 #if NN_PIA_EXPERIMENT_BAND_WIDTH_CHECK
208  Setting()
209  : bitRateCheckMode(session::BitRateCheck_Disable)
210  {
211  }
212 #endif
213  nn::pia::transport::NetworkFactory* pNetworkFactory; //!< Pointer to an instance of the concrete class that inherits <tt>@ref nn::pia::transport::NetworkFactory</tt> (factory pattern). It is used only when creating a <tt>Mesh</tt> instance.
214  nn::pia::session::NetworkTopology networkTopology; //!< Specifies the network topology setting for the mesh.
215 #if NN_PIA_EXPERIMENT_BAND_WIDTH_CHECK
216  nn::pia::session::BitRateCheckMode bitRateCheckMode; //!< Settings for the bitrate detection feature.
217 #endif
218  };
219 
220 /*!
221  @brief This structure stores settings passed to <tt>@ref nn::pia::session::Mesh::Startup</tt>.
222 */
224  {
226  : maxSilenceTime(NN_PIA_SESSION_MAX_SILENCE_TIME_DEFAULT),
227  keepAliveSendingInterval(NN_PIA_SESSION_KEEP_ALIVE_INTERVAL_DEFAULT),
228  bUsingHostMigration(true),
229  pPlayerName(NULL),
230  pCryptoSetting(NULL),
232 #if NN_PIA_EXPERIMENT_BAND_WIDTH_CHECK
233  uplinkBitRateLowerLimit(NN_PIA_SESSION_INVALID_UPLINK_BIT_RATE_LOWER_LIMIT),
234  bitRateCheckPacketSize(0),
235  bitRateMeasuringSpan(1000),
236  isSkipBitRateCheck(false),
237 #endif
238  pToken(NULL)
239  {
240  }
241 
242  u32 maxSilenceTime; //!< Specifies the maximum allowable time without communication (in milliseconds). The default value is <tt>session::NN_PIA_SESSION_MAX_SILENCE_TIME_DEFAULT</tt>. The maximum value that can be set is <tt>session::NN_PIA_SESSION_MAX_SILENCE_TIME_MAX</tt>, the minimum value is <tt>session::NN_PIA_SESSION_MAX_SILENCE_TIME_MIN</tt>.
243  u32 keepAliveSendingInterval; //!< Specifies the send interval for keep-alive (in milliseconds). The default value is <tt>session::NN_PIA_SESSION_KEEP_ALIVE_INTERVAL_DEFAULT</tt>.
244  bool bUsingHostMigration; //!< Sets the use of the host migration feature. The default is <tt>true</tt> (enabled).
245  const nn::pia::transport::Station::PlayerName* pPlayerName; //!< Specifies the name and language code associated with the local station. Other members of the mesh access this information.
246  const nn::pia::common::CryptoSetting* pCryptoSetting; //!< Specifies a pointer that points to a structure for configuring encryption. No encryption is configured if <tt>NULL</tt> is specified. The default is <tt>NULL</tt>.
247  nn::pia::common::SignatureSetting signatureSetting; //!< Specifies a properly configured instance of the class used to specify packet-signature settings. The default value for this parameter is <tt>unsigned</tt>.
248 #if NN_PIA_EXPERIMENT_BAND_WIDTH_CHECK
249  s32 uplinkBitRateLowerLimit; //!< Specifies the minimum rate required by the application when using the bitrate detection feature. The value is in bits per second. The default value is <tt>session::NN_PIA_SESSION_INVALID_UPLINK_BIT_RATE_LOWER_LIMIT</tt>.
250  size_t bitRateCheckPacketSize; //!< Specifies the IP packet size used for testing when using the bitrate detection feature. The value is in bytes. The expected value is the average size of IP packet sent and received by the application. It must be a multiple of 4. The default is <tt>0</tt>.
251  s32 bitRateMeasuringSpan; //!< Sets the time to spend measuring when the bit rate detection feature is used. The value is in milliseconds. The default is <tt>1000 msec</tt>. Changing this value from the default is not recommended.
252  bool isSkipBitRateCheck; //!< Set to skip detection processes when using bitrate detection. Specify <tt>true</tt> to skip. The default is <tt>false</tt>.
253 #endif
254  const nn::pia::transport::Station::IdentificationToken* pToken; //!< Specifies a pointer to the identification token indicating the local device. If <tt>NULL</tt> is specified, an identification token with all data set to <tt>NULL</tt> is used. The default is <tt>NULL</tt>.
255 
256  };
257 
258 /*!
259  @brief (For debugging.) This structure stores the debug feature settings that are passed to <tt>@ref nn::pia::session::Mesh::SetDebugSetting</tt>.
260 */
262  {
263  DebugSetting(bool argIsEnableRelayEmulation = false, bool argIsDisableCheckMaxSilenceTime = false)
264  : isEnableRelayEmulation(argIsEnableRelayEmulation),
265  isDisableCheckMaxSilenceTime(argIsDisableCheckMaxSilenceTime)
266  {
267  }
268  bool isEnableRelayEmulation; //!< Settings for the connection route emulation feature for debugging.
269  bool isDisableCheckMaxSilenceTime; //!< Does not check the range set for the maximum time without communication.
270  };
271 
272 /*!
273  @cond PRIVATE
274  @brief Enumerates mesh states.
275 */
276  enum State
277  {
278  STATE_DISCONNECTED, //!< Specifies that the local device is not connected to other devices and communication is not possible.
279  STATE_CONNECTED //!< Specifies that the local device is connected to other devices and communication is possible.
280  };
281  //! @endcond
282 
283 /*!
284  @brief This enumerated type represents reasons why a <tt>Mesh</tt> object cannot communicate.
285 
286  @details This information can be retrieved using the <tt>Mesh::GetDisconnectReason</tt> function.
287 */
289  {
290  UNKNOWN_REASON = 0, //!< Specifies that the reason for the disconnection is unknown. One way to get this value is by calling the <tt>Mesh::Cleanup</tt> function during mesh communication (without destroying or leaving the mesh).
291  NOT_YET_COMMUNICATED, //!< Specifies that no communication has been performed. You get this value if you never build or join a mesh after calling the <tt>Mesh::Startup</tt> function.
292  OPERATION_OF_OWN, //!< Specifies that the disconnection was caused by the local station. You get this value when the local station left the mesh by calling the <tt>Mesh::DestroyMesh</tt> or <tt>Mesh::LeaveMesh</tt> function, or the equivalent.
293  OPERATION_OF_OTHER, //!< Specifies that the disconnection was caused by another station in the mesh. One way to get this value is when the local station is a client, and the host destroys the mesh.
294  KICKOUT_BY_USER, //!< Specifies that the local station was kicked out from the mesh because of a call to the <tt>Mesh::KickoutStation</tt> function.
295  KICKOUT_BY_SYSTEM, //!< Specifies that the disconnection from the mesh was caused by the library. One way to get this value is when relaying is enabled, and the library disconnects you from the mesh because it restricts the number of relay requests.
296  INCONSISTENT_INFO, //!< Specifies that the disconnection was caused by a desync. (The mesh information was no longer consistent between participants.) One way to get this value is when the station counts do not match.
297  MIGRATION_FAIL, //!< Specifies that the disconnection was caused by a failed host migration.
298  EXTERNAL_FACTOR, //!< Specifies that the disconnection was caused by something other than the <tt>Mesh</tt> object. One way to get this value is when the network connection is lost.
299  MIGRATION_FATAL_ERROR //!< Specifies that a fatal error occurred during host migration. This error can occur when the library detects that a mesh has broken up.
300  };
301 
302 
303 /*!
304  @brief Enumerates connection path emulation settings. (For debugging.)
305 
306  @details This is used as the third argument to <tt>Mesh::RelayEmulation</tt>.
307 */
309  {
310  EMULATION_TYPE_NONE = 0, //!< Specifies no emulation.
311  EMULATION_TYPE_RELAY //!< Specifies the relay connection. (No direct connection is possible.)
312  };
313 
314 
315 /*!
316  @brief This enumerated type is passed as a parameter to the callback that sends notifications about changes in the mesh state.
317 
318  @details It represents the possible changes to the mesh state.
319 */
321  {
322  EVENT_JOIN, //!< Indicates that a station has joined.
323  EVENT_LEAVE, //!< A station has left.
324  EVENT_HOST_CHANGED, //!< Specifies that the mesh host has migrated. (Only occurs when host migration is enabled.)
325  EVENT_MIGRATION_FAIL //!< Indicates that host migration failed. (Only occurs when host migration is enabled.)
326  };
327 
328 /*!
329  @brief This callback function type is called when the mesh state changes.
330 
331  @details <b>Parameters</b>
332  <ul>
333  <li> eventType: Enumerated type indicating what the state change was. For more information, see the <tt>@ref EventType</tt> enumerated type.</li>
334  <li> id: The <tt>StationId</tt> of the station that changed its state.</li>
335  </ul>
336 */
337  typedef void (*MeshEventCallback)(EventType eventType, StationId id);
338 
339 
340 /*!
341  @brief Declares the type of the callback function for determining whether to approve join requests from clients.
342 
343  @details If the callback returns <tt>true</tt>, the join request is approved. If it returns <tt>false</tt>, the join request is denied.
344 
345  <b>Parameters</b>
346  <ul>
347  <li> pRequesterToken: Pointer to the identification token for the station that sent the join request.</li>
348  </ul>
349 */
350  typedef bool (*JoiningMeshApprovalCallback)(const nn::pia::transport::Station::IdentificationToken* pRequesterToken);
351 
352  /// @cond PRIVATE
353 /*!
354  @brief The callback function for adjusting to any secondary host candidate position when using multiple candidate host migration.
355 
356  @details The secondary host candidate position can be adjusted if any host candidate position (in ascending order) is returned for the <tt><var>targetId</var></tt> parameter.
357 */
358  typedef u8 (*CheckHostCandidateRankingCallback)(StationIndex targetId, bool isHost);
359  /// @endcond
360 
361  /// @cond PRIVATE
362  typedef u32 (*GetSessionIdCallback)();
363  /// @endcond
364 
365 /*!
366  @name Singleton Instance Control
367  @{
368 */
369 
370 /*!
371  @brief Creates an instance of <tt>Mesh</tt>.
372 
373  @details This function must be executed between calls to the <tt>@ref nn::pia::session::BeginSetup</tt> and <tt>@ref nn::pia::session::EndSetup</tt> functions.
374 
375  @details If the relay emulation feature for debugging has been set by the <tt>@ref SetDebugSetting</tt> function,
376  and the network topology is not set to <tt>NetworkTopology_RelayMesh</tt>, the call to this function fails.
377 
378  @attention Do not call <tt>@ref SetDebugSetting</tt> in retail ROMs.
379 
380  @param[in] setting Specifies various settings.
381 
382  @return Returns the result of the function. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. You must make sure that the implementation of this function in your application does not return any errors.
383  If this function call fails, one or more of the following <tt>Result</tt> values is returned.
384  @retval ResultNotInitialized Indicates that the <tt>session</tt> module is not initialized. Programming error. Fix your program so that this error is not returned.
385  @retval ResultInvalidState Indicates that the function cannot be executed in this state. This error is returned when the function is executed outside calls to the <tt>@ref nn::pia::session::BeginSetup</tt> and <tt>@ref nn::pia::session::EndSetup</tt> functions. Programming error. Fix your program so that this error is not returned.
386  @retval ResultInvalidArgument Indicates that the settings specified in the argument are invalid. Programming error. Fix your program so that this error is not returned.
387  @retval ResultAlreadyExists Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
388 */
389  static nn::Result CreateInstance(const nn::pia::session::Mesh::Setting& setting);
390 
391 
392 /*!
393  @brief Destroys the instance of <tt>Mesh</tt>.
394 */
395  static void DestroyInstance();
396 
397 
398 /*!
399  @brief Gets an instance of the <tt>Mesh</tt> object.
400 
401  @details The <tt>Mesh</tt> class is a singleton. Only one instance of this class is automatically created.
402  The pointer to this single instance can be obtained by calling this function.
403 
404  @return Returns a pointer to an instance of the <tt>Mesh</tt> object.
405 */
406  static Mesh* GetInstance()
407  {
408  return s_pMesh;
409  }
410 
411 
412 /*!
413  @brief (For debugging.) Sets the debugging features for <tt>Mesh</tt>.
414 
415  @details This function can be called even when a <tt>Mesh</tt> instance does not yet exist. Call it before calling the <tt>@ref CreateInstance</tt> function to create a <tt>Mesh</tt> instance.
416 
417  If the <tt>isEnableRelayEmulation</tt> member of the <tt>DebugSetting</tt> structure is set to <tt>true</tt>, the <tt>Session</tt> will be configured to use the relay emulation feature for debugging.
418  When the session is configured to use the relay emulation feature, the <tt>@ref CreateInstance</tt> function will not succeed unless the network topology is set to <tt>NetworkTopology_RelayMesh</tt>.
419 
420  If this function is not called, all related debugging features are disabled.
421 
422  @attention Do not call this function in retail ROMs.
423 
424  @return Returns the result of the function. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. You must make sure that the implementation of this function in your application does not return any errors.
425  If this function call fails, one or more of the following <tt>Result</tt> values is returned.
426  @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returns when the <tt>Mesh</tt> instance has already been created. Programming error. Fix your program so that this error is not returned.
427 */
428  static nn::Result SetDebugSetting(const DebugSetting& debugSetting);
429 
430 /*!
431  end of name Singleton Instance Control
432  @}
433 */
434 
435 /*!
436  @name Finish Initialization
437  @{
438 */
439 
440 /*!
441  @brief Starts the <tt>Mesh</tt>.
442 
443  @details The use of host migration is set by the <tt>bUsingHostMigration</tt> member of the <tt>StartupSetting</tt> structure. Set to <tt>true</tt> to enable. The default is <tt>true</tt>.
444  Specify the name and language code associated with the local station in the <tt>pPlayerName</tt> member of <tt>StartupSetting</tt>. The name must be no longer than 16 characters (not including the terminating null character).
445  @if CAFE_DOC
446  Set the language code to the language used by the application. Use one of the values defined in <tt>nn::fp::Language</tt>.
447  The name and language code you specify are shared with all members of the mesh. When the local station joins a mesh, all mesh participants are added to Player History. When another
448  client joins the mesh, the new participant's name and language code are looked up and automatically
449  added to Player History using the <tt>nn::fp::AddRecentPlayRecord()</tt> function from within the library.
450  For more information about Player History, see the <i>Pia Programming Manual</i> for the Friend Presence library
451  and the <i>Pia API Reference</i> for the <tt>nn::fp::AddRecentPlayRecord()</tt> function.
452  @endif
453  @if CTR_DOC
454  Specify a language code if your application determines the languages of other regions. 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.
455  @endif
456 
457  You can configure the communication encryption feature in the <tt>pCryptoSetting</tt> member of the <tt>StartupSetting</tt> structure.
458  Communication is not encrypted if <tt>NULL</tt> is specified. The default is <tt>NULL</tt>.
459 
460  You can configure the packet-signing feature in the <tt>signatureSetting</tt> member of the <tt>StartupSetting</tt> structure.
461  The unsigned option is not allowed for Internet communication. The <tt>@ref Startup</tt> function fails if unsigned is specified.
462 
463  In the <tt>pToken</tt> member of the <tt>StartupSetting</tt> structure, you can set an identification token that indicates the local host.
464  This identification token is shared with peers during the connection process, and it is associated with and maintained in <tt>@ref nn::pia::transport::Station</tt>.
465  You are not required to specify an identification token if you do not need to use one. The default is <tt>NULL</tt>.
466 
467  The <tt>@ref Startup</tt> function is the only way to specify and change an identification token that indicates the local host.
468  Note that there is no supported method for changing an identification token while a mesh is in use.
469  @if CTR_DOC
470 
471  When local communications and host migration are enabled, host migration can begin after detecting a communication problem with the host on the local network.
472  Note that the time period used by the local network to determine communication problems is not related to the maximum allowed silence time in <tt>Session</tt>.
473  @endif
474 
475  If the bitrate detection feature is enabled, you must set the <tt>uplinkBitRateLowerLimit</tt> and <tt>bitRateCheckPacketSize</tt> members of the <tt>@ref StartupSetting</tt> structure.
476  Both members default to an invalid value. Set the minimum bitrate (in bits per second) required by the application in <tt>uplinkBitRateLowerLimit</tt> and the IP packet size (in bytes) to use for measurements in <tt>bitRateCheckPacketSize</tt>.
477 
478  @param[in] startupSetting Specifies the settings to use for startup.
479 
480  @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when already in startup or a similar state. Programming error. Fix your program so that this error is not returned.
481  @retval ResultInvalidArgument Indicates a problem with the name associated with the station, a problem with the configuration of the packet-signing feature, or that an invalid pointer was specified in one of the arguments. Programming error. Fix your program so that this error is not returned.
482 
483  @see Cleanup, transport::Station::GetIdentificationToken, RegisterJoiningMeshApprovalCallback
484 */
485  nn::Result Startup(Mesh::StartupSetting& startupSetting);
486 
487  /// @cond PRIVATE
488 /*!
489  @brief Starts the <tt>Mesh</tt>.
490 
491  @details Host migration is configured with the first argument. Set to <tt>true</tt> to enable.
492  Specify the name and language code associated with the local station in the second parameter. The name must be no longer than 16 characters (not including the terminating null character).
493  @if CAFE_DOC
494  Set the language code to the language used by the application. Use one of the values defined in <tt>nn::fp::Language</tt>.
495  The name and language code you specify are shared with all members of the mesh. When the local station joins a mesh, all mesh participants are added to Player History. When another
496  client joins the mesh, the new participant's name and language code are looked up and automatically
497  added to Player History using the <tt>nn::fp::AddRecentPlayRecord()</tt> function from within the library.
498  For more information about Player History, see the <i>Pia Programming Manual</i> for the Friend Presence library
499  and the <i>Pia API Reference</i> for the <tt>nn::fp::AddRecentPlayRecord()</tt> function.
500  @endif
501  @if CTR_DOC
502  Specify a language code if your application determines the languages of other regions. 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.
503  @endif
504 
505  You can configure the communication encryption feature in the third argument.
506  Communication is not encrypted if <tt>NULL</tt> is specified.
507 
508  You can configure the packet-signing feature in the fourth argument.
509  The unsigned option is not allowed for Internet communication. The <tt>@ref Startup</tt> function fails if unsigned is specified.
510 
511  In the fifth parameter, you can set an identification token that indicates the local host.
512  This identification token is shared with peers during the connection process, and it is associated with and maintained in <tt>@ref nn::pia::transport::Station</tt>.
513  You are not required to specify an identification token if you do not need to use one.
514 
515  The <tt>@ref Startup</tt> function is the only way to specify and change an identification token that indicates the local host.
516  Note that there is no supported method for changing an identification token while a mesh is in use.
517  @if CTR_DOC
518 
519  When local communications and host migration are enabled, host migration can begin after detecting a communication problem with the host on the local network.
520  Note that the time period used by the local network to determine communication problems is not related to the maximum allowed silence time in <tt>Session</tt>.
521  @endif
522 
523  @param[in] bUsingHostMigration Sets the use of the host migration feature.
524  @param[in] pPlayerName Specifies the name and language code associated with the local station. Other members of the mesh access this information.
525  @param[in] pCryptoSetting Specifies a pointer that points to a structure for configuring encryption. No encryption is configured if <tt>NULL</tt> is specified.
526  @param[in] signatureSetting Specifies a properly configured instance of the class used to specify packet-signature settings. The default value for this parameter is <tt>unsigned</tt>.
527  @param[in] pToken Specifies a pointer to the identification token indicating the local device. If <tt>NULL</tt> is specified, an identification token with all data set to <tt>NULL</tt> is used.
528  @return Returns the result of the function. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. You must make sure that the implementation of this function in your application does not return any errors.
529  If this function call fails, one or more of the following <tt>Result</tt> values is returned.
530  @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when already in startup or a similar state. Programming error. Fix your program so that this error is not returned.
531  @retval ResultInvalidArgument Indicates a problem with the name associated with the station, a problem with the configuration of the packet-signing feature, or that an invalid pointer was specified in one of the arguments. Programming error. Fix your program so that this error is not returned.
532 
533  @see Cleanup, transport::Station::GetIdentificationToken, RegisterJoiningMeshApprovalCallback
534 */
535  //nn::Result Startup(
536  // bool bUsingHostMigration,
537  // const nn::pia::transport::Station::PlayerName* pPlayerName,
538  // const nn::pia::common::CryptoSetting* pCryptoSetting,
539  // const nn::pia::common::SignatureSetting& signatureSetting = nn::pia::common::SignatureSetting::NO_SIGNATURE,
540  // const nn::pia::transport::Station::IdentificationToken* pToken = NULL);
541 
542 /*!
543  @brief Starts the <tt>Mesh</tt>.
544 
545  @details Specify the maximum allowable time without communication in the first argument. If the period without communication with the station exceeds the specified period, that station is treated as disconnected.
546  Specify the send interval for keep alive in the second argument. Keep alive is a feature that keeps connections alive during periods of no communication by having the system send data to stations the application is not sending data to.
547 
548  The default values for the first and second arguments are listed below. The following defaults are used if you call an overload without configuration arguments.
549  <ul>
550  <li>First argument: <tt><var>nn::pia::session::NN_PIA_SESSION_MAX_SILENCE_TIME_DEFAULT</var></tt></li>
551  <li>Second argument: <tt><var>nn::pia::session::NN_PIA_SESSION_KEEP_ALIVE_INTERVAL_DEFAULT</var></tt></li>
552  </ul>
553  If you customize these values, make sure to test the actual results as you adjust them.
554 
555  Host migration is configured with the third argument. Set to <tt>true</tt> to enable.
556 
557  Specify the name and language code associated with the local station in the fourth argument. The name must be no longer than 16 characters (not including the terminating null character).
558  @if CAFE_DOC
559  Set the language code to the language used by the application. Use one of the values defined in <tt>nn::fp::Language</tt>.
560  The name and language code you specify are shared with all members of the mesh. When the local station joins a mesh, all mesh participants are added to Player History. When another
561  client joins the mesh, the new participant's name and language code are looked up and automatically
562  added to Player History using the <tt>nn::fp::AddRecentPlayRecord()</tt> function from within the library.
563  For more information about Player History, see the <i>Pia Programming Manual</i> for the Friend Presence library
564  and the <i>Pia API Reference</i> for the <tt>nn::fp::AddRecentPlayRecord()</tt> function.
565  @endif
566  @if CTR_DOC
567  Specify a language code if your application determines the languages of other regions. 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.
568  @endif
569 
570  You can configure the communication encryption feature in the fifth argument.
571  Communication is not encrypted if <tt>NULL</tt> is specified.
572 
573  You can configure the packet-signing feature in the sixth argument.
574  The unsigned option is not allowed for Internet communication. The <tt>@ref Startup</tt> function fails if unsigned is specified.
575 
576  In the seventh argument, you can set an identification token that indicates the local host.
577  This identification token is shared with peers during the connection process, and it is associated with and maintained in <tt>@ref nn::pia::transport::Station</tt>.
578  You are not required to specify an identification token if you do not need to use one.
579 
580  The <tt>@ref Startup</tt> function is the only way to specify and change an identification token that indicates the local host.
581  Note that there is no supported method for changing an identification token while a mesh is in use.
582  @if CTR_DOC
583 
584  When local communications and host migration are enabled, host migration can begin after detecting a communication problem with the host on the local network.
585  Note that the time period used by the local network to determine communication problems is not related to the maximum allowed silence time in <tt>Session</tt>.
586  @endif
587 
588  @param[in] maxSilenceTime Specifies the maximum allowable time without communication (in milliseconds).
589  @param[in] keepAliveSendingInterval Specifies the send interval for keep-alive (in milliseconds).
590  @param[in] bUsingHostMigration Sets the use of the host migration feature.
591  @param[in] pPlayerName Specifies the name and language code associated with the local station. Other members of the mesh access this information.
592  @param[in] pCryptoSetting Specifies a pointer that points to a structure for configuring encryption. No encryption is configured if <tt>NULL</tt> is specified.
593  @param[in] signatureSetting Specifies a properly configured instance of the class used to specify packet-signature settings. The default value for this parameter is <tt>unsigned</tt>.
594  @param[in] pToken Specifies a pointer to the identification token indicating the local device. If <tt>NULL</tt> is specified, an identification token with all data set to <tt>NULL</tt> is used.
595  @return Returns the result of the function. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. You must make sure that the implementation of this function in your application does not return any errors.
596  If this function call fails, one or more of the following <tt>Result</tt> values is returned.
597  @retval ResultInvalidState Indicates that the function cannot be executed in this state. Returned when already in startup or a similar state. Programming error. Fix your program so that this error is not returned.
598  @retval ResultInvalidArgument Indicates a problem with the name associated with the station, a problem with the configuration of the packet-signing feature, or that an invalid pointer was specified in one of the arguments. Programming error. Fix your program so that this error is not returned.
599 
600  @see Cleanup, transport::Station::GetIdentificationToken, RegisterJoiningMeshApprovalCallback
601 */
602 // nn::Result Startup(
603 // u32 maxSilenceTime,
604 // u32 keepAliveSendingInterval,
605 // bool bUsingHostMigration,
606 // const nn::pia::transport::Station::PlayerName* pPlayerName,
607 // const nn::pia::common::CryptoSetting* pCryptoSetting,
608 // const nn::pia::common::SignatureSetting& signatureSetting = nn::pia::common::SignatureSetting::NO_SIGNATURE,
609 //#if NN_PIA_EXPERIMENT_BAND_WIDTH_CHECK
610 // s32 bandwidthLimit = NN_PIA_SESSION_INVALID_UPLINK_BIT_RATE_LOWER_LIMIT,
611 //#endif
612 // const nn::pia::transport::Station::IdentificationToken* pToken = NULL);
613  /// @endcond
614 
615 
616 /*!
617  @brief Cleans up the <tt>Mesh</tt>.
618 
619  @details Call <tt>@ref Startup</tt> again if you want to reuse the <tt>Mesh</tt> instance after you have called the <tt>@ref Cleanup</tt> function.
620  For Internet communication, call it again from the start of the NAT session (<tt>@ref nn::pia::inet::NexFacade::StartNatSessionAsync</tt>).
621 
622  @see Startup
623 */
624  void Cleanup();
625 
626 /*!
627  end of name Finish Initialization
628  @}
629 */
630 
631 /*!
632  @name Building, Destroying, Joining, and Leaving Meshes
633  @{
634 */
635 
636 /*!
637  @cond PRIVATE
638  @brief Builds a mesh. (Old specification.)
639 
640  @details The local device acts as the mesh host.
641 
642  Starts building a mesh asynchronously. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
643  You can monitor the completion of the process by checking the <tt>CallContext</tt> specified in the arguments.
644 
645  You must set up the <tt>@ref nn::pia::transport::Transport</tt> instance beforehand.
646 
647  <b>The following results may be returned by the <tt>CallContext</tt> instance if the asynchronous process fails.</b>
648  <ul>
649  <li> ResultInvalidState: This function is not in a usable state. Programming error. Fix your program so that this error is not returned.</li>
650  </ul>
651 
652  @param[in] pCallContext Specifies the <tt>CallContext</tt> pointer to check the execution progress status.
653 
654  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the local device successfully starts building a mesh. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
655  @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
656  @retval ResultInvalidArgument Indicates that the function cannot be called in the specified <tt>CallContext</tt>. Programming error. Fix your program so that this error is not returned.
657 
658  @see DestroyMesh, LeaveMeshWithHostMigration
659 */
660  nn::Result CreateMesh(nn::pia::common::CallContext* pCallContext);
661  //!@endcond
662 
663 /*!
664  @brief Builds a mesh.
665 
666  @details The local device acts as the mesh host.
667 
668  Starts building a mesh asynchronously. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
669  Use <tt>@ref IsCompletedCreateMesh</tt> to check whether the process has completed and <tt>@ref GetCreateMeshResult</tt> to check the result.
670 
671  You must set up the <tt>@ref nn::pia::transport::Transport</tt> instance beforehand.
672 
673  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the local device successfully starts building a mesh. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
674  @retval ResultInvalidState Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.
675 
676  @see IsCompletedCreateMesh, GetCreateMeshResult
677  @see DestroyMeshAsync, LeaveMeshWithHostMigrationAsync
678 */
679  nn::Result CreateMeshAsync();
680 
681 /*!
682  @brief Checks the completion of <tt>CreateMeshAsync</tt> asynchronous processing.
683 
684  @details This function checks the completion of asynchronous processes started with <tt>@ref CreateMeshAsync</tt>.
685 
686  @return Returns <tt>true</tt> if the asynchronous process has completed, or <tt>false</tt> otherwise. Also returns <tt>false</tt> when there has been no asynchronous processing.
687 
688  @see CreateMeshAsync, GetCreateMeshResult
689 */
690  bool IsCompletedCreateMesh();
691 
692 /*!
693  @brief Gets the result of <tt>CreateMeshAsync</tt> asynchronous processing.
694 
695  @details This function gets the results after an asynchronous process started by <tt>@ref CreateMeshAsync</tt> ends.
696 
697  @return Returns the result of <tt>CreateMeshAsync</tt> asynchronous processing. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
698  @retval ResultInvalidState Returned when <tt>CreateMeshAsync</tt> is called at the wrong time. This result is also returned when the asynchronous process has not completed or has not started. Programming error. Fix your program so that this error is not returned.
699 
700  @see CreateMeshAsync, IsCompletedCreateMesh
701 */
702  nn::Result GetCreateMeshResult();
703 
704 
705 /*!
706  @cond PRIVATE
707  @brief Destroys a mesh. (Old specification.)
708 
709  @details Only the mesh host can call this function.
710 
711  Starts an asynchronous mesh destruction process. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
712  You can monitor the completion of the process by checking the <tt>CallContext</tt> specified in the arguments.
713  <b>Note:</b> If the mesh destruction process starts normally, the asynchronous process does not fail.
714 
715  Within the <tt>Mesh</tt> destruction process, all participants are notified that the <tt>Mesh</tt> will be ended.
716  For stations that receive the notification, the internal state of their mesh is initialized and becomes <tt>STATE_DISCONNECTED</tt>.
717 
718  @param[in] pCallContext Specifies the <tt>CallContext</tt> pointer to check the execution progress status.
719 
720  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the mesh is successfully destroyed. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
721  @retval ResultInvalidState Indicates that a node other than the mesh host called the function. Programming error. Fix your program so that this error is not returned.
722  @retval ResultInvalidArgument Indicates that the function cannot be called in the specified <tt>CallContext</tt>. Programming error. Fix your program so that this error is not returned.
723 
724  @see CreateMesh, LeaveMeshWithHostMigration
725 */
726  nn::Result DestroyMesh(nn::pia::common::CallContext* pCallContext);
727  //!@endcond
728 
729 /*!
730  @brief Destroys a mesh.
731 
732  @details Only the mesh host can call this function.
733 
734  Starts an asynchronous mesh destruction process. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
735  Use <tt>@ref IsCompletedDestroyMesh</tt> to check whether the process has completed and <tt>@ref GetDestroyMeshResult</tt> to check the result.
736  <b>Note:</b> If the mesh destruction process starts normally, the asynchronous process does not fail.
737 
738  Within the <tt>Mesh</tt> destruction process, all participants are notified that the <tt>Mesh</tt> will be ended.
739  For stations that receive the notification, the internal state of their mesh is initialized and becomes <tt>STATE_DISCONNECTED</tt>.
740 
741  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the mesh is successfully destroyed. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
742  @retval ResultInvalidState Returned when called by a station other than the mesh host or when another asynchronous process has already started. Programming error. Fix your program so that this error is not returned.
743 
744  @see IsCompletedDestroyMesh, GetDestroyMeshResult
745  @see CreateMeshAsync, LeaveMeshWithHostMigrationAsync
746 */
747  nn::Result DestroyMeshAsync();
748 
749 /*!
750  @brief Checks the completion of <tt>DestroyMeshAsync</tt> asynchronous processing.
751 
752  @details This function checks the completion of asynchronous processes started with <tt>@ref DestroyMeshAsync</tt>.
753 
754  @return Returns <tt>true</tt> if the asynchronous process has completed, or <tt>false</tt> otherwise. Also returns <tt>false</tt> when there has been no asynchronous processing.
755 
756  @see DestroyMeshAsync, GetDestroyMeshResult
757 */
758  bool IsCompletedDestroyMesh();
759 
760 /*!
761  @brief Gets the result of <tt>DestroyMeshAsync</tt> asynchronous processing.
762 
763  @details This function gets the results after an asynchronous process started by <tt>@ref DestroyMeshAsync</tt> ends.
764  <b>Note:</b> If the mesh destruction process starts normally, the asynchronous process does not fail.
765 
766  @return Returns the result of <tt>DestroyMeshAsync</tt> asynchronous processing. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
767  @retval ResultInvalidState Returned when the asynchronous process has not completed or has not started. Programming error. Fix your program so that this error is not returned.
768 
769  @see DestroyMeshAsync, IsCompletedDestroyMesh
770 */
771  nn::Result GetDestroyMeshResult();
772 
773 
774 /*!
775  @cond PRIVATE
776  @brief Leaves a mesh. Also specifies that host migration will start for mesh participants. (Old specification.)
777 
778  @details Only the mesh host can call this function. This function can be used only when the host migration feature is enabled.
779 
780  Starts an asynchronous mesh leaving process. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
781  You can monitor the completion of the process by checking the <tt>CallContext</tt> specified in the arguments.
782  <b>Note:</b> The asynchronous process never fails if the leave mesh process starts normally.
783 
784  All session participants are notified that host migration has started within the asynchronous process.
785  The host migration process begins on the stations that received the notification, and the mesh continues
786  under the new mesh host even after communication is terminated with the old mesh host that called this function.
787 
788  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the mesh is successfully left. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
789  @retval ResultInvalidState Indicates that a node other than the mesh host called this function, or that host migration is disabled. Programming error. Fix your program so that this error is not returned.
790  @retval ResultInvalidArgument Indicates that the function cannot be called in the specified <tt>CallContext</tt>. Programming error. Fix your program so that this error is not returned.
791 
792  @see CreateMesh, DestroyMesh
793 */
794  nn::Result LeaveMeshWithHostMigration(nn::pia::common::CallContext* pCallContext);
795  //!@endcond
796 
797 /*!
798  @brief Leaves a mesh. Also specifies that host migration will start for mesh participants.
799 
800  @details Only the mesh host can call this function. This function can be used only when the host migration feature is enabled.
801 
802  Starts an asynchronous mesh leaving process. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
803  Use <tt>@ref IsCompletedLeaveMeshWithHostMigration</tt> to check whether the process has completed and <tt>@ref GetLeaveMeshWithHostMigrationResult</tt> to check the result.
804  <b>Note:</b> The asynchronous process never fails if the leave mesh process starts normally.
805 
806  All session participants are notified that host migration has started within the asynchronous process.
807  The host migration process begins on the stations that received the notification, and the mesh continues
808  under the new mesh host even after communication is terminated with the old mesh host that called this function.
809 
810  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the mesh is successfully left. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
811  @retval ResultInvalidState Returned when called by a station other than the mesh host, when the host migration feature is disabled, or when another asynchronous process has already started. Programming error. Fix your program so that this error is not returned.
812 
813  @see IsCompletedLeaveMeshWithHostMigration, GetLeaveMeshWithHostMigrationResult
814  @see CreateMeshAsync, DestroyMeshAsync
815 */
816  nn::Result LeaveMeshWithHostMigrationAsync();
817 
818 /*!
819  @brief Checks the completion of <tt>LeaveMeshWithHostMigrationAsync</tt> asynchronous processing.
820 
821  @details This function checks the completion of asynchronous processes started with <tt>@ref LeaveMeshWithHostMigrationAsync</tt>.
822 
823  @return Returns <tt>true</tt> if the asynchronous process has completed, or <tt>false</tt> otherwise. Also returns <tt>false</tt> when there has been no asynchronous processing.
824 
825  @see LeaveMeshWithHostMigrationAsync, GetLeaveMeshWithHostMigrationResult
826 */
827  bool IsCompletedLeaveMeshWithHostMigration();
828 
829 /*!
830  @brief Gets the result of <tt>LeaveMeshWithHostMigrationAsync</tt> asynchronous processing.
831 
832  @details This function gets the results after an asynchronous process started by <tt>@ref LeaveMeshWithHostMigrationAsync</tt> ends.
833  <b>Note:</b> If the mesh destruction process starts normally, the asynchronous process does not fail.
834 
835  @return Returns the result of <tt>LeaveMeshWithHostMigrationAsync</tt> asynchronous processing. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
836  @retval ResultInvalidState Returned when the asynchronous process has not completed or has not started. Programming error. Fix your program so that this error is not returned.
837 
838  @see LeaveMeshWithHostMigrationAsync, IsCompletedLeaveMeshWithHostMigration
839 */
840  nn::Result GetLeaveMeshWithHostMigrationResult();
841 
842 
843  /// @cond PRIVATE
844 /*!
845  @brief Specifies whether join requests are allowed.
846 
847  @return Returns <tt>0xFF</tt> if join requests are allowed or another value if they are denied.
848 */
849  u8 CheckApprovalJoin(transport::Station* pTargetStation);
850  /// @endcond
851 
852 
853 /*!
854  @cond PRIVATE
855  @brief Joins a mesh. (Old specification.)
856 
857  @details This function starts an asynchronous processing required to join the mesh. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
858  You can monitor the completion and success or failure of the process by checking the <tt>CallContext</tt> specified in the second argument.
859  You can also cancel the process by calling the <tt>@ref nn::pia::common::CallContext::Cancel</tt> function during the process.
860 
861  <b>The following results may be returned by the <tt>CallContext</tt> instance when the asynchronous process ends.</b>
862  <ul>
863  <li> <tt>ResultSuccess</tt>: The asynchronous process succeeded.</li>
864  <li> <tt>ResultCancelled</tt>: The asynchronous process was canceled. Perform cleanup.</li>
865  <li> <tt>ResultInvalidState</tt>: Connection is not available in this state. Programming error. Fix your program so that this error is not returned.</li>
866  <li> <tt>ResultStationConnectionFailed</tt>: The connection failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.</li>
867  <li> <tt>ResultStationConnectionNatTraversalFailedUnknown</tt>: NAT traversal connection failed. The NAT type is unknown. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.</li>
868  <li> <tt>ResultNatTraversalFailedBothEim</tt>: NAT traversal connection failed. The NAT type was EIM for both the local station and the peer to which the connection failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.</li>
869  <li> <tt>ResultNatTraversalFailedLocalEimRemoteEdm</tt>: NAT traversal connection failed. The NAT type was EIM for the local station and EDM for the peer to which the connection failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.</li>
870  <li> <tt>ResultNatTraversalFailedLocalEdmRemoteEim</tt>: NAT traversal connection failed. The NAT type was EDM for the local station and EIM for the peer to which the connection failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.</li>
871  <li> <tt>ResultNatTraversalFailedBothEdm</tt>: NAT traversal connection failed. The NAT type was EDM for both the local station and the peer to which the connection failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.</li>
872  <li> <tt>ResultNatTraversalRequestTimeout</tt>: NAT traversal connection failed. The NAT traversal request timed out. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.</li>
873  <li> <tt>ResultJoinRequestDenied</tt>: The mesh host denied the connection request. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.</li>
874  <li> <tt>ResultMeshIsFull</tt>: Failed to join the mesh because it was full. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.</li>
875  <li> <tt>ResultRelayFailedNoCandidate</tt>: The relay connection failed because there were no relay route candidates. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.</li>
876  <li> <tt>ResultRelayFailedRttLimit</tt>: The relay connection failed because the relay route RTT limit was exceeded. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.</li>
877  <li> <tt>ResultRelayFailedRelayNumLimit</tt>: The relay connection failed because the limit on the number of relay route relay requests was exceeded. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.</li>
878  <li> <tt>ResultRelayFailedUnknown</tt>: The relay connection failed. (Details unknown.) Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.</li>
879  <li> <tt>ResultInvalidSystemMessage</tt>: The process was canceled because an invalid response was received from the mesh host. Programming error. Fix your program so that this error is not returned.</li>
880  <li> <tt>ResultIncompatibleFormat</tt>: Specifies that the peer is using an incompatible communication method. Returned when you try to communicate with a ROM that uses a different version of Pia that does not have communication compatibility. Programming error. Fix your program so that this error is not returned.</li>
881  </ul>
882 
883  If you execute other processes without destroying the <tt>Mesh</tt> instance after execution fails, or if you cancel execution using the
884  <tt>@ref nn::pia::common::CallContext::Cancel</tt> function, do so after you first clean up <tt>Mesh</tt> by calling <tt>@ref Cleanup</tt>.
885  For Internet communication, call it again from the start of the NAT session (<tt>@ref nn::pia::inet::NexFacade::StartNatSession</tt>).
886 
887  @param[in] stationConnectionInfo Specifies information for connecting to the host of the mesh being joined.
888  @param[in] pCallContext Specifies the <tt>CallContext</tt> pointer to check the execution progress status.
889 
890  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the station successfully joins the mesh. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
891  @retval ResultInvalidArgument Indicates that the <tt>CallContext</tt> specified in the arguments was not in a usable state. Programming error. Fix your program so that this error is not returned.
892  @retval ResultInvalidState The mesh has already been joined, or the <tt>JoinMesh</tt> asynchronous process already started. Programming error. Fix your program so that this error is not returned.
893 
894  @see LeaveMesh
895 */
896  nn::Result JoinMesh(
897  const nn::pia::transport::StationConnectionInfo& stationConnectionInfo,
898  nn::pia::common::CallContext* pCallContext);
899  //!@endcond
900 
901 /*!
902  @brief Joins a mesh.
903 
904  @details This function starts an asynchronous processing required to join the mesh. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
905  Use <tt>@ref IsCompletedJoinMesh</tt> to check whether the process has completed and <tt>@ref GetJoinMeshResult</tt> to check the result.
906  You can also cancel the process by calling the <tt>@ref CancelJoinMeshAsync</tt> function during the process.
907 
908  If you execute other processes without destroying the <tt>Mesh</tt> instance after execution fails, or if you cancel execution using the
909  <tt>@ref CancelJoinMeshAsync</tt> function, do so after you first clean up <tt>Mesh</tt> by calling <tt>@ref Cleanup</tt>.
910  For Internet communication, call it again from the start of the NAT session (<tt>@ref nn::pia::inet::NexFacade::StartNatSessionAsync</tt>).
911 
912  @param[in] stationConnectionInfo Specifies information for connecting to the host of the mesh being joined.
913 
914  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the station successfully joins the mesh. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
915  @retval ResultInvalidState Indicates that the mesh has already been joined or another asynchronous process has already been started. Programming error. Fix your program so that this error is not returned.
916 
917  @see IsCompletedJoinMesh, GetJoinMeshResult, CancelJoinMeshAsync
918  @see LeaveMeshAsync
919 */
920  nn::Result JoinMeshAsync(const nn::pia::transport::StationConnectionInfo& stationConnectionInfo);
921 
922 /*!
923  @brief Checks the completion of <tt>JoinMeshAsync</tt> asynchronous processing.
924 
925  @details This function checks the completion of asynchronous processes started with <tt>@ref JoinMeshAsync</tt>.
926 
927  @return Returns <tt>true</tt> if the asynchronous process has completed, or <tt>false</tt> otherwise. Also returns <tt>false</tt> when there has been no asynchronous processing.
928 
929  @see JoinMeshAsync, GetJoinMeshResult, CancelJoinMeshAsync
930 */
931  bool IsCompletedJoinMesh();
932 
933 /*!
934  @brief Gets the result of <tt>JoinMeshAsync</tt> asynchronous processing.
935 
936  @details This function gets the results after an asynchronous process started by <tt>@ref JoinMeshAsync</tt> ends.
937 
938  @return Returns the result of <tt>JoinMeshAsync</tt> asynchronous processing. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
939  @retval ResultCancelled The asynchronous process was canceled. Perform cleanup.
940  @retval ResultInvalidState Returned when the station is not in a connection-ready state. This result is also returned when the asynchronous process has not completed or has not started. Programming error. Fix your program so that this error is not returned.
941  @retval ResultStationConnectionFailed The connection process failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.
942  @retval ResultStationConnectionNatTraversalFailedUnknown The NAT traversal connection process failed. The NAT type is unknown. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.
943  @retval ResultNatTraversalFailedBothEim The NAT traversal connection process failed. The NAT type was EIM for both the local station and the peer to which the connection failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.
944  @retval ResultNatTraversalFailedLocalEimRemoteEdm The NAT traversal connection process failed. The NAT type was EIM for the local station and EDM for the peer to which the connection failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.
945  @retval ResultNatTraversalFailedLocalEdmRemoteEim The NAT traversal connection process failed. The NAT type was EDM for the local station and EIM for the peer to which the connection failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.
946  @retval ResultNatTraversalFailedBothEdm The NAT traversal connection process failed. The NAT type was EDM for both the local station and the peer to which the connection failed. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.
947  @retval ResultNatTraversalRequestTimeout The NAT traversal connection process failed. The NAT traversal request timed out. If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors. Perform cleanup.
948  @retval ResultJoinRequestDenied The mesh host denied the connection request. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.
949  @retval ResultMeshIsFull Failed to join the mesh because it was full. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.
950  @retval ResultRelayFailedNoCandidate The relay connection failed because there were no relay route candidates. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.
951  @retval ResultRelayFailedRttLimit The relay connection failed because the relay route RTT limit was exceeded. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.
952  @retval ResultRelayFailedRelayNumLimit The relay connection failed because the limit on the number of relay route relay requests was exceeded. Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.
953  @retval ResultRelayFailedUnknown The relay connection failed. (Details unknown.) Perform cleanup. Handle appropriately in the application. When an error occurs in Internet communication, If this error occurs during Internet communication, convert to a network error code and display in the error viewer applet/EULA applet. However, during local communication, do not display it as an error with error code in the error viewer applet/EULA applet. Do not use the error/EULA applet (CTR) for local communication errors.
954  @retval ResultInvalidSystemMessage The process was canceled because an invalid response was received from the mesh host. Programming error. Fix your program so that this error is not returned.
955  @retval ResultIncompatibleFormat Indicates that the peer is using an incompatible communication format. Returned when you try to communicate with a ROM that uses a different version of Pia that does not have communication compatibility. Programming error. Fix your program so that this error is not returned.
956 
957  @see JoinMeshAsync, IsCompletedJoinMesh, CancelJoinMeshAsync
958 */
959  nn::Result GetJoinMeshResult();
960 
961 /*!
962  @brief Cancels <tt>JoinMeshAsync</tt> asynchronous processes.
963 
964  @details This function cancels asynchronous processes started by <tt>JoinMeshAsync</tt>.
965  The cancel process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
966  The library quickly acts to cancel the asynchronous process after this function is called, but check
967  using the <tt>@ref IsCompletedJoinMesh()</tt> function that the cancellation has completed.
968 
969  @return Returns the result of canceling <tt>JoinMeshAsync</tt> asynchronous processing. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
970  @retval ResultInvalidState Returned when no <tt>JoinMeshAsync</tt> asynchronous processing is being performed. Programming error. Fix your program so that this error is not returned.
971 
972  @see JoinMeshAsync, IsCompletedJoinMesh, GetJoinMeshResult
973 */
974  nn::Result CancelJoinMeshAsync();
975 
976 
977 /*!
978  @cond PRIVATE
979  @brief Leaves a joined mesh. (Old specification.)
980 
981  @details Only the mesh clients can call this function.
982 
983  Starts an asynchronous process to leave the mesh. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
984  You can monitor the completion and success or failure of the process by checking the <tt>CallContext</tt> function specified in the arguments.
985 
986  @param[in] pCallContext Specifies the <tt>CallContext</tt> pointer to check the execution progress status.
987 
988  @return Returns a <tt>Result</tt> value indicating success if the station successfully starts the process for leaving the mesh.
989  @retval ResultInvalidState Indicates that a mesh host called this function. Programming error. Fix your program so that this error is not returned.
990  @retval ResultInvalidArgument Indicates that the function cannot be called in the specified <tt>CallContext</tt>. Programming error. Fix your program so that this error is not returned.
991 
992  @see JoinMesh
993 */
994  nn::Result LeaveMesh(nn::pia::common::CallContext* pCallContext);
995  //!@endcond
996 
997 /*!
998  @brief Leaves a joined mesh.
999 
1000  @details Only the mesh clients can call this function.
1001 
1002  Starts an asynchronous process to leave the mesh. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
1003  Use <tt>@ref IsCompletedJoinMesh</tt> to check whether the process has completed and <tt>@ref GetJoinMeshResult</tt> to check the result.
1004  <b>Note:</b> The asynchronous process never fails if the leave mesh process starts normally.
1005 
1006  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the mesh is successfully left. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
1007  @retval ResultInvalidState Returned when called by the mesh host or when another asynchronous process has already started. Programming error. Fix your program so that this error is not returned.
1008 
1009  @see IsCompletedLeaveMesh, GetLeaveMeshResult
1010  @see JoinMeshAsync
1011 */
1012  nn::Result LeaveMeshAsync();
1013 
1014 /*!
1015  @brief Checks the completion of <tt>LeaveMeshAsync</tt> asynchronous processing.
1016 
1017  @details This function checks the completion of asynchronous processes started with <tt>@ref LeaveMeshAsync</tt>.
1018 
1019  @return Returns <tt>true</tt> if the asynchronous process has completed, or <tt>false</tt> otherwise. Also returns <tt>false</tt> when there has been no asynchronous processing.
1020 
1021  @see LeaveMeshAsync, GetLeaveMeshResult
1022 */
1023  bool IsCompletedLeaveMesh();
1024 
1025 /*!
1026  @brief Gets the result of <tt>LeaveMeshAsync</tt> asynchronous processing.
1027 
1028  @details This function gets the results after an asynchronous process started by <tt>@ref LeaveMeshAsync</tt> ends.
1029  <b>Note:</b> If the mesh destruction process starts normally, the asynchronous process does not fail.
1030 
1031  @return Returns the result of <tt>LeaveMeshAsync</tt> asynchronous processing. On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt>. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
1032  @retval ResultInvalidState Returned when the asynchronous process has not completed or has not started. Programming error. Fix your program so that this error is not returned.
1033 
1034  @see LeaveMeshAsync, IsCompletedLeaveMesh
1035 */
1036  nn::Result GetLeaveMeshResult();
1037 
1038 
1039 /*!
1040  @brief Kicks a station from the mesh.
1041 
1042  @details Only the mesh host can call this function.
1043 
1044  A kick notice is conveyed to the station assigned the <tt>StationId</tt> specified in
1045  the argument, and that station leaves the mesh upon receiving the notice.
1046 
1047  Because of latency in transmitting the disconnect notification and other factors, there may be a delay between successfully calling this function, and the station leaving the mesh.
1048 
1049  @param[in] id Specifies the station ID assigned to the station being kicked.
1050 
1051  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the station is successfully kicked from the mesh. If this function call fails, one or more of the following <tt>Result</tt> values is returned.
1052  @retval ResultInvalidState Indicates that a node other than the mesh host called the function. Programming error. Fix your program so that this error is not returned.
1053  @retval ResultInvalidArgument Indicates that the <tt>StationId</tt> specified in the arguments belongs to the mesh host, or that no station in the mesh has that ID. Programming error. Fix your program so that this error is not returned.
1054  @retval ResultInProgress Indicates that the process to kick the station having the <tt>StationId</tt> specified in the arguments has already started. Handle appropriately in the application.
1055  @retval ResultBufferIsFull Indicates that the buffer for kicking stations or the buffer for sending kick notifications is full. It may succeed if you try again after some time has passed. Handle appropriately in the application.
1056 */
1057  nn::Result KickoutStation(nn::pia::StationId id);
1058 
1059  /// @cond PRIVATE
1060  nn::Result KickoutStationByIndex(nn::pia::StationIndex index);
1061  /// @endcond
1062 
1063 /*!
1064  end of name Building, Destroying, Joining, and Leaving Meshes
1065  @}
1066 */
1067 
1068 /*!
1069  @name Mesh Analysis
1070  @{
1071 */
1072 
1073 /*!
1074  @brief Gets the number of valid stations connected to the current mesh.
1075 
1076  @return Returns the number of connected stations.
1077 */
1078  u16 GetStationNum() const
1079  {
1080  return m_StationCount;
1081  }
1082 
1083 
1084 /*!
1085  @brief Gets the <tt>StationId</tt> of the mesh host.
1086 
1087  @details This function returns <tt>STATION_ID_INVALID</tt> if a mesh host has not been established.
1088 
1089  @return Returns the <tt>StationId</tt> representing the mesh host.
1090 */
1091  nn::pia::StationId GetHostStationId() const;
1092 
1093 
1094 /*!
1095  @brief Gets the <tt>StationId</tt> that specifies the local device.
1096 
1097  @details This function returns <tt>STATION_ID_INVALID</tt> if the local device's <tt>StationId</tt> has not been established.
1098 
1099  @return Returns the <tt>StationId</tt> representing the local station.
1100 */
1101  nn::pia::StationId GetLocalStationId() const;
1102 
1103 
1104  /// @cond PRIVATE
1105  nn::pia::StationIndex GetHostStationIndex() const
1106  {
1107  return m_HostStationIndex;
1108  }
1109 
1110  nn::pia::StationIndex GetLocalStationIndex() const
1111  {
1112  return m_LocalStationIndex;
1113  }
1114  /// @endcond
1115 
1116 
1117 /*!
1118  @brief Gets whether the local device is the mesh host.
1119 
1120  @details This function always returns <tt>false</tt> if the local device is not joined in a mesh.
1121 
1122  @return Returns <tt>true</tt> if the local device is the mesh host, or <tt>false</tt> otherwise.
1123 */
1124  bool IsHost() const
1125  {
1126  if (m_LocalStationIndex > STATION_INDEX_MAX)
1127  {
1128  return false;
1129  }
1130  return m_LocalStationIndex == m_HostStationIndex;
1131  }
1132 
1133 
1134 /*!
1135  @brief Checks whether an arbitrary <tt>StationId</tt> within the mesh is currently valid.
1136 
1137  @param[in] id Specifies the <tt>StationId</tt> being checked.
1138 
1139  @return Returns <tt>true</tt> if the specified <tt>StationId</tt> is valid, or <tt>false</tt> otherwise.
1140 */
1141  bool CheckStationIdIsValid(nn::pia::StationId id) const;
1142 
1143 
1144  /// @cond PRIVATE
1145  bool CheckStationIndexIsValid(nn::pia::StationIndex index) const;
1146 
1147 /*!
1148  @brief Gets a <tt>StationIndex</tt> that is currently not used in the mesh.
1149 
1150  @return Returns <tt>STATION_INDEX_INVALID</tt> if there are no valid unused <tt>StationIndex</tt> values.
1151 */
1152  nn::pia::StationIndex GetUsableStationIndex();
1153 
1154 
1155 /*!
1156  @brief Gets a bitmap indicating the currently valid station indexes in the mesh.
1157 
1158  @details <tt>StationIndex</tt> values are obtained by shifting bits. <tt>STATION_INDEX_1</tt> is <tt>0x00000001</tt>, <tt>STATION_INDEX_2</tt> is <tt>0x00000002</tt>, and so on.
1159 
1160  @return Returns a bitmap corresponding to the <tt>StationIndex</tt> instances that are currently active in the session.
1161 */
1162  bit32 GetValidStationIndexBitmap() const
1163  {
1164  return m_StationIndexUsedFlags;
1165  };
1166  /// @endcond
1167 
1168 /*!
1169  @brief Confirms whether the state of the current <tt>Mesh</tt> is communicable.
1170 
1171  @details Indicates in the <tt>Result</tt> whether the current <tt>Mesh</tt> is in a communicable state. When not in a communicable state, use <tt>@ref GetDisconnectReason</tt> to check, in detail, the reasons for entering that state.
1172 
1173  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if communication is possible. Otherwise, one of the following <tt>Result</tt> values is returned.
1174  @retval ResultMeshConnectionIsLost The <tt>Mesh</tt> is in an incommunicable state. Perform cleanup.
1175 
1176  @see GetDisconnectReason
1177 */
1178  nn::Result CheckConnectionError() const;
1179 
1180 
1181 /*!
1182  @brief Gets the reason why the <tt>Mesh</tt> object was disconnected.
1183 
1184  @details This function always returns <tt>UNKNOWN_REASON</tt> if the <tt>Mesh</tt> object is in a communicable state.
1185 
1186  @return Returns a <tt>DisconnectReason</tt> value indicating the reason why <tt>Mesh</tt> disconnected.
1187 
1188  @see CheckConnectionError
1189 */
1190  DisconnectReason GetDisconnectReason() const;
1191 
1192 /*!
1193  @brief Determines whether the bitrate value may be found using the bitrate detection feature.
1194 
1195  @return Returns <tt>true</tt> if the bitrate value can be obtained. <tt>true</tt> is also returned when detection fails on a timeout, or cancel.
1196 */
1197  bool IsCompleteBitRateCheck();
1198 
1199 /*!
1200  @brief Gets the uplink bitrate of the connection measured by the bitrate detection feature.
1201 
1202  @details Note that the value returned by this function is simply a measurement of the amount of data received over a set
1203  amount of time and does not necessarily represent the actual bandwidth of the connection.
1204  Even if the connection is capable of a high bitrate, if an application has
1205  low requirements, the amount of data sent and received during the measurement
1206  process is also small, which results in a lower bits-per-second value.
1207 
1208  @param[out] pBps Stores the measured bitrate. The value is in bits per second. A negative value is set if the bitrate could not be measured.
1209 
1210  @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if the call succeeds.
1211 
1212  @retval ResultNotInitialized Indicates that the instance has not been initialized. Programming error. Fix your program so that this error is not returned.
1213  @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
1214  @retval ResultInvalidState Indicates that the function was called at the wrong time. It is possible that the function was called while the bitrate detection feature was disabled. Programming error. Fix your program so that this error is not returned.
1215 */
1216  nn::Result GetUplinkBitRate(s32* pBps);
1217 
1218 /*!
1219  end of name Mesh Analysis
1220  @}
1221 */
1222 
1223 /*!
1224  @name Registering and Unregistering Callback Functions
1225  @{
1226 */
1227 
1228 /*!
1229  @brief Registers the callback function that is called when the mesh state changes.
1230 
1231  @details This function registers the callback that is called when the session mesh changes (when a station joins or exits).
1232 
1233  The mesh state change callback function is generally called by the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
1234  As an exception, it can also be called when the <tt>@ref CreateMeshAsync</tt> and <tt>@ref DestroyMeshAsync</tt> functions are called. It can also be called when the <tt>@ref Cleanup</tt> function is called.
1235 
1236  Do not include any processes that block for long periods of time in the registering function.
1237  In addition, do not call <tt>session</tt> module functions within the function that you are registering.
1238 
1239  @param[in] callback Specifies a pointer to the callback function being registered.
1240 
1241  @see UnregisterMeshEventCallback
1242 */
1243  void RegisterMeshEventCallback(MeshEventCallback callback);
1244 
1245 
1246 /*!
1247  @brief Unregisters the registered callback function for mesh state changes.
1248 
1249  @see RegisterMeshEventCallback
1250 */
1251  void UnregisterMeshEventCallback();
1252 
1253 
1254 /*!
1255  @brief Registers the callback used to approve or deny requests received by the host from clients seeking to join the mesh.
1256 
1257  @details The callback function for deciding whether to approve <tt>Join</tt> requests is called by the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
1258 
1259  Do not include any processes that block for long periods of time in the registering function.
1260 
1261  The ID token of the station that sent the <tt>Join</tt> request is passed as an argument to the callback function.
1262 
1263  If you do not register a callback function, <tt>Join</tt> requests are always approved unless the mesh is full.
1264 
1265  @param[in] callback Specifies a pointer to the callback function being registered.
1266 
1267  @see Startup, UnregisterJoiningMeshApprovalCallback
1268 */
1269  void RegisterJoiningMeshApprovalCallback(JoiningMeshApprovalCallback callback);
1270 
1271 
1272 /*!
1273  @brief Unregisters the registered <tt>Join</tt> request callback function for approving or denying the request.
1274 
1275  @see RegisterJoiningMeshApprovalCallback
1276 */
1277  void UnregisterJoiningMeshApprovalCallback();
1278 
1279 
1280  /// @cond PRIVATE
1281 /*!
1282  @brief Registers the callback function for adjusting to any secondary host candidate position when using multiple candidate host migration.
1283 
1284  @details The callback function for adjusting to any secondary host candidate position is called by the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function.
1285 
1286  Do not include any processes that block for long periods of time in the registering function.
1287 
1288  @param[in] callback Specifies a pointer to the callback function being registered.
1289  @return If it was possible to call this function while multiple candidate host migration was enabled, the <tt>IsSuccess</tt> function returns a <tt>Result</tt> value of <tt>true</tt>.
1290 
1291  @see UnregisterCheckHostCandidateRankingCallback
1292 */
1293  nn::Result RegisterCheckHostCandidateRankingCallback(CheckHostCandidateRankingCallback callback);
1294 
1295 
1296 /*!
1297  @brief Unregisters the callback function registered for adjusting to any secondary host candidate position.
1298 
1299  @see RegisterCheckHostCandidateRankingCallback
1300 */
1301  void UnregisterCheckHostCandidateRankingCallback();
1302  /// @endcond
1303 
1304 
1305  /// @cond PRIVATE
1306  void RegisterEventListener(MeshEventListener* pEventListener);
1307  void UnregisterEventListener();
1308 
1309  void RegisterGetSessionIdCallback(GetSessionIdCallback callback);
1310  void UnregisterGetSessionIdCallback();
1311  /// @endcond
1312 
1313 
1314 /*!
1315  end of name Registering and Unregistering Callback Functions
1316  @}
1317 */
1318 
1319 
1320  /// @cond PRIVATE
1321 /*!
1322  @brief Gets the <tt>MeshProtocol</tt> object generated automatically by the system.
1323 
1324  @return Returns a pointer to a <tt>MeshProtocol</tt> instance.
1325 */
1326  MeshProtocol* GetMeshProtocol()
1327  {
1328  return m_pMeshProtocol;
1329  }
1330  /// @endcond
1331 
1332  /// @cond PRIVATE
1333 /*!
1334  @brief Gets the <tt>StationProtocol</tt> object generated automatically by the system.
1335 
1336  @return Returns a pointer to a <tt>StationProtocol</tt> instance.
1337 */
1338  nn::pia::transport::StationProtocol* GetStationProtocol()
1339  {
1340  return m_pStationProtocol;
1341  }
1342  /// @endcond
1343 
1344 
1345 /*!
1346  @name Synchronous Clock
1347  @{
1348 */
1349 
1350 /*!
1351  @brief Specifies the synchronous clock (the time, in milliseconds, since the mesh was created).
1352 
1353  @details The synchronous clock is synchronized among all the stations in the mesh.
1354  Clients joined in the mesh periodically send a clock-synchronization pulse to the mesh host.
1355  The host then responds to these pulses, ensuring synchronization between the host and clients.
1356  By default, synchronization pulses are sent every two seconds,
1357  but the application can also change this interval. For more information, see <tt>SetSyncClockPulseInterval()</tt> and
1358  <tt>GetSyncClockPulseInterval()</tt>.
1359 
1360  @return Returns the elapsed time, in milliseconds, since the mesh was created. A negative value is returned when a mesh client out of synchronization
1361  with the mesh host calls this function.
1362  @see SetSyncClockPulseInterval, GetSyncClockPulseInterval
1363 */
1364  s64 GetTime(void) const;
1365 
1366 
1367 /*!
1368  @brief Specifies the send interval of the synchronization pulse for the synchronous clock.
1369 
1370  @param[in] interval Specifies the interval at which the synchronization pulse is sent. The value is in milliseconds.
1371  @see GetTime, GetSyncClockPulseInterval
1372 */
1373  void SetSyncClockPulseInterval(s32 interval);
1374 
1375 
1376 /*!
1377  @brief Gets the send interval of the synchronization pulse for the synchronous clock.
1378 
1379  @return Returns the interval at which synchronization pulses are sent. The value is in milliseconds.
1380  @see GetTime, SetSyncClockPulseInterval
1381 */
1382  s32 GetSyncClockPulseInterval(void) const;
1383 
1384 /*!
1385  end of name Synchronous Clock
1386  @}
1387 */
1388 
1389 
1390 /*!
1391  @name Relay Feature
1392  @{
1393 */
1394 
1395 /*!
1396  @brief Sets the maximum number of forwarding requests that can be assigned to a single station when relaying is enabled.
1397 
1398  @details The library uses this value as a metric when searching for and selecting relay paths.
1399  If you do not set a value, the library uses [<em>maximum mesh participants</em>] × [<em>maximum mesh participants</em>] as the default.
1400 
1401  We recommend that you set this to the same value for all participants in a mesh. (Operation is not guaranteed if different values are set on different clients.)
1402 
1403  This function is only available when the network topology allows relaying, and <tt>@ref Startup</tt> has not yet been called.
1404 
1405  @param[in] num Specifies the maximum value.
1406 
1407  @return Returns a <tt>Result</tt> value indicating success if the setting succeeds.
1408  @retval ResultInvalidState Indicates that relay connections are disabled or the <tt>Startup</tt> function has already been called. Programming error. Fix your program so that this error is not returned.
1409 */
1410  nn::Result SetMaxNumOfRelayRoutesAssignedToStation(u16 num);
1411 
1412 
1413 /*!
1414  @brief Sets the maximum total RTT for a relay route when relaying is enabled.
1415 
1416  @details The library uses this value as a metric when searching for and selecting relay paths.
1417  If you do not set a value, the library uses the default value of <tt>nn::pia::session::NN_PIA_SESSION_MAX_RTT_DEFAULT</tt>.
1418 
1419  We recommend that you set this to the same value for all participants in a mesh. (Operation is not guaranteed if different values are set on different clients.)
1420 
1421  This function is only available when the network topology allows relaying, and <tt>@ref Startup</tt> has not yet been called.
1422 
1423  @param[in] rtt Specifies the maximum value. The value is in milliseconds.
1424 
1425  @return Returns a <tt>Result</tt> value indicating success if the setting succeeds.
1426  @retval ResultInvalidState Indicates that relay connections are disabled or the <tt>Startup</tt> function has already been called. Programming error. Fix your program so that this error is not returned.
1427 */
1428  nn::Result SetMaxRtt(u16 rtt);
1429 
1430 /*!
1431  @brief Gets the connection path between the local station and an arbitrary station index when relaying is enabled. (For debugging.)
1432 
1433  @details This function is for debugging. Do not include it in retail products.
1434  The connection path between the local station and <tt><var>targetIndex</var></tt> is stored in <tt><var>pRelayIndex</var></tt>, according to the following rules.
1435  (The value of <tt><var>pRelayIndex</var></tt> does not change if the function could not retrieve the connection path.)
1436  <ul>
1437  <li>Direct connection: <tt><var>targetIndex</var></tt></li>
1438  <li>Relay connection: <tt>StationIndex</tt> of the relay requester.</li>
1439  <li>Local station: <tt>STATION_INDEX_INVALID</tt></li>
1440  <li>Not connected: <tt>STATION_INDEX_INVALID</tt></li>
1441  </ul>
1442 
1443  @param[in] targetIndex Specifies the <tt>StationIndex</tt> with the connection path to retrieve.
1444  @param[out] pRelayIndex Specifies the <tt>StationIndex</tt> indicating the connection path.
1445 
1446  @return Returns a <tt>Result</tt> value indicating success if the value can be retrieved successfully.
1447  @retval ResultInvalidState Indicates that relay connections are disabled. Programming error. Fix your program so that this error is not returned.
1448  @retval ResultInvalidArgument The specified <tt>StationIndex</tt> is invalid, or the pointer specified in the arguments is invalid. Programming error. Fix your program so that this error is not returned.
1449 */
1450  nn::Result GetConnectionRoute(StationIndex targetIndex, StationIndex* pRelayIndex);
1451 
1452 /*!
1453  @brief Specifies connection path emulation settings between any two <tt>StationIndex</tt> objects when relaying is enabled. (For debugging.)
1454 
1455  @details This function is for debugging. Do not include it in retail products.
1456 
1457  @details When you call this function, make sure that you have enabled the connection path emulation feature by using the <tt>@ref Mesh::SetDebugSetting</tt> function.
1458 
1459  @details If <tt>EMULATION_TYPE_RELAY</tt> is set, the connection method for the target <tt>StationIndex</tt> is always a relay connection
1460  (even when, for example, a direct connection is possible).
1461 
1462  @details Call this function when the terminal is not connected to a mesh.
1463  If you call this function when the terminal has already joined a mesh, there is no guarantee that changing the connection path emulation settings will work.
1464 
1465  @param[in] index1 Specifies a <tt>StationIndex</tt>.
1466  @param[in] index2 Specifies a <tt>StationIndex</tt>.
1467  @param[in] type Specifies the connection method emulation setting.
1468 
1469  @return Returns a <tt>Result</tt> value indicating success if the setting succeeds.
1470  @retval ResultInvalidState Indicates that relay connections are disabled. Programming error. Fix your program so that this error is not returned.
1471  @retval ResultInvalidArgument Indicates that the <tt>StationIndex</tt> is invalid, or the specified <tt>EmulationType</tt> is invalid. Programming error. Fix your program so that this error is not returned.
1472 
1473  @see ResetRelayEmulation
1474 */
1475  nn::Result RelayEmulation(StationIndex index1, StationIndex index2, EmulationType type);
1476 
1477 /*!
1478  @brief Initializes connection path emulation settings when relay connections are enabled. (For debugging.)
1479 
1480  @details This function is for debugging. Do not include it in retail products.
1481 
1482  @details All connections are initialized to use the connection path emulation configured by the <tt>Mesh::RelayEmulation</tt> function.
1483  (This is equivalent to setting <tt>EMULATION_TYPE_NONE</tt> for all combinations of <tt>StationIndex</tt>.)
1484 
1485  @details Call this function when the terminal is not connected to a mesh.
1486  If you call this function when the terminal has already joined a mesh, there is no guarantee that changing the connection path emulation settings will work.
1487 
1488  @see RelayEmulation
1489 */
1490  void ResetRelayEmulation();
1491 
1492 /*!
1493  end of name Relay Feature
1494  @}
1495 */
1496 
1497 
1498  /// @cond PRIVATE
1499 /*!
1500  @brief Sets a flag for determining whether host migration has started.
1501  @param[in] val Specifies that the flag is in this state after the function is called.
1502 */
1503  void SetHostMigrationStartFlag(bool val);
1504  /// @endcond
1505 
1506  /// @cond PRIVATE
1507 /*!
1508  @brief Gets a flag for determining whether host migration has started.
1509  @return Returns the flag state.
1510 */
1511  bool GetHostMigrationStartFlag();
1512  /// @endcond
1513 
1514  //private
1515  ProcessHostMigrationJob* GetProcessHostMigrationJobPtr()
1516  {
1517  return m_pProcessHostMigrationJob;
1518  }
1519 
1520  KickoutManageJob* GetKickoutManageJobPtr()
1521  {
1522  return m_pKickoutManageJob;
1523  }
1524 
1525  //private
1526  ProcessDestroyMeshJob* GetProcessDestroyMeshJobPtr()
1527  {
1528  return m_pProcessDestroyMeshJob;
1529  }
1530 
1531  void SetFatalError(DisconnectReason reason);
1532 
1533  /// @cond PRIVATE
1534 /*!
1535  @brief Sets whether to add players to Player History automatically.
1536  @param[in] val Specify <tt>true</tt> to add players automatically.
1537 */
1538  void SetAutoAddRecentPlayRecord(bool val)
1539  {
1540  m_AutoAddRecentPlayRecord = val;
1541  }
1542 /// @endcond
1543 
1544 #if NN_PIA_EXPERIMENT_SHARE_CONNECTION_INFO_EARLY
1545  //private
1546  ProcessUpdateMeshJob* GetProcessUpdateMeshJobPtr()
1547  {
1548  return m_pProcessUpdateMeshJob;
1549  }
1550 #endif
1551 
1552  //private
1553  NetworkTopology GetNetworkTopologyType()
1554  {
1555  return m_NetworkTopologyType;
1556  }
1557 
1558  /// @cond PRIVATE
1559 /*!
1560  @brief Gets the location where the signature setting is stored.
1561 */
1562  const SignatureSettingStorage* GetSignatureSettingStorage() const
1563  {
1564  return m_pSignatureSettingStorage;
1565  }
1566  /// @endcond
1567 
1568  /// @cond PRIVATE
1569  static nn::Result SetDebugSettingForInternal(const DebugSetting& debugSetting);
1570  /// @endcond
1571 
1572  /// @cond PRIVATE
1573  void NotifyLeaveStationAddress(const common::StationAddress& leftStationAddress);
1574  /// @endcond
1575 
1576 /*!
1577  @name Other
1578  @{
1579 */
1580 
1581 /*!
1582  @brief Prints information that is useful for debugging.
1583 
1584  @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> API reference.
1585 */
1586  void TraceStationConnectionInfoList(u64 flag);
1587 
1588  /// @cond PRIVATE
1589  bool IsUsingHostMigration(); //Gets whether host migration is in use.
1590  int GetJoinMeshSequence(); // Gets the progress of joining the mesh.
1591  void SetSkipCleanupReport(bool isSkip);
1592  void SetSkipReport(bool isSkip);
1593  void SendReport(u8 type);
1594  bool IsProcessedAtMeshBegin() const;
1595  bool IsProcessingLeaveMesh() const;
1596  State GetMeshState() const;
1597  void IsDenyJoinRequestBySession(bool isDeny); // While <tt>true</tt> is set, participation in the <tt>Mesh</tt> instance fails on denial from <tt>Session</tt> and <tt>ResultJoinRequestDenied</tt> is returned.
1598  void CleanupMonitoringBeginData();
1599  /// @endcond
1600 
1601 #if NN_PIA_EXPERIMENT_BAND_WIDTH_CHECK
1602  /// @cond PRIVATE
1603  BitRateCheckMode GetBitRateCheckMode();
1604  nn::pia::transport::BandwidthCheckerProtocol* GetBandwidthCheckerProtocol();
1605  /// @endcond
1606 #endif
1607 
1608  /// @cond PRIVATE
1609  s32 GetProcessUpdateMeshJobStepSequence() const;
1610  /// @endcond
1611 
1612 /*!
1613  @brief Prints information that is useful for debugging.
1614 
1615  @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> API reference.
1616 */
1617  virtual void Trace(u64 flag) const;
1618 
1619 /*!
1620  end of name Others
1621  @}
1622 */
1623 
1624 protected:
1625  static Mesh* s_pMesh;
1626  static DebugSetting s_DebugSetting;
1627 
1628  static nn::Result setDebugSettingImpl(const DebugSetting& debugSetting);
1629 
1630 private:
1631  /// @cond PRIVATE
1632 /*!
1633  @brief Instantiates an object. (DO NOT USE.)
1634 */
1635  Mesh(const nn::pia::session::Mesh::Setting& setting);
1636  /// @endcond
1637 
1638  /// @cond PRIVATE
1639 /*!
1640  @brief Destroys the object. (DO NOT USE.)
1641 */
1642  virtual ~Mesh(void);
1643  /// @endcond
1644 
1645  /// @cond PRIVATE
1646 /*!
1647  @brief This copy constructor is private.
1648 */
1649  Mesh(const Mesh&);
1650  /// @endcond
1651 
1652  /// @cond PRIVATE
1653 /*!
1654  @brief This assignment operator is private.
1655 */
1656  Mesh& operator=(const Mesh&);
1657  /// @endcond
1658 
1659  nn::Result Initialize(const nn::pia::session::Mesh::Setting& setting, bool isEnableRelayEmulation);
1660 
1661  nn::Result SetupProtocols(); // System protocol preparations.
1662 
1663  void CleanupStatus(); // Called at the end of the mesh that initializes the internal state.
1664  void CleanupJobs(); // Called at the end of the mesh that initializes the job the mesh manages.
1665 
1666  void CleanupStationsJobs();
1667 
1668  void FixConnectedId(nn::pia::StationIndex id);
1669  void UnfixDisconnectedId(nn::pia::StationIndex id);
1670 
1671  void StartUse(nn::pia::StationIndex id); // Changes the status to "in use."
1672  void StopUse(nn::pia::StationIndex id); // Changes the status to "not in use."
1673 
1674  void ResetStationIndexUsage(); // Resets the use status of the <tt>StationIndex</tt>.
1675 
1676  // Records the times when the mesh was successfully created and joined.
1677  void SetMeshStartTime(common::Time startTime)
1678  {
1679  m_MeshStartTime = startTime;
1680  m_MeshStartTimeValidFlag = true;
1681  }
1682 
1683  // Checks whether the values recorded for when the mesh was successfully created or joined are valid.
1684  bool CheckMeshStartTimeIsValid() const
1685  {
1686  return m_MeshStartTimeValidFlag;
1687  }
1688 
1689  // Calculates the difference between an arbitrary time and when the mesh was successfully created or joined.
1690  common::TimeSpan CalcDiffWithMeshStartTime(common::Time target) const
1691  {
1692  return (target - m_MeshStartTime);
1693  }
1694 
1695  void ProcessingAtMeshBegin();
1696  void ProcessingAtMeshEnd(DisconnectReason reason);
1697  void ProcessingAtEndHM();
1698  void MonitoringProcess(DisconnectReason reason, u8 type);
1699 
1700  enum AsyncProcessingName
1701  {
1702  ASYNC_NOTHING = 0,
1703  ASYNC_CREATE_SESSION,
1704  ASYNC_DESTROY_SESSION,
1705  ASYNC_LEAVE_SESSION_WITH_HM,
1706  ASYNC_JOIN_SESSION,
1707  ASYNC_LEAVE_SESSION
1708  };
1709 
1710  void ResetInternalAsyncState();
1711  bool IsCompletedAsyncProcess(AsyncProcessingName processingName);
1712  nn::Result GetAsyncProcessResult(AsyncProcessingName processingName);
1713  nn::Result CancelAsyncProcess(AsyncProcessingName processingName);
1714 
1715  nn::Result joinMeshCore(
1716  const nn::pia::transport::StationConnectionInfo& stationConnectionInfo,
1717  nn::pia::common::CallContext* pCallContext);
1718 
1719  void SetMeshState(State meshState);
1720  void NoticeMeshEvent(EventType eventType, StationIndex idx);
1721 
1722  CreateMeshJob* m_pCreateMeshJob;
1723  JoinMeshJob* m_pJoinMeshJob;
1724  LeaveMeshJob* m_pLeaveMeshJob;
1725  ProcessJoinRequestJob* m_pProcessJoinRequestJob;
1726  ProcessUpdateMeshJob* m_pProcessUpdateMeshJob;
1727  DestroyMeshJob* m_pDestroyMeshJob;
1728  ProcessDestroyMeshJob* m_pProcessDestroyMeshJob;
1729  ProcessHostMigrationJob* m_pProcessHostMigrationJob;
1730  LeaveWithHostMigrationJob* m_pLeaveWithHostMigrationJob;
1731  SignatureSettingStorage* m_pSignatureSettingStorage;
1732 #if NN_PIA_EXPERIMENT_RELAY_CONNECTION_TOPOLOGY
1733  RelayRouteManageJob* m_pRelayRouteManageJob;
1734 #endif
1735  KickoutManageJob* m_pKickoutManageJob;
1736  nn::pia::transport::MissingStationHandler* m_pMissingStationHandler;
1737 
1738  MeshEventCallback m_MeshEventCallback;
1739  JoiningMeshApprovalCallback m_JoiningMeshApprovalCallback;
1740  CheckHostCandidateRankingCallback m_CheckHostCandidateRankingCallback;
1741  GetSessionIdCallback m_GetSessionIdCallback;
1742 
1743  u32 m_MeshProtocolHandle;
1744  MeshProtocol* m_pMeshProtocol;
1745  nn::pia::transport::StationProtocol* m_pStationProtocol;
1746 
1747 #if NN_PIA_EXPERIMENT_BAND_WIDTH_CHECK
1748  u32 m_BandwidthCheckerHandle;
1749  nn::pia::transport::BandwidthCheckerProtocol* m_pBandwidthCheckerProtocol;
1750 #endif
1751 
1752  u16 m_StationCount;
1753  u16 m_StationMax;
1754  bool m_IsApprovalJoin;
1755 
1756  // n2908: Approve/deny join-in flag that is changed only when <tt>OpenSession</tt> or <tt>CloseSession</tt> is handled by <tt>Session</tt>.
1757  bool m_IsDenyJoinRequestBySession;
1758 
1759  nn::pia::StationIndex m_HostStationIndex;
1760  nn::pia::StationIndex m_LocalStationIndex;
1761 
1762  State m_State;
1763  DisconnectReason m_DisconnectReason;
1764  HostMigrationMode m_HostMigrationMode;
1765  NetworkTopology m_NetworkTopologyType;
1766 #if NN_PIA_EXPERIMENT_BAND_WIDTH_CHECK
1767  BitRateCheckMode m_BitRateCheckMode;
1768 #endif
1769 
1770  bool m_IsEnableHostMigration;
1771 
1772  bit32 m_StationIndexUsedFlags;
1773  u32 m_UpdateCount;
1774 
1775  //n1769
1776  u32 m_SyncClockProtocolHandle;
1777 
1778  nn::pia::common::Time m_MeshStartTime;
1779  bool m_MeshStartTimeValidFlag;
1780 
1781  bool m_IsStarted;
1782 
1783  bool m_HostMigrationStartFlag;
1784 
1785  bool m_AutoAddRecentPlayRecord;
1786 
1787  common::MonitoringDataSender* m_pMonitoringDataSender;
1788 
1789  common::CallContext m_InternalContext;
1790  AsyncProcessingName m_CurrentAsyncProcessingName;
1791 
1792  MeshEventListener* m_pMeshEventListener;
1793 
1794  bool m_IsSkipSendingReport;
1795  bool m_IsSkipCleanupReport;
1796 };
1797 }
1798 }
1799 } // end of namespace nn::pia::session
nn::pia::session::BitRateCheckMode bitRateCheckMode
Settings for the bitrate detection feature.
Definition: session_Mesh.h:216
u16 GetStationNum() const
Gets the number of valid stations connected to the current mesh.
Definition: session_Mesh.h:1078
EventType
This enumerated type is passed as a parameter to the callback that sends notifications about changes ...
Definition: session_Mesh.h:320
nn::pia::transport::NetworkFactory * pNetworkFactory
Pointer to an instance of the concrete class that inherits nn::pia::transport::NetworkFactory (factor...
Definition: session_Mesh.h:213
EmulationType
Enumerates connection path emulation settings. (For debugging.)
Definition: session_Mesh.h:308
bool IsHost() const
Gets whether the local device is the mesh host.
Definition: session_Mesh.h:1124
Specifies that the disconnection was caused by a desync. (The mesh information was no longer consiste...
Definition: session_Mesh.h:296
This class maintains signature setting information.
Definition: common_SignatureSetting.h:33
Class that represents time.
Definition: common_Time.h:39
Specifies that the disconnection was caused by something other than the Mesh object. One way to get this value is when the network connection is lost.
Definition: session_Mesh.h:298
StationIndex
Enumerates StationIndex values.
Definition: platformCtr.h:44
Definition of the StationId identifying the station within the session.
Definition: types.h:33
Definition: assert.h:115
u32 maxSilenceTime
Specifies the maximum allowable time without communication (in milliseconds). The default value is se...
Definition: session_Mesh.h:242
s32 bitRateMeasuringSpan
Sets the time to spend measuring when the bit rate detection feature is used. The value is in millise...
Definition: session_Mesh.h:251
(For debugging.) This structure stores the debug feature settings that are passed to nn::pia::session...
Definition: session_Mesh.h:261
Represents a station. A station refers to a machine participating in a Pia session.
Definition: transport_Station.h:75
u32 keepAliveSendingInterval
Specifies the send interval for keep-alive (in milliseconds). The default value is session::NN_PIA_SE...
Definition: session_Mesh.h:243
This structure stores settings passed to nn::pia::session::Mesh::CreateInstance.
Definition: session_Mesh.h:205
DisconnectReason
This enumerated type represents reasons why a Mesh object cannot communicate.
Definition: session_Mesh.h:288
const nn::pia::transport::Station::PlayerName * pPlayerName
Specifies the name and language code associated with the local station. Other members of the mesh acc...
Definition: session_Mesh.h:245
size_t bitRateCheckPacketSize
Specifies the IP packet size used for testing when using the bitrate detection feature. The value is in bytes. The expected value is the average size of IP packet sent and received by the application. It must be a multiple of 4. The default is 0.
Definition: session_Mesh.h:250
Specifies that the mesh host has migrated. (Only occurs when host migration is enabled.)
Definition: session_Mesh.h:324
bool bUsingHostMigration
Sets the use of the host migration feature. The default is true (enabled).
Definition: session_Mesh.h:244
Stores the player name struct associated with a Station.
Definition: transport_Station.h:692
const nn::pia::common::CryptoSetting * pCryptoSetting
Specifies a pointer that points to a structure for configuring encryption. No encryption is configure...
Definition: session_Mesh.h:246
Specifies that the disconnection from the mesh was caused by the library. One way to get this value i...
Definition: session_Mesh.h:295
NetworkTopology
Enumerated type for configuring the network topology of a mesh created with the Session class or the ...
Definition: session_types.h:43
Represents the calling context.
Definition: common_CallContext.h:43
static const SignatureSetting NO_SIGNATURE
Specifies an instance of the signature setting class that has no signature.
Definition: common_SignatureSetting.h:123
Specifies that the disconnection was caused by the local station. You get this value when the local s...
Definition: session_Mesh.h:292
Class for representing time spans. This class can perform type conversions with numeric values in mil...
Definition: common_TimeSpan.h:41
This structure stores settings passed to nn::pia::session::Mesh::Startup.
Definition: session_Mesh.h:223
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
Contains member functions that manage connections with other devices.
Definition: session_Mesh.h:186
nn::pia::common::SignatureSetting signatureSetting
Specifies a properly configured instance of the class used to specify packet-signature settings...
Definition: session_Mesh.h:247
BitRateCheckMode
Enumerated type for setting the bitrate detection feature.
Definition: session_types.h:56
Stores the ID token associated with a Station.
Definition: transport_Station.h:682
bool isDisableCheckMaxSilenceTime
Does not check the range set for the maximum time without communication.
Definition: session_Mesh.h:269
Specifies that the local station was kicked out from the mesh because of a call to the Mesh::KickoutS...
Definition: session_Mesh.h:294
static Mesh * GetInstance()
Gets an instance of the Mesh object.
Definition: session_Mesh.h:406
nn::pia::session::NetworkTopology networkTopology
Specifies the network topology setting for the mesh.
Definition: session_Mesh.h:214
s32 uplinkBitRateLowerLimit
Specifies the minimum rate required by the application when using the bitrate detection feature...
Definition: session_Mesh.h:249
Specifies that the disconnection was caused by a failed host migration.
Definition: session_Mesh.h:297
Specifies that the disconnection was caused by another station in the mesh. One way to get this value...
Definition: session_Mesh.h:293
Maximum value of StationIndex.
Definition: platformCtr.h:58
Indicates that a station has joined.
Definition: session_Mesh.h:322
bool isEnableRelayEmulation
Settings for the connection route emulation feature for debugging.
Definition: session_Mesh.h:268
bool isSkipBitRateCheck
Set to skip detection processes when using bitrate detection. Specify true to skip. The default is false.
Definition: session_Mesh.h:252
Specifies that no communication has been performed. You get this value if you never build or join a m...
Definition: session_Mesh.h:291
const nn::pia::transport::Station::IdentificationToken * pToken
Specifies a pointer to the identification token indicating the local device. If NULL is specified...
Definition: session_Mesh.h:254
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40
A station has left.
Definition: session_Mesh.h:323
A structure for encryption settings.
Definition: common_CryptoSetting.h:33