7.3. 基本機能 - 初期化と終了処理

PiaSession を使用する場合の初期化と終了処理について説明します。

初期化処理

事前処理が正しく実行できたら、PiaSession の初期化処理を行います。Session クラスのインスタンス生成時に渡す Setting 構造体のメンバ pNetworkFactory  には、使用するネットワーク方式に合わせた NetworkFactory 派生クラスのインスタンスを設定する必要があります。networkTopology には使用するネットワークトポロジーを指定します。インターネット以外のネットワーク方式の場合にはnn::pia::session::NetworkTopology_FullMesh  以外のネットワークトポロジーを設定することはできません。browsedSessionInfoListNum にはセッション検索時に検索できたセッションの情報を格納するリストのサイズを設定する必要があります。設定した値の分、セッション情報を格納するためのメモリを内部で確保します。 ブラウズマッチメイクを行う場合は 1 以上の値を設定します。ランダムマッチメイクのみを行う場合は 0 を設定しても問題ありません。コミュニティを使用する場合、browsedCommunityInfoListNum にはコミュニティ検索時に検索できたコミュニティの情報を格納するリストのサイズを設定します。設定した値の分、セッション情報を格納するためのメモリを内部で確保します。コミュニティ機能を使用しない場合は 0 を設定します。bitRateCheckMode にはビットレート判定機能を有効にするかどうかを設定します。デフォルトは無効に設定されています。

Setting 構造体および NetworkFactory 派生クラスのインスタンスは、Session クラス初期化処理時にのみ参照、使用されます。初期化処理後はインスタンスを破棄しても問題ありません。

コード 7-1. PiaSession の初期化処理
// 事前処理は済ませておきます
 
// Setting 構造体の設定
nn::pia::session::Session::Setting sessionSetting;

// transport::NetFactory の派生クラス
nn::pia::inet::NexNetworkFactory nexFactory; // インターネットマッチメイク用 NetworkFactory
nn::pia::local::UdsNetworkFactory udsFactory; // ローカルマッチメイク用 NetworkFactory

if (networkType == INTERNET)
{
    // インターネットマッチメイクの場合は NexNetworkFactory
    sessionSetting.pNetworkFactory = &nexFactory;
}
else if (networkType == LOCAL)
{
    // ローカルマッチメイクの場合は UdsNetworkFactory
    sessionSetting.pNetworkFactory = &udsFactory;
}

// ネットワークトポロジの設定
sessionSetting.networkTopology = nn::pia::session::NetworkTopology_FullMesh;  
 
// セッションの検索結果のリストサイズ
sessionSetting.browsedSessionInfoListNum = 16;

// コミュニティの検索結果のリストサイズ
sessionSetting.browsedCommunityInfoListNum = 20;

// ビットレート判定機能の設定
sessionSetting.bitRateCheckMode = nn::pia::session::BitRateCheck_Disable;

result = nn::pia::session::Initialize();
if (result.IsFailure())
{
    // エラー処理
    // 適切なタイミングで呼び出している限り、失敗しません
}
result = nn::pia::session::BeginSetup();
if (result.IsFailure())
{
    // エラー処理
    // 適切なタイミングで呼び出している限り、失敗しません
}
result = nn::pia::session::Session::CreateInstance(sessionSetting);
if (result.IsFailure())
{
    // エラー処理
    // 適切なタイミング、適切に設定された Setting 構造体を渡して呼び出す限り、失敗しません
}
result = nn::pia::session::EndSetup();
if (result.IsFailure())
{
    // エラー処理
    // 適切なタイミングで呼び出している限り、失敗しません
}
 
/* Setting 構造体に設定した NetworkFactory 派生クラスのインスタンスは、初期化処理後に参照されることはありません。*/


スタートアップ

セッションの構築/参加を行う前にスタートアップを行います。スタートアップでは nn::pia::session::Session::StartupSetting を継承した構造体を用いて、自分自身のステーションと関連付ける名前の設定などを行えます。

インターネットマッチメイク時には nn::pia::inet::NexSessionStartupSetting、ローカルマッチメイク時には nn::pia::local::LocalSessionStartupSetting、LAN マッチメイク時には nn::pia::lan::LanSessionStartupSetting を使用します。

nn::pia::session::Session::StartupSetting

maxSilenceTime には許容する最大無通信時間、keepAliveSendingInterval にはキープアライブ送信間隔を設定し、キープアライブ設定(切断耐性)を調節できます。

pToken には、セッションへの参加処理が完了した時点で各セッション参加者から取得可能なステーション識別トークンを設定できます。詳しくは 7.14. 応用機能 - ステーション識別トークン を参照してください。

nn::pia::inet::NexSessionStartupSetting

isHostMigrationEnabled にはホストマイグレーションを有効にするかどうかを設定します。

playerInfo にはプレイヤー情報用の nn::pia::transport::Station::PlayerInfo を設定することで自分自身のステーションとプレイヤー情報を関連付けることができます。プレイヤー情報にはプレイヤー名、言語タイプ、プレイヤーIDが含まれますが、プレイヤーIDは設定の必要がありません。関連付けたプレイヤー情報はメッシュ内のステーション間で共有されます。プレイヤー名の長さは20文字(NULL終端を含めない)以内である必要があります。

ビットレート判 定機能を使用する場合には、uplinkBitRateLowerLimit にアプリケーションが要求するビットレートの下限値、bitRateCheckPacketSize にビットレート測定時に送出する IP パケットのサイズ、isBitRateCheckSkipped にビットレート判定の処理をスキップするかどうか、bitRateMeasuringSpan にビットレートの計測にかける時間を設定します。詳しくは 7.20. 応用機能 - ビットレート判定機能 を参照してください

cryptoMode には、 nn::pia::common::CryptoSetting::Mode の値を渡し、送受信のパケットを暗号化するための設定を行います。暗号化を有効にした場合には、ゲームサーバーから割り当てられるセッション毎に異なる鍵を暗号鍵として使用します。

mtuSize にはパケットの MTU を指定します。inet::MtuSizeMin から inet::MtuSizeMax までの値を指定できますが、特別な事情が無ければ inet::DefaultMtuSize を指定することを推奨します。

nn::pia::local::LocalSessionStartupSetting

playerInfo にはプレイヤー情報用の nn::pia::transport::Station::PlayerInfo を設定することで自分自身のステーションとプレイヤー情報を関連付けることができます。プレイヤー情報にはプレイヤー名、言語タイプ、プレイヤーIDが含まれますが、プレイヤーIDは設定の必要がありません。関連付けたプレイヤー情報はメッシュ内のステーション間で共有されます。プレイヤー名の長さは20文字 (NULL終端を含めない)以内である必要があります。

CTR のローカル通信機能では「いっしょにあそんだ人の記録」をサポートしていないので、isAddRecentPlayRecordEnabled の設定は不要です。

signatureKeyData には、署名鍵を設定します。署名鍵は 32 バイト以内である必要があります。signatureKeyDataSize には、署名鍵のバイト数を設定します。署名を無効にする場合は 0 を設定します。

nn::pia::lan::LanSessionStartupSetting

playerInfo にはプレイヤー情報用の nn::pia::transport::Station::PlayerInfo を設定することで自分自身のステーションとプレイヤー情報を関連付けることができます。プレイヤー情報にはプレイヤー名、言語タイプ、プレイヤーIDが含まれますが、プレイヤーIDは設定の必要がありません。関連付けたプレイヤー情報はメッシュ内のステーション間で共有されます。プレイヤー名の長さは20文字 (NULL終端を含めない)以内である必要があります。

cryptoMode には、 nn::pia::common::CryptoSetting::Mode の値を渡し、送受信のパケットを暗号化するための設定を行います。暗号化を有効にした場合には、セッション毎に異なる鍵をライブラリ内で生成し、暗号鍵として使用します。

参考:

 LANマッチメイクではライブラリ内で自動的に「いっしょに遊んだ記録」に追加しません。


コード 7-2. セッションのスタートアップ(インターネットマッチメイク時)
// 識別トークンの設定
nn::pia::transport::Station::IdentificationToken token;

// プレイヤー情報の設定
nn::pia::transport::Station::PlayerInfo playerInfo;
nns::pia::Session_GetLocalPlayerInfo(&playerInfo);

// スタートアップ設定
nn::pia::inet::NexSessionStartupSetting startupSetting;
startupSetting.isHostMigrationEnabled = true; // ホストマイグレーション設定
startupSetting.playerInfo[0].Copy(&playerInfo); // 通信に使用するプレイヤー情報
startupSetting.isPlayersCountedAsParticipants = true; // プレイヤー数とセッション参加者数が一致するかどうか
startupSetting.maxSilenceTime = 10000; // 最大無通信時間
startupSetting.keepAliveSendingInterval = 500; // キープアライブ送信間隔
startupSetting.pToken = &token; // 識別トークン
startupSetting.uplinkBitRateLowerLimit = 200; // アプリケーションが要求するビットレート。単位は bps。
startupSetting.bitRateCheckPacketSize = 1024; // ビットレート測定時に使用する IP パケットのサイズ。単位はバイト。
startupSetting.isBitRateCheckSkipped = false; // ビットレート判定処理をスキップするかどうか。
startupSetting.bitRateMeasuringSpan = 1000; // ビットレート測定にかける時間。単位は msec。
startupSetting.cryptoMode = nn::pia::common::CryptoSetting::Mode_Aes128; // 暗号化設定
startupSetting.mtuSize = nn::pia::inet::DefaultMtuSize;

// スタートアップ
result = nn::pia::session::Session::GetInstance()->Startup(startupSetting);
if (result.IsFailure())
{
    // エラー処理
}
 
/* スタートアップに成功した場合にセッション構築処理、参加処理を行えます */


nn::pia::session::Session::StartupSetting 及び、それを継承した構造体の各パラメータの初期値、最小値、最大値は次のようになっています。

構造体 パラメータ 初期値 最大値 最小値

nn::pia::session::Session::StartupSetting

maxSilenceTime
session::SessionMaxSilenceTimeDefault session::SessionMaxSilenceTimeMax session::SessionMaxSilenceTimeMin
keepAliveSendingInterval
session::SessionKeepAliveIntervalDefault - -
pToken
NULL

nn::pia::inet::NexSessionStartupSetting

isHostMigrationEnabled
true
 

cryptoMode
common::CryptoSetting::Mode_Aes128

playerInfo
transport::Station::PlayerInfo()

isPlayersCountedAsParticipants
true

uplinkBitRateLowerLimit
session::SessionInvalidUplinkBitRateLowerLimit - -
bitRateCheckPacketSize
0

isBitRateCheckSkipped
false

bitRateMeasuringSpan
1000 - -
isAddRecentPlayRecordEnabled
true

isOnlineDeclarationSkipped
false

mtuSize
inet::DefaultMtuSize inet::MtuSizeMax inet::MtuSizeMin

nn::pia::local::LocalSessionStartupSetting

 
signatureKeyData
0 埋め

signatureKeyDataSize
0 common::SignatureSetting::SignatureKeyDataSizeMax
playerInfo
transport::Station::PlayerInfo()

isAddRecentPlayRecordEnabled
true

maxSilenceTime
local::MaxSilenceTime session::SessionMaxSilenceTimeMax session::SessionMaxSilenceTimeMin
keepAliveSendingInterval
local::KeepAliveSendingInterval

nn::pia::lan::LanSessionStartupSetting

cryptoMode
common::CryptoSetting::Mode_Aes128

playerInfo
transport::Station::PlayerInfo()

isPlayersCountedAsParticipants
true

maxSilenceTime
lan::MaxSilenceTime session::SessionMaxSilenceTimeMax session::SessionMaxSilenceTimeMin
keepAliveSendingInterval
lan::KeepAliveSendingInterval

クリーンアップ

セッションの離脱/破棄を行った場合やセッションから切断された後は、クリーンアップを行ってセッション開始前の状態に戻します。クリーンアップを行った後に再度スタートアップを行うことで新たなセッションの構築/参加が可能になります。完全に通信を終える場合でも、クリーンアップを終えてから後述する終了処理を行います。

コード 7-3. セッションのクリーンアップ
// クリーンアップ
nn::pia::session::Session::GetInstance()->Cleanup();

終了処理

PiaSession の利用を終える際には終了処理を行います。各モジュールの終了処理は初期化処理とは逆順に行います。

コード 7-4. PiaSession の終了処理
// Session インスタンスの破棄処理
nn::pia::session::Session::GetInstance()->DestroyInstance();

// PiaSession 終了処理
nn::pia::session::Finalize();