CTR NEX API Reference
nn::nex::NetZ クラス

NetZのランタイム機能をカプセル化するクラスです。 [詳解]

#include <NetZ/src/Core/Facade/NetZ.h>

ProductFacadeを継承しています。

公開メンバ関数

 NetZ ()
 NetZクラスのインスタンスの存在はただ一つのみ許されます。 [詳解]
 
virtual ~NetZ ()
 NetZインスタンスが破棄されたとき、全てのNetZ関連のインスタンスはシャットダウンされます。 [詳解]
 
virtual qResult GetFatalError () const
 NetZ内部で発生しているフェイタルエラーを取得します。 [詳解]
 
virtual qBool GetTerminateImmediately ()
 NetZ::Terminate の終了モードを取得します。 [詳解]
 
virtual qBool IsValid () const
 NetZインスタンスが正常かどうかを返します。 [詳解]
 
virtual void SetTerminateImmediately (qBool immediately)
 NetZ::Terminate の終了モードを設定します。 [詳解]
 
virtual qBool Terminate (CallContext *pContext)
 オブジェクトは破棄せずに P2P セッションの終了処理を行います。 [詳解]
 

静的公開メンバ関数

static NetZGetInstance ()
 NetZインスタンスへのポインタを返します。 [詳解]
 
static void SetDOClassInitializationCallback (InitDOClassesFunction fInitDOClasses)
 DO クラス初期化関数を登録します。 [詳解]
 
static void SetNetworkTopology (NetworkTopology::Mode eSelectedTopology)
 NetZが確立するネットワークトポロジーのタイプを定義します。 [詳解]
 

詳解

NetZのランタイム機能をカプセル化するクラスです。

NetZを使用するためにはインスタンスを生成しなければなりません。 インスタンスを破棄するとNetZ機能は終了します。

ユーザーDO を使用する(ddlファイルを作成する必要がある場合)場合、DDLコンパイラによって生成される InitDOClasses() を NetZ::SetDOClassInitializationCallback() でセットしてください。 ユーザーDO を使用しない場合は特別な処理は不要です。 ホストマイグレーション拡張機能を使用する場合は、ユーザーDOを使用しない場合でも InitDOClasses() の設定が必要です。

NetZインスタンスはローカルセッションオブジェクトを保持するので、 セッションごとにNetZインスタンスを作りなおす必要があります。 Session::CreateSessionSession::JoinSession の処理に失敗した場合でも、 再度セッションに参加するにはNetZインスタンスを作りなおす必要があるので注意してください。

構築子と解体子

nn::nex::NetZ::NetZ ( )

NetZクラスのインスタンスの存在はただ一つのみ許されます。

このインスタンスが破棄されれば、現在作成されているセッションは終了され、 ランタイム機能は停止します。

戻り値一覧:
作成されたNetZオブジェクトを返します。 2つ以上のNetZオブジェクトを作成するとSYSTEMERROR_GEN_MULTIPLE_INSTANCESが シグナルされます。
virtual nn::nex::NetZ::~NetZ ( )
virtual

NetZインスタンスが破棄されたとき、全てのNetZ関連のインスタンスはシャットダウンされます。

デストラクタを呼び出す前に、必ず Terminate を実行して P2P セッションの終了を行なってください。 Terminate を呼び出さずに、デストラクタが呼ばれた場合、内部でTerminate を呼び出します。 Terminate も参照してください。

参照
Terminate

関数詳解

virtual qBool nn::nex::NetZ::Terminate ( CallContext pContext)
virtual

オブジェクトは破棄せずに P2P セッションの終了処理を行います。

NetZのデストラクタを呼ぶ前に、本関数を必ず実行してください。 本関数は通信状況によっては完了までに遅くとも5秒程度かかることがあります。 処理時間の要因については、プログラミングマニュアルを参照してください。

終了処理によって、すべての複製オブジェクトが破棄されます。 アプリケーションによる複製オブジェクトへの参照(例えば、RefTemplateまたはDuplicatedObject::Refによって 作成されたもの)が残っていても、強制的に破棄されます。 そのため、本関数を呼び出す前に、必ずアプリケーションで保持しているずすべての複製オブジェクトへの参照を開放してください。

この複製オブジェクトにはローカルセッションオブジェクトが含まれ、 そして、それは現在のセッションのシャットダウン中に NetZによって削除されます。 したがって、他のセッションに参加するためには、一旦現在のNetZオブジェクトを 削除して、新たなNetZを作る必要があります。 Session::CreateSessionSession::JoinSession の処理に失敗 した場合にもローカルセッションオブジェクトが残っている可能性があるため、 NetZを作りなおす必要があります。

この関数が非同期に呼ばれた場合、 P2P セッションがシャットダウンプロセスにいる間も 処理を継続できます。

引数
pContext呼び出しのCallContext へのポインタ
戻り値一覧:

true P2P セッションが正常に強制終了された場合に返します。

false P2P セッションが異常に強制終了された場合、またはエラーが起こった場合に返します。

static NetZ* nn::nex::NetZ::GetInstance ( )
static

NetZインスタンスへのポインタを返します。

NetZオブジェクトを操作するためには、この関数が返す参照を使用して下さい。

戻り値
NetZインスタンスへのポインタ。
virtual qBool nn::nex::NetZ::IsValid ( ) const
virtual

NetZインスタンスが正常かどうかを返します。

NetZインスタンスが2つ以上作成されると異常になります。


戻り値一覧:

true NetZインスタンスが正常な場合に返ります。

false NetZインスタンスが異常な場合、またはエラーが起こった場合に返します。

virtual qResult nn::nex::NetZ::GetFatalError ( ) const
virtual

NetZ内部で発生しているフェイタルエラーを取得します。

NetZインスタンス作成後、毎フレームに1度の頻度で実行し、 フェイタルエラーが発生していないかどうかをチェックしてください。 NetZ::Terminate 中は本関数でエラーチェックを行う必要はありません。

何らかのフェイタルエラーが発生している場合には、失敗を示す qResult が返ります。

本関数の返り値のハンドリング方法は以下のとおりです。

  • フェイタルエラーが発生しているかどうかは、本関数の返り値を QFAILED を使ってチェックするか、false と比較してください。
  • 本関数が返す qResult が失敗を示す場合は何らかのフェイタルエラーが発生しているので、エラーを保存して速やかに NetZ を破棄し、 ErrorCodeConverter::ConvertToNetworkErrorCode で取得できるエラーコードを画面に表示してください。
  • 本関数が返す qResult が成功を示す場合は、アプリケーションで特別なハンドリングを行う必要はありません。

本関数で取得できるqResultは以下のとおりです。

戻り値
内部で発生したフェイタルエラー
参照
ErrorCodeConverter::ConvertToNetworkErrorCode, QFAILED, DOCoreErrorCode::ErrorCode
virtual void nn::nex::NetZ::SetTerminateImmediately ( qBool  immediately)
virtual

NetZ::Terminate の終了モードを設定します。

ホストがホストの権限を他のステーションへ移譲するときや、DOのマスターを他のステーションへ移譲するときに、 NetZ::Terminate の処理時間が5秒程度かかることがあります。

強制終了モードへの変更により、1秒程度で処理を終えることができます。 ただし、通常の切断処理が行われないため、通信相手にはキープアライブのタイムアウトが発生してこちらのステーションがネットワークから切断されたように見える場合があります。 そのため、通常の終了シーケンスで設定することは控えてください。

以下の条件で強制終了モードに自動設定されます。

初期値は通常終了モードです。 本設定は、NetZインスタンス毎に保持されます。

引数
[in]immediatelytrueを指定すると強制終了モードになります。falseを指定すると通常終了モードになります。
参照
Core::SetTerminateImmediately(), Session::GameOver(), Session::DestroySession()
virtual qBool nn::nex::NetZ::GetTerminateImmediately ( )
virtual

NetZ::Terminate の終了モードを取得します。

戻り値
NetZ::Terminate の終了モードが強制終了モードであればtrue、通常終了モードであればfalseが返ります。
static void nn::nex::NetZ::SetNetworkTopology ( NetworkTopology::Mode  eSelectedTopology)
static

NetZが確立するネットワークトポロジーのタイプを定義します。

NetZファサードオブジェクトの作成前にこの関数を使用すれば、 選択したタイプのトポロジーを使用したNetZネットワークトポロジーが確立されます。

デフォルトのネットワークトポロジーは、すべてのステーションがセッションに 参加すると相互に直接接続する典型的な P2P ネットワークです。 このコマンドを使用すれば、NetZにサーバークライアントネットワークを確立するように 指定することが出来ます。サーバークライアントネットワークでは、セッションマスターは すべての参加者にゲームメッセージを送るサーバーになります。 ハイブリッドネットワークでは、Peer2Peerネットワークをベースに、 相互に直接接続できないステーション間の通信をセッションマスター経由で通信します。

引数
eSelectedTopologyP2P セッションが確立するネットワークトポロジーです。 この引数は Peer2Peer、ClientServer、Hybridのいずれかです。
static void nn::nex::NetZ::SetDOClassInitializationCallback ( InitDOClassesFunction  fInitDOClasses)
static

DO クラス初期化関数を登録します。

NetZオブジェクトのコンストラクト時にセットしたDO クラス初期化関数が呼び出されます。 ユーザーDO 機能を使用する場合は、DDLコンパイラによって生成された InitDOClasses() をセットしてください。 ユーザーDO 機能を使用しない場合は、本関数を呼び出す必要はありません。

引数
fInitDOClassesDO クラス初期化関数