CTR Pia
4.11.3
Game Communication Engine
|
Contains member functions that manage connections with other devices. More...
Classes | |
struct | DebugSetting |
(For debugging.) This structure stores the debug feature settings that are passed to nn::pia::session::Mesh::SetDebugSetting . More... | |
struct | Setting |
This structure stores settings passed to nn::pia::session::Mesh::CreateInstance . More... | |
struct | StartupSetting |
This structure stores settings passed to nn::pia::session::Mesh::Startup . More... | |
Public Types | |
typedef bool(* | JoiningMeshApprovalCallback) (const nn::pia::transport::Station::IdentificationToken *pRequesterToken) |
Declares the type of the callback function for determining whether to approve join requests from clients. More... | |
typedef void(* | MeshEventCallback) (EventType eventType, StationId id) |
This callback function type is called when the mesh state changes. More... | |
Public Member Functions | |
Finish Initialization | |
nn::Result | Startup (Mesh::StartupSetting &startupSetting) |
Starts the Mesh . More... | |
void | Cleanup () |
Cleans up the Mesh . More... | |
Building, Destroying, Joining, and Leaving Meshes | |
nn::Result | CreateMeshAsync () |
Builds a mesh. More... | |
bool | IsCompletedCreateMesh () |
Checks the completion of CreateMeshAsync asynchronous processing. More... | |
nn::Result | GetCreateMeshResult () |
Gets the result of CreateMeshAsync asynchronous processing. More... | |
nn::Result | DestroyMeshAsync () |
Destroys a mesh. More... | |
bool | IsCompletedDestroyMesh () |
Checks the completion of DestroyMeshAsync asynchronous processing. More... | |
nn::Result | GetDestroyMeshResult () |
Gets the result of DestroyMeshAsync asynchronous processing. More... | |
nn::Result | LeaveMeshWithHostMigrationAsync () |
Leaves a mesh. Also specifies that host migration will start for mesh participants. More... | |
bool | IsCompletedLeaveMeshWithHostMigration () |
Checks the completion of LeaveMeshWithHostMigrationAsync asynchronous processing. More... | |
nn::Result | GetLeaveMeshWithHostMigrationResult () |
Gets the result of LeaveMeshWithHostMigrationAsync asynchronous processing. More... | |
nn::Result | JoinMeshAsync (const nn::pia::transport::StationConnectionInfo &stationConnectionInfo) |
Joins a mesh. More... | |
bool | IsCompletedJoinMesh () |
Checks the completion of JoinMeshAsync asynchronous processing. More... | |
nn::Result | GetJoinMeshResult () |
Gets the result of JoinMeshAsync asynchronous processing. More... | |
nn::Result | CancelJoinMeshAsync () |
Cancels JoinMeshAsync asynchronous processes. More... | |
nn::Result | LeaveMeshAsync () |
Leaves a joined mesh. More... | |
bool | IsCompletedLeaveMesh () |
Checks the completion of LeaveMeshAsync asynchronous processing. More... | |
nn::Result | GetLeaveMeshResult () |
Gets the result of LeaveMeshAsync asynchronous processing. More... | |
nn::Result | KickoutStation (nn::pia::StationId id) |
Kicks a station from the mesh. More... | |
Mesh Analysis | |
u16 | GetStationNum () const |
Gets the number of valid stations connected to the current mesh. More... | |
nn::pia::StationId | GetHostStationId () const |
Gets the StationId of the mesh host. More... | |
nn::pia::StationId | GetLocalStationId () const |
Gets the StationId that specifies the local device. More... | |
bool | IsHost () const |
Gets whether the local device is the mesh host. More... | |
bool | CheckStationIdIsValid (nn::pia::StationId id) const |
Checks whether an arbitrary StationId within the mesh is currently valid. More... | |
nn::Result | CheckConnectionError () const |
Confirms whether the state of the current Mesh is communicable. More... | |
DisconnectReason | GetDisconnectReason () const |
Gets the reason why the Mesh object was disconnected. More... | |
bool | IsCompleteBitRateCheck () |
Determines whether the bitrate value may be found using the bitrate detection feature. More... | |
nn::Result | GetUplinkBitRate (s32 *pBps) |
Gets the uplink bitrate of the connection measured by the bitrate detection feature. More... | |
Registering and Unregistering Callback Functions | |
void | RegisterMeshEventCallback (MeshEventCallback callback) |
Registers the callback function that is called when the mesh state changes. More... | |
void | UnregisterMeshEventCallback () |
Unregisters the registered callback function for mesh state changes. More... | |
void | RegisterJoiningMeshApprovalCallback (JoiningMeshApprovalCallback callback) |
Registers the callback used to approve or deny requests received by the host from clients seeking to join the mesh. More... | |
void | UnregisterJoiningMeshApprovalCallback () |
Unregisters the registered Join request callback function for approving or denying the request. More... | |
Synchronous Clock | |
s64 | GetTime (void) const |
Specifies the synchronous clock (the time, in milliseconds, since the mesh was created). More... | |
void | SetSyncClockPulseInterval (s32 interval) |
Specifies the send interval of the synchronization pulse for the synchronous clock. More... | |
s32 | GetSyncClockPulseInterval (void) const |
Gets the send interval of the synchronization pulse for the synchronous clock. More... | |
Relay Feature | |
nn::Result | SetMaxNumOfRelayRoutesAssignedToStation (u16 num) |
Sets the maximum number of forwarding requests that can be assigned to a single station when relaying is enabled. More... | |
nn::Result | SetMaxRtt (u16 rtt) |
Sets the maximum total RTT for a relay route when relaying is enabled. More... | |
nn::Result | GetConnectionRoute (StationIndex targetIndex, StationIndex *pRelayIndex) |
Gets the connection path between the local station and an arbitrary station index when relaying is enabled. (For debugging.) More... | |
nn::Result | RelayEmulation (StationIndex index1, StationIndex index2, EmulationType type) |
Specifies connection path emulation settings between any two StationIndex objects when relaying is enabled. (For debugging.) More... | |
void | ResetRelayEmulation () |
Initializes connection path emulation settings when relay connections are enabled. (For debugging.) More... | |
Other | |
void | TraceStationConnectionInfoList (u64 flag) |
Prints information that is useful for debugging. More... | |
virtual void | Trace (u64 flag) const |
Prints information that is useful for debugging. More... | |
Static Public Member Functions | |
Singleton Instance Control | |
static nn::Result | CreateInstance (const nn::pia::session::Mesh::Setting &setting) |
Creates an instance of Mesh . More... | |
static void | DestroyInstance () |
Destroys the instance of Mesh . | |
static Mesh * | GetInstance () |
Gets an instance of the Mesh object. More... | |
static nn::Result | SetDebugSetting (const DebugSetting &debugSetting) |
(For debugging.) Sets the debugging features for Mesh . More... | |
Contains member functions that manage connections with other devices.
This class implements the singleton pattern. Only a single instance can be created.
Mesh
class when using sessions. Do not use the Session
class when directly manipulating meshes.Some of the internal processes of the Mesh
class are registered as jobs in nn::pia::common::Scheduler
. To use the Mesh
features, you must make periodic calls to nn::pia::common::Scheduler::Dispatch
.
2015-05-20 Added the Mesh::GetUplinkBitRate
function.
2015-05-20 Added the bitRateCheckMode
member to the Setting
structure to enable configuration of the bit rate detection feature.
2015-05-20 Added the uplinkBitRateLowerLimit
and bitRateCheckPacketSize
members to the StartupSetting
structure to enable configuration of the bit rate detection feature.
2015-05-11 Provided the StartupSetting
structure to consolidate the arguments when calling the Startup()
function.
2014-09-18 Changed the specifications so that ResultAlreadyExists
is returned if you call CreateInstance()
when an instance already exists.
2014-09-17 Changed the Result
returned when a StationId
that has already been kicked out is specified for Mesh::KickoutStation
.
2014-05-30 Changed the notations for the cautions when local communication for Mesh::Startup
and host migration are enabled.
2014-05-15 Added the Mesh::CheckConnection
function that returns a Result
indicating whether Mesh
is in a communicable state.
2014-05-02 Added a note to the description of Mesh::Startup(const transport::Station::PlayerName*, const common::CryptoSetting*, const common::SignatureSetting&, const transport::Station::IdentificationToken*)
about the affect of the UdsNode connection monitoring feature when the host migration feature is enabled for local communication.
2014-04-17 Added a note to the description of Mesh::Startup(u32, u32, const transport::Station::PlayerName*, const common::CryptoSetting*, const common::SignatureSetting&, const transport::Station::IdentificationToken*)
about the affect of the UdsNode connection monitoring feature when the host migration feature is enabled for local communication.
2014-02-10 Added a note to the descriptions of both Mesh::RelayEmulation
and Mesh::ResetRelayEmulation
about when the functions can be called.
2014-02-03 Organized the results that are returned when Mesh::JoinMeshAsync
or asynchronous processes fail, and increased the number of reasons for distinguishable asynchronous process failures.
2013-12-18 Removed the synchronous processing version of Mesh::CreateMesh
.
2013-12-11 Fixed a bug where the asynchronous processing result was different from the actual reason for failure when Mesh::JoinMesh
failed because its request was rejected due to the internal state of the host's library.
2013-12-04 Added an overload with arguments to Mesh::Startup
to pass a structure for the encryption settings.
2013-08-09 Fixed a bug where the internal state would become inconsistent if Mesh::DestroyMesh
was called while joining a mesh, or if a station called Mesh::KickoutStation
on itself.
2013-08-09 Corrected the descriptions of the return values of Mesh::GetConnectionRoute
and Mesh::RelayEmulation
. (No changes were made to conditions that result in an error or Result
types.)
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.
2013-07-26 Removed Mesh::GetIdentificationToken
.
2013-07-10 Changed the specifications of Mesh::Startup
about the timeout used with the Mesh::JoinMesh
process so that it cannot be changed by applications.
2013-07-10 Removed some Result
types that can be returned when asynchronous processing of Mesh::JoinMesh
fails.
2013-06-25 Added the Mesh::RelayEmulation
and Mesh::ResetRelayEmulation
functions for debugging the relay feature.
2013-06-25 Added an overload to Mesh::CreateInstance
allowing you to enable or disable the use of debugging of the relay feature.
2013-06-18 Changed the specification to check whether lower modules can use host migration when Mesh::Startup
is called while host migration is enabled.
2013-06-13 Fixed a bug where calls to Mesh::LeaveMesh
would fail if they were called at the same time a station was being kicked from the mesh using Mesh::KickoutStation
.
2013-05-28 Changed the default timeout for Mesh::JoinMesh
processing (defined by the NN_PIA_SESSION_JOIN_TIMEOUT_DEFAULT
constant) from 20,000 milliseconds to 30,000 milliseconds.
2013-05-15 Added the Mesh::KickoutStation
function for kicking out an arbitrary station from the mesh.
2013-05-15 Added the Mesh::DisconnectReason
enumerated type to represent reasons why a station is unable to connect to a mesh, and the Mesh::GetDisconnectReason
function to get this reason.
2013-04-24 Added the Mesh::GetConnectionRoute
function for debugging relaying.
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.
2013-04-08 Added available settings to use as the network topology for the meshes built using the Mesh
class.
2013-04-08 Added the following functions for changing settings when relaying is enabled: Mesh::SetMaxNumOfRelayRoutesAssignedToStation
and Mesh::SetMaxRtt
.
2013-03-29 Changed the Mesh::Startup
function to set the player name.
2013-03-14 Added an asynchronous version of the Mesh::CreateMesh
function.
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.
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.
2012-12-19 Reviewed the value of nn::pia::session::NN_PIA_SESSION_KEEP_ALIVE_INTERVAL_DEFAULT
(the default setting for the interval at which to send keep-alives), and changed it from 2000 to 1000.
2012-12-18 Fixed a bug where clients already in a mesh could be dropped if a new client failed to join it.
2012-12-18 Added a Result
type that can be returned when asynchronous processing of a Mesh::JoinMesh
fails.
2012-12-10 Fixed a timing bug where host migration could fail when it was expected to succeed.
2012-12-10 Fixed a bug where local host migration would fail for everyone unless it succeeded for all the remaining clients.
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.
2012-11-30 Changed the specifications to configure the packet-signing feature when calling the Mesh::Startup
function. The parameter specification was changed.
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.
2012-11-13 Fixed a bug where the mesh client could never detect an abnormal connection status if communication with another client was lost.
2012-10-29 Categorized member functions to improve readability of the API reference.
2012-08-22 Fixed a bug in the link between the server matchmaking process for Internet communication and the mesh participation process.
2012-08-22 As a result of this fix, communication with PiaMesh
in earlier versions is no longer compatible.
2012-08-20 Fixed a bug where disconnect events with the same StationIndex
were duplicated in events sent in a callback for a mesh state change notification.
2012-08-07 Fixed a bug where continuing host migration by using local communication frequently failed.
2012-07-18 Made minor amendments to the descriptions of the Mesh::Startup
, Mesh::Cleanup
, and related functions.
2012-07-10 Improved the speed and accuracy of host migration failure assessments during host migration.
2012-07-05 Added a Mesh::Startup
overload that enables you to specify any settings, such as the timeout period for the mesh participation process.
2012-07-03 Added a Result
type that can be returned when asynchronous processing of a Mesh::JoinMesh
fails.
2012-07-02 Fixed a bug where when running a Mesh::DestroyMesh
, the mesh destroy message sometimes did not reach the client.
2012-06-11 Fixed a bug where a station could not join a session using the Mesh::JoinMesh
function if another station left the mesh while the function was executing.
2012-05-30 Fixed a bug where clients did not receive notifications when the mesh host called the Mesh::DestroyMesh
function.
2012-05-30 Fixed a bug where disconnecting from a peer at nearly the same time the Mesh::LeaveMesh
function starts would result in a timeout wait even though the peer had already disconnected.
2012-05-22 Implemented host migration. To enable or disable the host migration feature, use the Mesh::Setting
structure, which is passed when you create a Mesh
instance.
2012-05-22 Added the Mesh::LeaveMeshWithHostMigration
function.
2012-05-22 Added host migration-related events to the events that are notified with the state change notification callback for the mesh.
2012-05-22 Changed the name of the event enumerated type from Event
to EventType
for the state change notification callback for the mesh.
2012-05-15 Added a function to get and set the synchronization pulse interval of the synchronization clock.
2012-05-11 Added the GetTime
function, which can get the elapsed time (called the synchronization clock) from the time that the mesh was created.
2012-05-01 Added the Mesh::Startup
function.
2012-05-01 Implemented the shared identification token feature.
2012-04-24 Added a feature to notify, in a callback, the changes to mesh information when joining or leaving stations.
2012-04-16 Changed the maximum specification value of connectible stations from 10
to 12
.
2012-04-12 Listed const
information for functions in which the internal state does not change.
2012-04-12 Changed Mesh::DestroyMesh
so that it is an asynchronous process.
2012-04-12 Added an enumerated type to indicate the Mesh
state and a function for getting the state.
2012-04-12 Implemented a keep-alive feature.
2012-04-06 Initial version.
typedef bool(* nn::pia::session::Mesh::JoiningMeshApprovalCallback) (const nn::pia::transport::Station::IdentificationToken *pRequesterToken) |
Declares the type of the callback function for determining whether to approve join requests from clients.
If the callback returns true
, the join request is approved. If it returns false
, the join request is denied.
<b>Parameters</b> <ul> <li> pRequesterToken: Pointer to the identification token for the station that sent the join request.</li> </ul>
This enumerated type represents reasons why a Mesh
object cannot communicate.
This information can be retrieved using the Mesh::GetDisconnectReason
function.
Enumerator | |
---|---|
UNKNOWN_REASON |
Specifies that the reason for the disconnection is unknown. One way to get this value is by calling the |
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 |
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 |
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. |
KICKOUT_BY_USER |
Specifies that the local station was kicked out from the mesh because of a call to the |
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. |
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. |
MIGRATION_FAIL |
Specifies that the disconnection was caused by a failed host migration. |
EXTERNAL_FACTOR |
Specifies that the disconnection was caused by something other than the |
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. |
Enumerates connection path emulation settings. (For debugging.)
This is used as the third argument to Mesh::RelayEmulation
.
Enumerator | |
---|---|
EMULATION_TYPE_NONE |
Specifies no emulation. |
EMULATION_TYPE_RELAY |
Specifies the relay connection. (No direct connection is possible.) |
This enumerated type is passed as a parameter to the callback that sends notifications about changes in the mesh state.
It represents the possible changes to the mesh state.
nn::Result nn::pia::session::Mesh::CancelJoinMeshAsync | ( | ) |
Cancels JoinMeshAsync
asynchronous processes.
This function cancels asynchronous processes started by JoinMeshAsync
. The cancel process advances by periodically calling the nn::pia::common::Scheduler::Dispatch
function. The library quickly acts to cancel the asynchronous process after this function is called, but check using the IsCompletedJoinMesh()
function that the cancellation has completed.
JoinMeshAsync
asynchronous processing. On success, returns a Result
value for which the IsSuccess()
function returns true
. If this function call fails, one or more of the following Result
values is returned. ResultInvalidState
Returned when no JoinMeshAsync
asynchronous processing is being performed. Programming error. Fix your program so that this error is not returned.nn::Result nn::pia::session::Mesh::CheckConnectionError | ( | ) | const |
Confirms whether the state of the current Mesh
is communicable.
Indicates in the Result
whether the current Mesh
is in a communicable state. When not in a communicable state, use GetDisconnectReason
to check, in detail, the reasons for entering that state.
Result
value for which the IsSuccess()
function returns true
if communication is possible. Otherwise, one of the following Result
values is returned. ResultMeshConnectionIsLost
The Mesh
is in an incommunicable state. Perform cleanup.bool nn::pia::session::Mesh::CheckStationIdIsValid | ( | nn::pia::StationId | id | ) | const |
void nn::pia::session::Mesh::Cleanup | ( | ) |
|
static |
Creates an instance of Mesh
.
This function must be executed between calls to the nn::pia::session::BeginSetup
and nn::pia::session::EndSetup
functions.
If the relay emulation feature for debugging has been set by the SetDebugSetting
function, and the network topology is not set to NetworkTopology_RelayMesh
, the call to this function fails.
SetDebugSetting
in retail ROMs.[in] | setting | Specifies various settings. |
Result
value for which the IsSuccess()
function returns true
. You must make sure that the implementation of this function in your application does not return any errors. If this function call fails, one or more of the following Result
values is returned. ResultNotInitialized
Indicates that the session
module is not initialized. Programming error. Fix your program so that this error is not returned.
ResultInvalidState
Indicates that the function cannot be executed in this state. This error is returned when the function is executed outside calls to the nn::pia::session::BeginSetup
and nn::pia::session::EndSetup
functions. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Indicates that the settings specified in the argument are invalid. Programming error. Fix your program so that this error is not returned.
ResultAlreadyExists
Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
nn::Result nn::pia::session::Mesh::CreateMeshAsync | ( | ) |
Builds a mesh.
The local device acts as the mesh host.
Starts building a mesh asynchronously. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function. Use <tt>@ref IsCompletedCreateMesh</tt> to check whether the process has completed and <tt>@ref GetCreateMeshResult</tt> to check the result. You must set up the <tt>@ref nn::pia::transport::Transport</tt> instance beforehand.
Result
value for which the IsSuccess()
function returns true
if the local device successfully starts building a mesh. If this function call fails, one or more of the following Result
values is returned. ResultInvalidState
Indicates that the function cannot be executed in this state. Programming error. Fix your program so that this error is not returned.nn::Result nn::pia::session::Mesh::DestroyMeshAsync | ( | ) |
Destroys a mesh.
Only the mesh host can call this function.
Starts an asynchronous mesh destruction process. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function. Use <tt>@ref IsCompletedDestroyMesh</tt> to check whether the process has completed and <tt>@ref GetDestroyMeshResult</tt> to check the result. <b>Note:</b> If the mesh destruction process starts normally, the asynchronous process does not fail. Within the <tt>Mesh</tt> destruction process, all participants are notified that the <tt>Mesh</tt> will be ended. For stations that receive the notification, the internal state of their mesh is initialized and becomes <tt>STATE_DISCONNECTED</tt>.
Result
value for which the IsSuccess()
function returns true
if the mesh is successfully destroyed. If this function call fails, one or more of the following Result
values is returned. 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.nn::Result nn::pia::session::Mesh::GetConnectionRoute | ( | StationIndex | targetIndex, |
StationIndex * | pRelayIndex | ||
) |
Gets the connection path between the local station and an arbitrary station index when relaying is enabled. (For debugging.)
This function is for debugging. Do not include it in retail products. The connection path between the local station and targetIndex
is stored in pRelayIndex
, according to the following rules. (The value of pRelayIndex
does not change if the function could not retrieve the connection path.)
targetIndex
StationIndex
of the relay requester. STATION_INDEX_INVALID
STATION_INDEX_INVALID
[in] | targetIndex | Specifies the StationIndex with the connection path to retrieve. |
[out] | pRelayIndex | Specifies the StationIndex indicating the connection path. |
Result
value indicating success if the value can be retrieved successfully. ResultInvalidState
Indicates that relay connections are disabled. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
The specified StationIndex
is invalid, or the pointer specified in the arguments is invalid. Programming error. Fix your program so that this error is not returned.
nn::Result nn::pia::session::Mesh::GetCreateMeshResult | ( | ) |
Gets the result of CreateMeshAsync
asynchronous processing.
This function gets the results after an asynchronous process started by CreateMeshAsync
ends.
CreateMeshAsync
asynchronous processing. On success, returns a Result
value for which the IsSuccess()
function returns true
. If this function call fails, one or more of the following Result
values is returned. ResultInvalidState
Returned when CreateMeshAsync
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.nn::Result nn::pia::session::Mesh::GetDestroyMeshResult | ( | ) |
Gets the result of DestroyMeshAsync
asynchronous processing.
This function gets the results after an asynchronous process started by DestroyMeshAsync
ends. Note: If the mesh destruction process starts normally, the asynchronous process does not fail.
DestroyMeshAsync
asynchronous processing. On success, returns a Result
value for which the IsSuccess()
function returns true
. If this function call fails, one or more of the following Result
values is returned. 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.DisconnectReason nn::pia::session::Mesh::GetDisconnectReason | ( | ) | const |
Gets the reason why the Mesh
object was disconnected.
This function always returns UNKNOWN_REASON
if the Mesh
object is in a communicable state.
DisconnectReason
value indicating the reason why Mesh
disconnected.nn::pia::StationId nn::pia::session::Mesh::GetHostStationId | ( | ) | const |
|
inlinestatic |
nn::Result nn::pia::session::Mesh::GetJoinMeshResult | ( | ) |
Gets the result of JoinMeshAsync
asynchronous processing.
This function gets the results after an asynchronous process started by JoinMeshAsync
ends.
JoinMeshAsync
asynchronous processing. On success, returns a Result
value for which the IsSuccess()
function returns true
. If this function call fails, one or more of the following Result
values is returned. ResultCancelled
The asynchronous process was canceled. Perform cleanup.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
nn::Result nn::pia::session::Mesh::GetLeaveMeshResult | ( | ) |
Gets the result of LeaveMeshAsync
asynchronous processing.
This function gets the results after an asynchronous process started by LeaveMeshAsync
ends. Note: If the mesh destruction process starts normally, the asynchronous process does not fail.
LeaveMeshAsync
asynchronous processing. On success, returns a Result
value for which the IsSuccess()
function returns true
. If this function call fails, one or more of the following Result
values is returned. 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.nn::Result nn::pia::session::Mesh::GetLeaveMeshWithHostMigrationResult | ( | ) |
Gets the result of LeaveMeshWithHostMigrationAsync
asynchronous processing.
This function gets the results after an asynchronous process started by LeaveMeshWithHostMigrationAsync
ends. Note: If the mesh destruction process starts normally, the asynchronous process does not fail.
LeaveMeshWithHostMigrationAsync
asynchronous processing. On success, returns a Result
value for which the IsSuccess()
function returns true
. If this function call fails, one or more of the following Result
values is returned. 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.nn::pia::StationId nn::pia::session::Mesh::GetLocalStationId | ( | ) | const |
|
inline |
Gets the number of valid stations connected to the current mesh.
s32 nn::pia::session::Mesh::GetSyncClockPulseInterval | ( | void | ) | const |
Gets the send interval of the synchronization pulse for the synchronous clock.
s64 nn::pia::session::Mesh::GetTime | ( | void | ) | const |
Specifies the synchronous clock (the time, in milliseconds, since the mesh was created).
The synchronous clock is synchronized among all the stations in the mesh. Clients joined in the mesh periodically send a clock-synchronization pulse to the mesh host. The host then responds to these pulses, ensuring synchronization between the host and clients. By default, synchronization pulses are sent every two seconds, but the application can also change this interval. For more information, see SetSyncClockPulseInterval()
and GetSyncClockPulseInterval()
.
nn::Result nn::pia::session::Mesh::GetUplinkBitRate | ( | s32 * | pBps | ) |
Gets the uplink bitrate of the connection measured by the bitrate detection feature.
Note that the value returned by this function is simply a measurement of the amount of data received over a set amount of time and does not necessarily represent the actual bandwidth of the connection. Even if the connection is capable of a high bitrate, if an application has low requirements, the amount of data sent and received during the measurement process is also small, which results in a lower bits-per-second value.
[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. |
Result
value for which the IsSuccess()
function returns true
if the call succeeds.ResultNotInitialized
Indicates that the instance has not been initialized. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
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.
bool nn::pia::session::Mesh::IsCompleteBitRateCheck | ( | ) |
Determines whether the bitrate value may be found using the bitrate detection feature.
true
if the bitrate value can be obtained. true
is also returned when detection fails on a timeout, or cancel. bool nn::pia::session::Mesh::IsCompletedCreateMesh | ( | ) |
Checks the completion of CreateMeshAsync
asynchronous processing.
This function checks the completion of asynchronous processes started with CreateMeshAsync
.
true
if the asynchronous process has completed, or false
otherwise. Also returns false
when there has been no asynchronous processing.bool nn::pia::session::Mesh::IsCompletedDestroyMesh | ( | ) |
Checks the completion of DestroyMeshAsync
asynchronous processing.
This function checks the completion of asynchronous processes started with DestroyMeshAsync
.
true
if the asynchronous process has completed, or false
otherwise. Also returns false
when there has been no asynchronous processing.bool nn::pia::session::Mesh::IsCompletedJoinMesh | ( | ) |
Checks the completion of JoinMeshAsync
asynchronous processing.
This function checks the completion of asynchronous processes started with JoinMeshAsync
.
true
if the asynchronous process has completed, or false
otherwise. Also returns false
when there has been no asynchronous processing.bool nn::pia::session::Mesh::IsCompletedLeaveMesh | ( | ) |
Checks the completion of LeaveMeshAsync
asynchronous processing.
This function checks the completion of asynchronous processes started with LeaveMeshAsync
.
true
if the asynchronous process has completed, or false
otherwise. Also returns false
when there has been no asynchronous processing.bool nn::pia::session::Mesh::IsCompletedLeaveMeshWithHostMigration | ( | ) |
Checks the completion of LeaveMeshWithHostMigrationAsync
asynchronous processing.
This function checks the completion of asynchronous processes started with LeaveMeshWithHostMigrationAsync
.
true
if the asynchronous process has completed, or false
otherwise. Also returns false
when there has been no asynchronous processing.
|
inline |
Gets whether the local device is the mesh host.
This function always returns false
if the local device is not joined in a mesh.
true
if the local device is the mesh host, or false
otherwise. nn::Result nn::pia::session::Mesh::JoinMeshAsync | ( | const nn::pia::transport::StationConnectionInfo & | stationConnectionInfo | ) |
Joins a mesh.
This function starts an asynchronous processing required to join the mesh. The started process advances by periodically calling the nn::pia::common::Scheduler::Dispatch
function. Use IsCompletedJoinMesh
to check whether the process has completed and GetJoinMeshResult
to check the result. You can also cancel the process by calling the CancelJoinMeshAsync
function during the process.
If you execute other processes without destroying the Mesh
instance after execution fails, or if you cancel execution using the CancelJoinMeshAsync
function, do so after you first clean up Mesh
by calling Cleanup
. For Internet communication, call it again from the start of the NAT session (nn::pia::inet::NexFacade::StartNatSessionAsync
).
[in] | stationConnectionInfo | Specifies information for connecting to the host of the mesh being joined. |
Result
value for which the IsSuccess()
function returns true
if the station successfully joins the mesh. If this function call fails, one or more of the following Result
values is returned. 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.nn::Result nn::pia::session::Mesh::KickoutStation | ( | nn::pia::StationId | id | ) |
Kicks a station from the mesh.
Only the mesh host can call this function.
A kick notice is conveyed to the station assigned the <tt>StationId</tt> specified in the argument, and that station leaves the mesh upon receiving the notice. 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.
[in] | id | Specifies the station ID assigned to the station being kicked. |
Result
value for which the IsSuccess()
function returns true
if the station is successfully kicked from the mesh. If this function call fails, one or more of the following Result
values is returned. 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.
ResultInvalidArgument
Indicates that the StationId
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.
ResultInProgress
Indicates that the process to kick the station having the StationId
specified in the arguments has already started. Handle appropriately in the application.
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.
nn::Result nn::pia::session::Mesh::LeaveMeshAsync | ( | ) |
Leaves a joined mesh.
Only the mesh clients can call this function.
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. Use <tt>@ref IsCompletedJoinMesh</tt> to check whether the process has completed and <tt>@ref GetJoinMeshResult</tt> to check the result. <b>Note:</b> The asynchronous process never fails if the leave mesh process starts normally.
Result
value for which the IsSuccess()
function returns true
if the mesh is successfully left. If this function call fails, one or more of the following Result
values is returned. 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.nn::Result nn::pia::session::Mesh::LeaveMeshWithHostMigrationAsync | ( | ) |
Leaves a mesh. Also specifies that host migration will start for mesh participants.
Only the mesh host can call this function. This function can be used only when the host migration feature is enabled.
Starts an asynchronous mesh leaving process. The started process advances by periodically calling the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function. Use <tt>@ref IsCompletedLeaveMeshWithHostMigration</tt> to check whether the process has completed and <tt>@ref GetLeaveMeshWithHostMigrationResult</tt> to check the result. <b>Note:</b> The asynchronous process never fails if the leave mesh process starts normally. All session participants are notified that host migration has started within the asynchronous process. The host migration process begins on the stations that received the notification, and the mesh continues under the new mesh host even after communication is terminated with the old mesh host that called this function.
Result
value for which the IsSuccess()
function returns true
if the mesh is successfully left. If this function call fails, one or more of the following Result
values is returned. 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.void nn::pia::session::Mesh::RegisterJoiningMeshApprovalCallback | ( | JoiningMeshApprovalCallback | callback | ) |
Registers the callback used to approve or deny requests received by the host from clients seeking to join the mesh.
The callback function for deciding whether to approve Join
requests is called by the nn::pia::common::Scheduler::Dispatch
function.
Do not include any processes that block for long periods of time in the registering function. The ID token of the station that sent the <tt>Join</tt> request is passed as an argument to the callback function. If you do not register a callback function, <tt>Join</tt> requests are always approved unless the mesh is full.
[in] | callback | Specifies a pointer to the callback function being registered. |
void nn::pia::session::Mesh::RegisterMeshEventCallback | ( | MeshEventCallback | callback | ) |
Registers the callback function that is called when the mesh state changes.
This function registers the callback that is called when the session mesh changes (when a station joins or exits).
The mesh state change callback function is generally called by the <tt>@ref nn::pia::common::Scheduler::Dispatch</tt> function. 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. Do not include any processes that block for long periods of time in the registering function. In addition, do not call <tt>session</tt> module functions within the function that you are registering.
[in] | callback | Specifies a pointer to the callback function being registered. |
nn::Result nn::pia::session::Mesh::RelayEmulation | ( | StationIndex | index1, |
StationIndex | index2, | ||
EmulationType | type | ||
) |
Specifies connection path emulation settings between any two StationIndex
objects when relaying is enabled. (For debugging.)
This function is for debugging. Do not include it in retail products.
When you call this function, make sure that you have enabled the connection path emulation feature by using the Mesh::SetDebugSetting
function.
If EMULATION_TYPE_RELAY
is set, the connection method for the target StationIndex
is always a relay connection (even when, for example, a direct connection is possible).
Call this function when the terminal is not connected to a mesh. 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.
[in] | index1 | Specifies a StationIndex . |
[in] | index2 | Specifies a StationIndex . |
[in] | type | Specifies the connection method emulation setting. |
Result
value indicating success if the setting succeeds. ResultInvalidState
Indicates that relay connections are disabled. Programming error. Fix your program so that this error is not returned.
ResultInvalidArgument
Indicates that the StationIndex
is invalid, or the specified EmulationType
is invalid. Programming error. Fix your program so that this error is not returned.
void nn::pia::session::Mesh::ResetRelayEmulation | ( | ) |
Initializes connection path emulation settings when relay connections are enabled. (For debugging.)
This function is for debugging. Do not include it in retail products.
All connections are initialized to use the connection path emulation configured by the Mesh::RelayEmulation
function. (This is equivalent to setting EMULATION_TYPE_NONE
for all combinations of StationIndex
.)
Call this function when the terminal is not connected to a mesh. 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.
|
static |
(For debugging.) Sets the debugging features for Mesh
.
This function can be called even when a Mesh
instance does not yet exist. Call it before calling the CreateInstance
function to create a Mesh
instance.
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. 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>. If this function is not called, all related debugging features are disabled.
Result
value for which the IsSuccess()
function returns true
. You must make sure that the implementation of this function in your application does not return any errors. If this function call fails, one or more of the following Result
values is returned. ResultInvalidState
Indicates that the function cannot be executed in this state. Returns when the Mesh
instance has already been created. Programming error. Fix your program so that this error is not returned. nn::Result nn::pia::session::Mesh::SetMaxNumOfRelayRoutesAssignedToStation | ( | u16 | num | ) |
Sets the maximum number of forwarding requests that can be assigned to a single station when relaying is enabled.
The library uses this value as a metric when searching for and selecting relay paths. If you do not set a value, the library uses [maximum mesh participants] × [maximum mesh participants] as the default.
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.)
This function is only available when the network topology allows relaying, and Startup
has not yet been called.
[in] | num | Specifies the maximum value. |
Result
value indicating success if the setting succeeds. ResultInvalidState
Indicates that relay connections are disabled or the Startup
function has already been called. Programming error. Fix your program so that this error is not returned. nn::Result nn::pia::session::Mesh::SetMaxRtt | ( | u16 | rtt | ) |
Sets the maximum total RTT for a relay route when relaying is enabled.
The library uses this value as a metric when searching for and selecting relay paths. If you do not set a value, the library uses the default value of nn::pia::session::NN_PIA_SESSION_MAX_RTT_DEFAULT
.
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.)
This function is only available when the network topology allows relaying, and Startup
has not yet been called.
[in] | rtt | Specifies the maximum value. The value is in milliseconds. |
Result
value indicating success if the setting succeeds. ResultInvalidState
Indicates that relay connections are disabled or the Startup
function has already been called. Programming error. Fix your program so that this error is not returned. void nn::pia::session::Mesh::SetSyncClockPulseInterval | ( | s32 | interval | ) |
Specifies the send interval of the synchronization pulse for the synchronous clock.
[in] | interval | Specifies the interval at which the synchronization pulse is sent. The value is in milliseconds. |
nn::Result nn::pia::session::Mesh::Startup | ( | Mesh::StartupSetting & | startupSetting | ) |
Starts the Mesh
.
The use of host migration is set by the bUsingHostMigration
member of the StartupSetting
structure. Set to true
to enable. The default is true
. Specify the name and language code associated with the local station in the pPlayerName
member of StartupSetting
. The name must be no longer than 16 characters (not including the terminating null character). Specify a language code if your application determines the languages of other regions. You can use the value returned by the nn::cfg::CTR::GetLanguage()
function if you want to use the language setting of the system.
You can configure the communication encryption feature in the pCryptoSetting
member of the StartupSetting
structure. Communication is not encrypted if NULL
is specified. The default is NULL
.
You can configure the packet-signing feature in the signatureSetting
member of the StartupSetting
structure. The unsigned option is not allowed for Internet communication. The Startup
function fails if unsigned is specified.
In the pToken
member of the StartupSetting
structure, you can set an identification token that indicates the local host. This identification token is shared with peers during the connection process, and it is associated with and maintained in nn::pia::transport::Station
. You are not required to specify an identification token if you do not need to use one. The default is NULL
.
The Startup
function is the only way to specify and change an identification token that indicates the local host. Note that there is no supported method for changing an identification token while a mesh is in use.
When local communications and host migration are enabled, host migration can begin after detecting a communication problem with the host on the local network. Note that the time period used by the local network to determine communication problems is not related to the maximum allowed silence time in Session
.
If the bitrate detection feature is enabled, you must set the uplinkBitRateLowerLimit
and bitRateCheckPacketSize
members of the StartupSetting
structure. Both members default to an invalid value. Set the minimum bitrate (in bits per second) required by the application in uplinkBitRateLowerLimit
and the IP packet size (in bytes) to use for measurements in bitRateCheckPacketSize
.
[in] | startupSetting | Specifies the settings to use for startup. |
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.
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.
|
virtual |
Prints information that is useful for debugging.
[in] | flag | Specifies the bitwise OR of trace flags. For more information, see the TraceFlag API reference. |
void nn::pia::session::Mesh::TraceStationConnectionInfoList | ( | u64 | flag | ) |
Prints information that is useful for debugging.
[in] | flag | Specifies the bitwise OR of trace flags. For more information, see the TraceFlag API reference. |
void nn::pia::session::Mesh::UnregisterJoiningMeshApprovalCallback | ( | ) |
Unregisters the registered Join
request callback function for approving or denying the request.
void nn::pia::session::Mesh::UnregisterMeshEventCallback | ( | ) |
Unregisters the registered callback function for mesh state changes.