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

ゲームサーバーとの通信処理に対する CallContext クラスです。 [詳解]

#include <RendezVous/Core/src/Common/ProtocolCallContext.h>

+ nn::nex::ProtocolCallContext の継承関係図

公開型

typedef void(* CompletionCallback) (CallContext *, const UserContext *)
 CompletionCallback を定義します。 [詳解]
 
enum  Flags { ,
  DeleteOnCompletion = 0x02,
  OneWayCall = 0x04,
  SendUnreliableMessage = 0x08
}
 CallContext に使用可能な各種フラグを列挙します。 [詳解]
 
enum  State {
  Available,
  CallInProgress,
  CallSuccess,
  CallFailure,
  CallCancelled
}
 CallContext の状態を列挙します。 [詳解]
 

公開メンバ関数

RefCountedObjectAcquireRef ()
 参照カウントを 1 増加させます。
 
qBool Cancel ()
 この CallContext に関連付けられている非同期処理をキャンセルします。 [詳解]
 
void ClearFlag (qUnsignedInt32 uiFlag)
 SetFlag を使用して設定されたフラグをクリアします。 [詳解]
 
qBool FlagIsSet (qUnsignedInt32 uiFlag) const
 特定のフラグが設定されているかどうかを返します。 [詳解]
 
virtual qBool FlagsAreValid () const
 現在使用されているフラグの組み合わせが有効かどうかを返します。 [詳解]
 
qResult GetOutcome () const
 非同期処理の結果を qResult として取得します。 [詳解]
 
State GetState () const
 CallContext の現在の状態を返します。 [詳解]
 
const UserContextGetUserContext (size_t iIndex) const
 この CallContext に関連付けられている UserContext を返します。 [詳解]
 
void RegisterCompletionCallback (CompletionCallback pfCompletionCallback, const UserContext &oContext, qBool bAddToEnd=true)
 この CallContext の完了時に実行するコールバック関数を設定します。 [詳解]
 
void RegisterCompletionCallback (CallbackRoot *pCallback, qBool bCallOnSuccess=true, qBool bAddToEnd=true)
 この CallContext の完了時に実行するコールバックオブジェクトを設定します。 [詳解]
 
template<typename TCallback >
void RegisterCompletionCallbackGeneric (const TCallback &callback, qBool deleteCallbackAfterCall=false, qBool bAddToEnd=true)
 この ProtocolCallContext の完了時に実行するコールバックを設定します。 [詳解]
 
void ReleaseRef ()
 参照カウントを 1 減少させます。0 になるときに自分自身を delete します。
 
qBool Reset ()
 CallContext の状態を利用可能に再設定します。 [詳解]
 
void SetFlag (qUnsignedInt32 uiFlag)
 非同期処理に使用するフラグを設定します。 [詳解]
 
void SetTimeout (TimeInterval tiTimeout)
 非同期処理のタイムアウトをセットします。 [詳解]
 
void SetUserContext (size_t iIndex, const UserContext &oUserContext)
 この CallContext に関連付けられている UserContext を設定します。 [詳解]
 
void Trace (qUnsignedInt64 uiTraceFlags=TRACE_ALWAYS)
 この CallContext オブジェクトの内容をトレースします。 リリースモードで実行されると自動的に無効になります。 [詳解]
 
qBool Wait (qUnsignedInt32 uiTimeout=WAIT_INFINITE_TIMEOUT)
 非同期処理が完了する、またはタイムアウトを越えるまで内部処理を進め、待機します。 [詳解]
 
qBool WaitWithoutDispatch (qUnsignedInt32 uiTimeout=WAIT_INFINITE_TIMEOUT)
 非同期処理が完了する、またはタイムアウトを越えるまで待機します。 [詳解]
 

詳解

ゲームサーバーとの通信処理に対する CallContext クラスです。

ゲームサーバーとの通信処理に対する CallContext クラスです。NEX でゲームサーバーと通信するような 非同期処理関数には、有効な ProtocolCallContext クラスオブジェクトを渡す必要があります。

タイムアウト時間を設定する場合 30 秒よりも短い時間を指定しないようにしてください。

型定義メンバ詳解

typedef void(* nn::nex::CallContext::CompletionCallback) (CallContext *, const UserContext *)
inherited

CompletionCallback を定義します。

処理完了時に特定のユーザー定義関数が呼び出されるように、CompletionCallback を RegisterCompletionCallback() で登録します。

参照
RegisterCompletionCallback, RegisterCompletionCallback

列挙型メンバ詳解

CallContext の状態を列挙します。

非同期処理を開始すると Available から CallInProgress に遷移し、処理が終了すると CallSuccess、CallFailure、CallCancelled のいずれかの完了状態に遷移します。

列挙値
Available 

実行可能。

CallInProgress 

処理を実行中。この状態のときは他の非同期処理の Context としては使用できません。

CallSuccess 

処理が成功して終了しました。

CallFailure 

処理が失敗して終了しました。

CallCancelled 

処理がキャンセルされました。

CallContext に使用可能な各種フラグを列挙します。

列挙値
DeleteOnCompletion 

処理が完了したタイミングで ReleaseRef() が呼ばれます。

OneWayCall 

呼び出しが一方通行になります。この呼び出しに対する結果は返されません。 このフラグはRMCContext のためだけに用意されています。もしも相手先のメソッドが値を返したとき、 値は無視されて返答されません。しかし、常に、メッセージが相手に対して送信されたのかどうかは ブール値として返ります。もしもこのフラグがセットされていたら、この呼び出しは複数の対象を取ることができ、 SendUnreliableMessage, CallOnDuplicas, CallOnMaster, CallOnNeighbouringStations, CallOnLocalStationの 各フラグと一緒に設定しても問題ありません。

SendUnreliableMessage 

呼び出しはアンリライアブル(到達保証性のない)チャンネルを利用します。 このフラグはRMCContext のために用意されています。 また、OneWayCallフラグも同時にセットされていなければなりません。

関数詳解

template<typename TCallback >
void nn::nex::ProtocolCallContext::RegisterCompletionCallbackGeneric ( const TCallback &  callback,
qBool  deleteCallbackAfterCall = false,
qBool  bAddToEnd = true 
)

この ProtocolCallContext の完了時に実行するコールバックを設定します。

設定したコールバックはこの ProtocolCallContext が完了状態に遷移したときに呼び出されます。 このコールバックを使用することで、 ProtocolCallContext が完了したかどうかを確認するためにポーリングする手間を省くことができます。

callback には ProtocolCallContext* を引数に取る関数ポインタ、関数オブジェクト、ラムダ式を指定できます。 AddCallContextArgumentAdapter() を併用すると引数を一つも取らない関数を渡すこともできます。

関数オブジェクトを渡す場合は値もしくは参照型で渡す方法とポインタ型で渡す方法の二種類があり、それぞれ挙動が異なります。 値もしくは参照型で渡した場合は内部で関数オブジェクトがコピーもしくはムーブされ、コールバックはそのコピーもしくはムーブされたオブジェクトに対して行われます。 そのため、本関数呼び出し後は指定したオブジェクトを即座に破棄する事ができます。 ポインタ型で渡した場合は、コールバックはそのポインタが指すオブジェクトに対して行われます。 そのため、コールバックが呼び出されるまでその関数オブジェクトを呼び出し側で保持しておく必要があります。

本関数を複数回呼び出すことで複数のコールバックを登録することが出来ます。 複数のコールバックを登録した場合はデフォルトでは登録順にコールバックの呼び出しが行われ、最初に登録されたコールバックは最初に呼び出されます。 この順序を変更したい場合は、コールバックを登録する際に bAddToEnd パラメータを設定する必要があります。

callback に関数オブジェクトをポインタで渡した場合は deleteCallbackAfterCall を true にする事で callback の呼び出し後に自動的に callback を delete することができます。 もし callback を delete するのではなくアプリケーション独自の解放処理を行いたい場合は、 再度本関数を呼び出しそのための関数オブジェクトを追加する事で実装が可能です。

コールバック関数内では NEX のブロック関数を呼び出さないようにしてください。

引数
[in]callbackコールバックする関数ポインタもしくは関数オブジェクトもしくはラムダ式。
[in]deleteCallbackAfterCallcallback の実行が完了した後自動的に callback を delete するかどうか。
[in]bAddToEndtrue(デフォルト)であれば、コールバックはリストの最後に追加されます。falseであればリストの先頭に追加されます。
void nn::nex::CallContext::SetTimeout ( TimeInterval  tiTimeout)
inherited

非同期処理のタイムアウトをセットします。

非同期処理の開始後 tiTimeout ミリ秒後に非同期処理が完了していない( CallInProgress )場合に、 自動的に状態が CallFailure に移行し、 GetOutcome() で取得できる qResult が QRESULT(Core, Timemout) になります。

引数
[in]tiTimeoutタイムアウト時間(ミリ秒)
State nn::nex::CallContext::GetState ( ) const
inherited

CallContext の現在の状態を返します。

NEX のスレッドモードがスレッドアンセーフモードであっても、本関数は Scheduler::Dispatch() を含む任意の他の関数と同時に呼び出すことができます。

戻り値
現在の State 。 Available 、 CallInProgress 、 CallSuccess 、 CallFailure または CallCancelled のいずれかを返します。
参照
State
void nn::nex::CallContext::SetUserContext ( size_t  iIndex,
const UserContext oUserContext 
)
inherited

この CallContext に関連付けられている UserContext を設定します。

引数
[in]iIndexこの CallContext に関連付けられている UserContext のユーザー定義インデックスです。
[in]oUserContextこの CallContext に関連付けされている UserContext へのポインタ。
参照
GetUserContext
const UserContext& nn::nex::CallContext::GetUserContext ( size_t  iIndex) const
inherited

この CallContext に関連付けられている UserContext を返します。

戻り値
この CallContext に関連付けされている UserContext へのポインタ。
引数
[in]iIndex返される UserContext のユーザー定義インデックスです。
参照
SetUserContext
void nn::nex::CallContext::SetFlag ( qUnsignedInt32  uiFlag)
inherited

非同期処理に使用するフラグを設定します。

引数
[in]uiFlagCallContext::Flags で定義されるフラグ。
参照
ClearFlag, FlagIsSet, Flags
virtual qBool nn::nex::CallContext::FlagsAreValid ( ) const
virtualinherited

現在使用されているフラグの組み合わせが有効かどうかを返します。

戻り値
現在使用されているフラグの組み合わせが有効なら true 、そうでないかエラーが起きる場合は false 。
参照
Flags

nn::nex::DOCallContextで再実装されています。

void nn::nex::CallContext::ClearFlag ( qUnsignedInt32  uiFlag)
inherited

SetFlag を使用して設定されたフラグをクリアします。

引数
[in]uiFlagコールが呼び出されるフラグ。
参照
SetFlag, FlagIsSet, Flags
qBool nn::nex::CallContext::FlagIsSet ( qUnsignedInt32  uiFlag) const
inherited

特定のフラグが設定されているかどうかを返します。

戻り値
指定のフラグが設定されれば true 、そうでないかエラーが起きた場合は false 。
引数
[in]uiFlagコールが呼び出されるフラグ。
参照
SetFlag, ClearFlag, Flags
void nn::nex::CallContext::RegisterCompletionCallback ( CompletionCallback  pfCompletionCallback,
const UserContext oContext,
qBool  bAddToEnd = true 
)
inherited

この CallContext の完了時に実行するコールバック関数を設定します。

設定したコールバックはこの CallContext が完了状態に遷移したときに呼び出されます。 このコールバックを使用することで、 CallContext が完了したかどうかを確認するためにポーリングする手間を省くことができます。

本関数を複数回呼び出すことで複数のコールバックを登録することが出来ます。 複数のコールバックを登録した場合はデフォルトでは登録順にコールバックの呼び出しが行われ、最初に登録されたコールバックは最初に呼び出されます。 この順序を変更したい場合は、コールバックを登録する際に bAddToEnd パラメータを設定する必要があります。

コールバック関数内では NEX のブロック関数を呼び出さないようにしてください。

引数
[in]pfCompletionCallback完了時に呼び出されるコールバック関数へのポインタ。
[in]oContext呼び出されるコールバック関数へ渡される UserContext
[in]bAddToEndtrue(デフォルト)であれば、コールバックはリストの最後に追加されます。falseであればリストの先頭に追加されます。
void nn::nex::CallContext::RegisterCompletionCallback ( CallbackRoot pCallback,
qBool  bCallOnSuccess = true,
qBool  bAddToEnd = true 
)
inherited

この CallContext の完了時に実行するコールバックオブジェクトを設定します。

設定したコールバックはこの CallContext が完了状態に遷移したときに呼び出されます。 このコールバックを使用することで、 CallContext が完了したかどうかを確認するためにポーリングする手間を省くことができます。

本関数を複数回呼び出すことで複数のコールバックを登録することが出来ます。 複数のコールバックを登録した場合はデフォルトでは登録順にコールバックの呼び出しが行われ、最初に登録されたコールバックは最初に呼び出されます。 この順序を変更したい場合は、コールバックを登録する際に bAddToEnd パラメータを設定する必要があります。

コールバック関数内では NEX のブロック関数を呼び出さないようにしてください。

引数
[in]pCallback完了時に呼び出されるコールバックオブジェクトへのポインタ。
[in]bCallOnSuccess真(デフォルト)であれば、 コールバックは非同期処理の成功時にのみ呼び出されます。
[in]bAddToEndtrue(デフォルト)であれば、コールバックはリストの最後に追加されます。falseであればリストの先頭に追加されます。
qBool nn::nex::CallContext::Reset ( )
inherited

CallContext の状態を利用可能に再設定します。

このメソッドは、 State が Sucess 、 Failure または Cancelled のいずれかひとつである場合のみ、呼び出すことができます。

State が CallInProgress のときに本関数が呼び出されると、エラー SYSTEMERROR_GEN_INVALID_OPERATION になります。 State が Available の場合、本関数は true を返しますが、何も起こりません。

参照
State
qBool nn::nex::CallContext::Wait ( qUnsignedInt32  uiTimeout = WAIT_INFINITE_TIMEOUT)
inherited

非同期処理が完了する、またはタイムアウトを越えるまで内部処理を進め、待機します。

本関数は、 CallContextState が CallInProgress の場合に呼び出すことができます。 非同期処理が完了する、またはタイムアウトを越えるまで本関数の内部で Scheduler::Dispatch() が呼び出されます。

タイムアウトを越えた場合は、エラー SYSTEMERROR_GEN_TIMEOUT が発生します。 タイムアウトを越えた場合でも非同期処理が継続するため、非同期処理のout引数は解放できません。 out引数を解放したい場合は明示的に CallContext::Cancel() を呼び出してください。

引数
[in]uiTimeout待機する最大の時間(ミリ秒)。デフォルトのuiTimeoutは無限大です。
戻り値
非同期処理が完了した場合は true を、タイムアウトを越えた場合は false を返します。 false を返した場合の CallContext::GetOutcome() の値は不定です。
参照
State, CallContext::GetOutcome
qBool nn::nex::CallContext::WaitWithoutDispatch ( qUnsignedInt32  uiTimeout = WAIT_INFINITE_TIMEOUT)
inherited

非同期処理が完了する、またはタイムアウトを越えるまで待機します。

本関数は、 CallContextState が CallInProgress の場合に呼び出すことができます。 非同期処理が完了する、またはタイムアウトを越えるまで処理を戻しません。 CallContext::Wait() とは異なり、本関数内部で Scheduler::Dispatch() は呼び出されません。 内部処理を進めるには他のスレッドで Scheduler::Dispatch() などを呼び出す必要があります。 NEX のスレッドモードがスレッドアンセーフモードであっても、 本関数は Scheduler::Dispatch() を含む任意の他の関数と同時に呼び出すことができます。

タイムアウトを越えた場合でも非同期処理が継続するため、非同期処理のout引数は解放できません。 out引数を解放したい場合は明示的に CallContext::Cancel() を呼び出してください。

引数
[in]uiTimeout待機する最大の時間(ミリ秒)。デフォルトのuiTimeoutは無限大です。
戻り値
非同期処理が完了した場合は true を、タイムアウトを越えた場合は false を返します。 false を返した場合の CallContext::GetOutcome() の値は不定です。
参照
State, CallContext::GetOutcome
qBool nn::nex::CallContext::Cancel ( )
inherited

この CallContext に関連付けられている非同期処理をキャンセルします。

CallContext に関連付けされた非同期処理のうち、まだ実行されていない処理を放棄します。 本関数から戻った後は非同期処理開始時にセットした out 引数を解放する事ができます。

すでに実行されている処理については取り消す事は出来ず、どこまで処理されたかを知る方法はありません。 例えば、サーバーに対して何らかのリクエストを行う処理をキャンセルした場合、サーバーへのリクエストを送信した後に キャンセルが行われてもそのリクエストはサーバーで処理されます。その結果を呼び出し側で受信してもそれを無視するという動作になります。

主に非同期処理の結果を無視して良い状況で非同期処理開始時にセットしたout引数を解放する目的で使用してください。

本関数で非同期処理がキャンセルされた場合、返値は true となり非同期処理の結果は QERROR(Core, Cancelled) になります。 ステートが CallInProgress 以外だった場合にキャンセルした場合は返値は false となり、キャンセル処理は行われません。


戻り値一覧:

true 非同期処理がキャンセルされた。(ステートが CallInProgress だった場合)

false 非同期処理が開始されていないものをキャンセルしようとした。(ステートが Available だった場合。) もしくはすでに非同期処理が完了していた。(ステートが CallSuccess もしくは CallFailure もしくは CallCancelled だった場合。)

参照
State , Reset
qResult nn::nex::CallContext::GetOutcome ( ) const
inherited

非同期処理の結果を qResult として取得します。

特定の非同期処理に対する結果を取得します。 結果の内容については CallContext をパラメータとしてとる関数を参照してください。

戻り値
qResult としての非同期処理の結果。
void nn::nex::CallContext::Trace ( qUnsignedInt64  uiTraceFlags = TRACE_ALWAYS)
inherited

この CallContext オブジェクトの内容をトレースします。 リリースモードで実行されると自動的に無効になります。

引数
[in]uiTraceFlagsTraceLog::SetFlag() の引数と同様です。