6.19.4. Directly Controlling Meshes for Internet Communications

This section describes procedures and important information for using mesh networks for PiaInet Internet communications.

Initialization Order

When using PiaInet, initialize the modules in the following order.

  1. Initialize PiaCommon.
  2. Initialize NEX.
  3. Initialize PiaInet.
  4. Initialize PiaTransport.
  5. Initialize PiaSession (for the mesh network).
  6. Connect to the Internet.
  7. Log in to NEX.
  8. Configure the NEX game server information.
  9. Call inet::NexFacade::Startup().
  10. Call inet::NexFacade::StartNatSessionAsync().
  11. Start PiaSession (for the mesh network).
  12. Create and participate in the mesh network using PiaSession.

For more information about each of these processes, see the appropriate pages of the programming manual.

Configuring and Deleting NEX Game Server Information

Call the inet::NexFacade::Bind() function to configure NEX game server information. Call the inet::NexFacade::Unbind() function to delete (unbind) NEX game server information.

When configuring NEX game server information, make sure to call the Bind() function after logging in to the game server but before starting NexFacade. The Bind() function takes a pointer to an inet::NexFacade::LoginInfo object.

When deleting NEX game server settings, make sure to call the Unbind() function after cleaning up NexFacade, but before logging out of the NEX game server.

NexFacade Startup

Start NexFacade after you have configured the NEX game server information. Call the inet::NexFacade::Startup function each time you log in.

Code 6-69. Starting NexFacade
// The matchmaking client bound with the certificate for using the matchmaking service.
result = nn::pia::inet::NexFacade::GetInstance()->Startup(s_pMatchMakingClient);
PIA_ASSERT(result.IsSuccess());

Starting a NAT Session

Start a NAT session (P2P communication) by calling the NexFacade::StartNatSessionAsync function. The NexFacade::StartNatSessionAsync function is executed asynchronously. To advance processing, call the NEX dispatch function and the Pia dispatch function at a frequency of once or twice per game frame. This process is handled in a background thread in Pia. Other threads must be put to sleep as necessary to ensure that this background thread gets sufficient CPU time. Use the NexFacade::IsCompletedStartNatSession function to check whether processing has completed, and the NexFacade::GetStartNatSessionResult function to check the result.

The NexFacade::StartNatSessionAsync function performs DNS name resolution to determine the NAT type only the first time it is called after the application starts. This name resolution runs in the background. If the WAN cable on the router is unplugged before name resolution is complete, this process may take 30 or more seconds to finish because the router waits for name resolution to time out. You cannot cancel this name resolution process. As a result, when calling the NexFacade::CancelStartNatSessionAsync function at such times, the cancel is processed after name resolution, and cancel processing can take time to complete.

Code 6-70. Starting a NAT Session
// Start the NAT session.
result = nn::pia::inet::NexFacade::GetInstance()->StartNatSessionAsync();
PIA_ASSERT(result.IsSuccess());

// Advance the process.
while (!nn::pia::inet::NexFacade::GetInstance()->IsCompletedStartNatSession()) {
    nn::nex::Scheduler::GetInstance()->Dispatch(NEX_DISPATCH_TIMEOUT);
    nn::pia::common::Scheduler::GetInstance()->Dispatch(PIA_DISPATH_TIMEOUT);
    // Run once or twice in each game frame.
}
// Check the processing result.
result = nn::pia::inet::NexFacade::GetInstance()->GetStartNatSessionResult();
if (result.IsFailure()) {
    // Error handling.
}

/*
Use the NEX matchmaking API to joint the matchmaking session.
Start PiaSession and join the P2P mesh network.
*/

Joining a Matchmaking Session

Use the NEX matchmaking API to join a matchmaking session. The NEX matchmaking API provides functions for creating, searching, and joining matchmaking sessions. It also provides an auto-matchmaking feature. After you have joined the session, start an instance of the Mesh class, create the P2P mesh network, and start game communications. For more information about joining matchmaking sessions, see the NEX programming manual.

Finalization Order

When using PiaInet, finalize the modules in the following order.

  1. Leave and destroy the session using PiaSession (used for the mesh network).
  2. Clean up PiaSession (used for the mesh network).
  3. Call inet::NexFacade::StopNatSession().
  4. Call inet::NexFacade::Cleanup().
  5. Delete NEX game server information settings.
  6. Log out from NEX.
  7. Disconnect from the Internet.
  8. Finalize PiaSession.
  9. Finalize PiaTransport.
  10. Finalize PiaInet.
  11. Finalize NEX.
  12. Finalize PiaCommon.

For more information about each of these processes, see the appropriate pages of the programming manual.