6.3. Basic Features - Initializing and Finalizing

This section describes the initialization and finalization processes when using PiaSession.

Initialization

If preprocessing has been run correctly, PiaSession can be initialized. You must set the NetworkFactory derived instance that matches the type of network to use in the pNetworkFactory member of the Setting structure, which is passed when an instance of the Session class is created. When searching, you must set the size of the list that stores the information found in the search in browsedSessionInfoListNum. The value you set allocates a corresponding amount of memory to store the session information. Set a value of 1 or greater for browse-and-select matchmaking. You can set a value of 0 when using random matchmaking only. Specify whether to enable the bit rate detection feature in the bitRateCheckMode member variable. The default setting is disabled.

The Setting structure and the NetworkFactory derived class instance are only accessed and used when the Session class is initialized. After initialization, it is okay to destroy their instances.

Code 6-1. PiaSession Initialization Process
// Preprocessing already completed.
 
// Configure the Setting structure.
nn::pia::session::Session::Setting sessionSetting;

// The transport::NetFactory derived class.
nn::pia::inet::NexNetworkFactory nexFactory; // NetworkFactory for Internet communication.
nn::pia::local::UdsNetworkFactory udsFactory; // NetworkFactory for UDS communication.

if (networkType == INTERNET)
{
    // NexNetworkFactory in the case of Internet communication.
    sessionSetting.pNetworkFactory = &nexFactory;
}
else if (networkType == LOCAL)
{
    // UdsNetworkFactory in the case of UDS communication.
    sessionSetting.pNetworkFactory = &udsFactory;
}

// Network topology settings.
sessionSetting.networkTopology = nn::pia::session::NetworkTopology_FullMesh;  
 
// Size of the list of session search results.
sessionSetting.browsedSessionInfoListNum = 16;

// Bit rate detection feature settings.
sessionSetting.bitRateCheckMode = nn::pia::session::BitRateCheck_Disable;

result = nn::pia::session::Initialize();
if (result.IsFailure())
{
    // Error processing.    // Will not fail if called at the appropriate time.
}
result = nn::pia::session::BeginSetup();
if (result.IsFailure())
{
    // Error processing.
    // Will not fail if called at the appropriate time.
}
result = nn::pia::session::Session::CreateInstance(sessionSetting);
if timing(result.IsFailure())
{
    // Error processing.
    // Will not fail if called at the appropriate time with the appropriately configured Setting structure passed.
}
result = nn::pia::session::EndSetup();
if (result.IsFailure())
{
    // Error processing.
    // Will not fail if called at the appropriate time.
}
 
/* The instance of the NetworkFactory derived class configured in the Setting structure will never be referenced after initialization. */

Startup

Perform startup before creating and joining a session. In startup, you can use a nn::pia::session::Session::StartupSetting object to associate a name with the local station and configure whether to use packet encryption.

Specify whether to enable host migration in bUsingHostMigration.

Specify nn::pia::transport::Station::PlayerName for the pPlayerName parameter to associate a name with the local station. This name is shared among other stations in the mesh network. The name must be no longer than 16 characters (not including the terminating null character).

Specify the value of nn::pia::common::CryptoSetting::Mode in cryptoMode to set the encryption of packets sent and received. This is only enabled for Internet communication, but when encryption is enabled, the signature keys obtained from the game server are automatically used as encryption keys.

Specify the maximum allowed silence time in maxSilenceTime and the interval at which to send keep-alive packets in keepAliveSendingInterval to adjust the keep-alive settings (the system's tolerance for disconnections).

You can set the station identification token received from each of the session participants after the process of joining the session has been completed in pToken. For more information, see 6.14. Advanced Features - Station Identification Tokens.

To use the bit rate detection feature, set the minimum bit rate required by the application in uplinkBitRateLowerLimit, the size of IP packet to send when measuring the bit rate in bitRateCheckPacketSize, whether bit rate detection processing is skipped in isSkipBitRateCheck, and the time taken for bit rate measurement in bitRateMeasuringSpan. For more information, see 6.20. Advanced Features - Bit Rate Detection Feature.

 
Code 6-2. Starting the Session
// Identification token setting.
nn::pia::transport::Station::IdentificationToken token;

// Player name setting.
nn::pia::transport::Station::PlayerName playerName;

// Startup setting.
nn::pia::session::Session::StartupSetting startupSetting;
startupSetting.bUsingHostMigration = true; // Host migration setting.
startupSetting.pPlayerName = &playerName; // Player name to use for communication.
startupSetting.cryptoMode = nn::pia::common::CryptoSetting::MODE_AES_128; // Encryption setting.
startupSetting.maxSilenceTime = 10000; // Maximum time without communication.
startupSetting.keepAliveSendingInterval = 500; // Interval for sending keep-alive signals.
startupSetting.pToken = &token; // Identification token.
startupSetting.uplinkBitRateLowerLimit = 200; // Bit rate required by the application. In bits per second.
startupSetting.bitRateCheckPacketSize = 1024; // IP packet size to use when measuring the bit rate. The value is in bytes.
startupSetting.isSkipBitRateCheck = false; // Whether to skip the bit rate detection process.
startupSetting.bitRateMeasuringSpan = 1000; // Time to spend measuring the bit rate. The units are in milliseconds.

// Startup.
result = nn::pia::session::Session::GetInstance()->Startup(startupSetting);
if (result.IsFailure())
{
    // Error processing.
}
 
/* If startup has succeeded, sessions can be created and joined. */

 

The initial values for StartupSetting are as follows.

StartupSetting Parameters Initial Value Maximum Value Minimum Value
bUsingHostMigration
true    
pPlayerName
NULL    
cryptoMode
common::CryptoSetting::MODE_NOTHING    
maxSilenceTime
session::NN_PIA_SESSION_MAX_SILENCE_TIME_DEFAULT session::NN_PIA_SESSION_MAX_SILENCE_TIME_MAX session::NN_PIA_SESSION_MAX_SILENCE_TIME_MIN
keepAliveSendingInterval
session::NN_PIA_SESSION_INVALID_UPLINK_BIT_RATE_LOWER_LIMIT    
pToken
NULL    
uplinkBitRateLowerLimit
session::NN_PIA_SESSION_INVALID_UPLINK_BIT_RATE_LOWER_LIMIT    
bitRateCheckPacketSize
0    
isSkipBitRateCheck
false    
bitRateMeasuringSpan
1000    

Cleanup

When leaving, disconnecting from, or destroying a session, perform cleanup operations afterward to restore the system to its state before a session starts. After performing cleanup, if you perform startup once more, you can create or join new sessions. Even when communication completely fails, proceed to the finalization process noted below after cleanup is done.

Code 6-3. Session Cleanup
// Cleanup.
nn::pia::session::Session::GetInstance()->Cleanup();

Finalization

When you are finished using PiaSession, perform finalization. Perform the finalization process for each module in the reverse order of the initialization process.

Code 6-4. Finalizing PiaSession
// Destruction of the Session instance.
nn::pia::session::Session::GetInstance()->DestroyInstance();

// Finalization of PiaSession.
nn::pia::session::Finalize();