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

ログイン処理を行うクラスです。 [詳解]

#include <RendezVous/Services/Jugem/Login/src/Client/NgsFacade.h>

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

公開メンバ関数

 NgsFacade ()
 コンストラクタです。
 
virtual ~NgsFacade ()
 デストラクタです。 [詳解]
 
CredentialsGetCredentials ()
 Credentials (クライアントの証明書情報)を取得します。 [詳解]
 
qBool GetGameServerTime (DateTime *pServerTime) const
 ゲームサーバーの時刻(UTC)を取得します。 [詳解]
 
qInt32 GetLastLoginErrorCode () const
 ログイン処理で発生したネットワークエラーコードを取得します。 NgsFacade::Login() の非同期処理に失敗した場合にのみ有効な値がセットされます 本関数を呼び出せるかどうかは HasErrorOccuredLastLogin() で取得できます。 [詳解]
 
NgsBridgeInterfaceGetNgsBridge () const
 Pia と連携するための Interface を取得します。 [詳解]
 
qBool GetServerTime (DateTime *pServerTime) const
 ゲームサーバーの時刻(UTC)を取得します。 [詳解]
 
qBool HasErrorOccuredLastLogin () const
 前回のログインでエラーが発生したかどうかを取得します。 [詳解]
 
qResult IsConnected () const
 ゲームサーバーへの接続状態を取得します。 [詳解]
 
qResult Login (ProtocolCallContext *pContext, qUnsignedInt32 gameServerId, const qChar *pAccessKey, TimeInterval uiTimeout=30000, PrincipalID principalId=INVALID_PRINCIPALID)
 ログイン処理を行います。 [詳解]
 
qResult LoginAndRequestAuthenticationToken (ProtocolCallContext *pContext, qUnsignedInt32 gameServerId, const qChar *pAccessKey, const qChar8 *pKeyHash, qChar8 *pAuthToken, TimeInterval uiTimeout=30000, PrincipalID principalId=INVALID_PRINCIPALID)
 ログイン処理と独自サーバーの認証トークンの要求を行います。 [詳解]
 
qResult Logout (ProtocolCallContext *pContext)
 ログアウト処理を行います。 [詳解]
 
qBool RegisterNotificationEventHandler (NotificationEventHandler *pNotificationEventHandler)
 通知イベントハンドラーを登録します [詳解]
 
void ResetLastLoginError ()
 前回のログインでエラーが発生したかどうかの情報をクリアします。 [詳解]
 
qBool Terminate (CallContext *pContext)
 NgsFacade を終了し、deleteできる状態にします。 [詳解]
 
qBool TestConnectivity (ProtocolCallContext *pContext)
 インターネットとの接続性テストを行います。 [詳解]
 
qBool UnregisterNotificationEventHandler (NotificationEventHandler *pNotificationEventHandler)
 登録した通知イベントハンドラーを削除します。 [詳解]
 

静的公開メンバ関数

static void DisableLoginDataCache ()
 ログインに必要な情報のキャッシュをクリアします [詳解]
 
static void EnableLoginDataCache ()
 ログインに必要な情報の一部をキャッシュし、2回目以降のログイン時間を短縮できるようにします [詳解]
 
static qBool IsAbleLoginDataCache ()
 ログインに必要な情報のキャッシュを有効化しているかを返します [詳解]
 

詳解

ログイン処理を行うクラスです。

内部で nn::os::Event オブジェクトを一つ使用します。

NgsFacade オブジェクトが生存している間は定期的に Scheduler::Dispatch() を呼び出す必要があります。

構築子と解体子

virtual nn::nex::NgsFacade::~NgsFacade ( )
virtual

デストラクタです。

ログイン処理中・ログアウト処理中・ログイン中のいずれかの状態のとき、デストラクタ内で NgsFacade::Terminate() が呼ばれ、 オフライン状態に遷移するまでブロックします。デストラクタが呼ばれる前に NgsFacade::Terminate() を呼ぶことを推奨します。

関数詳解

qResult nn::nex::NgsFacade::Login ( ProtocolCallContext pContext,
qUnsignedInt32  gameServerId,
const qChar pAccessKey,
TimeInterval  uiTimeout = 30000,
PrincipalID  principalId = INVALID_PRINCIPALID 
)

ログイン処理を行います。

NGS (Nintendo Game Server) へのログイン処理を行います。

NGS へログインするには事前に NFS (Nintendo Friend Server) へのログイン処理が成功している必要があります。 NFS へのログインについては、 nn::friends のマニュアルを参照してください。

本関数は、認証サーバーでゲームの認証処理を行った後、NGS へログインします。

本関数では、ProtocolCallContext::SetTimeout()ProtocolCallContext::Cancel() で非同期処理をコントロールしないでください。 タイムアウト時間に関しては引数で指定し、ログイン処理を中断したい場合は NgsFacade::Terminate() を使用してください。

非同期処理の結果は CallContext::GetState() で成功・失敗の判断を行い、失敗の場合は GetLastLoginErrorCode() でネットワークエラーコードを取得してください。 CallContext::GetOutcome() で結果を取得しないでください。

ログイン処理が成功すると、NEX ライブラリ内部でゲームサーバーにキープアライブを送信します。 ゲームサーバーから 30 秒間キープアライブの応答がない場合、自動的にライブラリの内部状態がオフライン状態に遷移します。 このとき、アプリケーションは終了処理を行い、 NgsFacade::Logout() または NgsFacade::Terminate() を実行してください。 ライブラリの内部状態は IsConnected() で取得できます。

ゲームサーバー側でも、30秒間クライアントのキープアライブパケットが受け取れなかった場合にログアウトしたものとして扱います。

引数
[in,out]pContext呼び出し情報。 このオブジェクトでタイムアウト時間の設定やキャンセルを行わないで下さい。
[in]gameServerIdゲームサーバ ID。
[in]pAccessKeyゲームサーバーのアクセスキー。
[in]uiTimeoutタイムアウト時間(ミリ秒)。デフォルトは30秒です。
[in]principalIdINVALID_PRINCIPALID(デフォルト) または、本体の プリンシパルID を指定してください。


戻り値一覧:

"QSUCCESS(Core,Success)" ログイン処理の起動に成功。

"QERROR(Core,InvalidArgument)" 引数が不正。

"QERROR(Core,OperationAborted)" ログイン/ログアウト/ターミネート処理中、またはオンライン状態

"QERROR(FPD,NotInitialized)" フレンドライブラリが初期化されていない。

"QERROR(FPD,NotConnected)" NFS にログインしていない

"QERROR(FPD,InvalidPrincipalID)" 引数で与えた principalId が INVALID_PRINCIPALID とも本体の プリンシパルID とも一致しない。

qResult nn::nex::NgsFacade::LoginAndRequestAuthenticationToken ( ProtocolCallContext pContext,
qUnsignedInt32  gameServerId,
const qChar pAccessKey,
const qChar8 pKeyHash,
qChar8 pAuthToken,
TimeInterval  uiTimeout = 30000,
PrincipalID  principalId = INVALID_PRINCIPALID 
)

ログイン処理と独自サーバーの認証トークンの要求を行います。

本関数は、 Login() と、 IndependentServer::RequestAuthenticationToken() の処理をひとまとめにして行う関数です。 詳しくは、各関数のリファレンスを参照して下さい。

非同期処理の結果は CallContext::GetState() で成功・失敗の判断を行い、失敗の場合は GetLastLoginErrorCode() でネットワークエラーコードを取得してください。 CallContext::GetOutcome() で結果を取得しないでください。

引数
[in,out]pContext呼び出し情報。 このオブジェクトでタイムアウト時間の設定やキャンセルを行わないで下さい。
[in]gameServerIdゲームサーバ ID。
[in]pAccessKeyゲームサーバーのアクセスキー。
[in]pKeyHashキーハッシュ値。
[out]pAuthToken認証トークンを受け取るバッファ。
バッファサイズは IndependentServer::AUTH_TOKEN_SIZE 以上にして下さい。
[in]uiTimeoutタイムアウト時間(ミリ秒)。デフォルトは30秒です。
[in]principalIdINVALID_PRINCIPALID(デフォルト) または、本体の プリンシパルID を指定してください。


戻り値一覧:

"QSUCCESS(Core,Success)" ログイン処理の起動に成功。

"QERROR(Core,InvalidArgument)" 引数が不正。

"QERROR(Core,OperationAborted)" ログイン/ログアウト/ターミネート処理中、またはオンライン状態

"QERROR(FPD,NotInitialized)" フレンドライブラリが初期化されていない。

"QERROR(FPD,NotConnected)" NFS にログインしていない

"QERROR(FPD,InvalidPrincipalID)" 引数で与えた principalId が INVALID_PRINCIPALID とも本体の プリンシパルID とも一致しない。

qResult nn::nex::NgsFacade::Logout ( ProtocolCallContext pContext)

ログアウト処理を行います。

本関数を呼ぶ前に ServiceClient 継承クラス( MatchmakeExtensionClient , NATTraversalClient など)の Unbind() および delete を実行してください。

引数
[in,out]pContext呼び出し情報。 このオブジェクトでタイムアウト時間の設定やキャンセルを行わないで下さい。
戻り値
処理の結果が返ります。
戻り値一覧:

"QSUCCESS(Core,Success)" ログアウト処理の起動に成功。

"QERROR(Core,OperationAborted)" ログイン処理が実行中

"QERROR(Core,CallInitiationFailure)" 上記以外の失敗(別のログアウト処理が実行中など)

qBool nn::nex::NgsFacade::TestConnectivity ( ProtocolCallContext pContext)

インターネットとの接続性テストを行います。

ゲームサーバーと通信することによりインターネットとの接続性テストを行います。 正常に稼動しているゲームサーバーと通信できる場合は、本関数の非同期処理は必ず成功を返します。 本関数の非同期処理の完了を待つ必要はなく、アプリケーションで指定した時間(2, 3秒程度)で 非同期処理が完了しなかった場合は、接続性テストに失敗したと判定して構いません。

本関数を定期的に呼び出すことは禁止されています。クライアントが P2P 通信時に相手との通信が 出来なくなった場合に、切断の理由が相手クライアント側にあるのか、自分にあるのかを確認するために使用してください。 サーバーとの通信状態が維持されているかを確認する場合は NgsFacade::IsConnected() を使用し、 アクセスポイントとの接続が維持されているかを確認する場合は ac&#58&#58IsConnected()(または切断イベントのハンドリング) を使用してください。

ゲームサーバーにログインしていない場合は使用できません。

引数
[in,out]pContext呼び出し情報。


戻り値一覧:

true 非同期処理の開始に成功。

false 指定した pContext の状態が CallContext::CallInProgress となっており非同期処理を開始出来ない。 これは他の非同期処理で使用中であることを示します。 プログラミングエラーであるため、このケースはリリースビルド以外では内部で Assert により停止します。

qBool nn::nex::NgsFacade::HasErrorOccuredLastLogin ( ) const

前回のログインでエラーが発生したかどうかを取得します。

本関数はログイン処理が完了後もしくは試行前に呼び出すことができます。ログイン処理中は呼び出すことができません。


戻り値一覧:

true 前回のログインでエラーが発生した。

false 前回のログインでエラーが発生していない。もしくはログインを試行していない。

参照
ResetLastLoginError()
void nn::nex::NgsFacade::ResetLastLoginError ( )

前回のログインでエラーが発生したかどうかの情報をクリアします。

本関数を実行後は HasErrorOccuredLastLogin() が false を返します。 NgsFacade::Login() を呼び出すと自動的に本関数が呼び出されます。

参照
HasErrorOccuredLastLogin()
qInt32 nn::nex::NgsFacade::GetLastLoginErrorCode ( ) const

ログイン処理で発生したネットワークエラーコードを取得します。 NgsFacade::Login() の非同期処理に失敗した場合にのみ有効な値がセットされます 本関数を呼び出せるかどうかは HasErrorOccuredLastLogin() で取得できます。

戻り値
ログイン時のネットワークエラーコード。
NgsBridgeInterface* nn::nex::NgsFacade::GetNgsBridge ( ) const

Pia と連携するための Interface を取得します。

戻り値
NgsBridgeInterface のポインタ
参照
NgsBridgeInterface
qBool nn::nex::RendezVous::GetGameServerTime ( DateTime pServerTime) const
inherited

ゲームサーバーの時刻(UTC)を取得します。

ゲームサーバーへログイン後に取得可能です。ログアウトしても取得可能です。 ゲームサーバーからログイン時に取得した時間で、現在時刻を算出しています。

ずれの主要因として、ログイン時にゲームサーバーの時刻を取得するときのゲームサーバーの処理遅延、ゲームサーバーからの片道伝送遅延、および、 クライアントの Scheduler::Dispatch() の呼び出し遅延があげられます。 また、ゲームサーバーの時刻は、 NTP による同期の精度しかありませんので、 UTC 時刻に対して、最悪数百 msec 程度の精度となります。 負荷分散のため、端末ごとゲームサーバーの接続先が異なる場合があり、異なるゲームサーバーに接続した場合の時刻の一致も、 保証できません。

時刻の精度は、内部クロックに依存しますので、ログインしてから日単位の長時間経過後の精度は保証できません。

引数
[out]pServerTimeサーバー時刻。
戻り値
処理結果が返ります。


戻り値一覧:

true 成功

false 失敗(ゲームサーバーに一度もログインしていない。もしくは、pServerTimeがNULL)

参照
GetServerTime()
qBool nn::nex::RendezVous::GetServerTime ( DateTime pServerTime) const
inherited

ゲームサーバーの時刻(UTC)を取得します。

ゲームサーバーへログイン後に取得可能です。ログアウトしても取得可能です。 ゲームサーバーからログイン時に取得した時間で、現在時刻を算出しています。

ずれの主要因として、ログイン時にゲームサーバーの時刻を取得するときのゲームサーバーの処理遅延、ゲームサーバーからの片道伝送遅延、および、 クライアントの Scheduler::Dispatch() の呼び出し遅延があげられます。 また、ゲームサーバーの時刻は、 NTP による同期の精度しかありませんので、 UTC 時刻に対して、最悪数百 msec 程度の精度となります。 負荷分散のため、端末ごとゲームサーバーの接続先が異なる場合があり、異なるゲームサーバーに接続した場合の時刻の一致も、 保証できません。

時刻の精度は、内部クロックに依存しますので、ログインしてから日単位の長時間経過後の精度は保証できません。

NEX 3.6以降は、 GetGameServerTime()と同等の処理になりました。API互換性のために残してあります。

参照
GetGameServerTime()
qResult nn::nex::BackEndServices::IsConnected ( ) const
inherited

ゲームサーバーへの接続状態を取得します。

ゲームサーバーへの接続状態を取得します。本関数が false を返した場合でも明示的に NgsFacade::Logout() を呼ぶ必要があります。 本関数は毎フレーム呼び出してもパフォーマンスには影響がありません。 ログイン処理が終了するまでtrueとなりません。

ネットワーク接続が切れた場合や、一定時間サーバーとの通信ができない場合にオフラインとなります。

失敗時には、QERROR(RendezVous, ConnectionDisconnected) が返ります。

この値を ErrorCodeConverter::ConvertToNetworkErrorCode() でネットワークエラーコードに変換して、エラー・EULAアプレットに渡すことで、

「通信エラーが発生しました」というメッセージが表示されます。


戻り値一覧:

"QSUCCESS(Core, Success)" ゲームサーバーに接続中(オンライン)

"QERROR(RendezVous, ConnectionDisconnected)" オフライン

qBool nn::nex::BackEndServices::Terminate ( CallContext pContext)
inherited

NgsFacade を終了し、deleteできる状態にします。

本関数はログイン処理中・ログアウト処理中・オンライン・オフラインのいずれの状態であっても呼び出し可能で、 非同期処理が完了するとオフライン状態となることが保証されます。

ログイン処理中・ログアウト処理中・ログイン中のいずれかの状態のとき、 NgsFacade のデストラクタ内で NgsFacade::Terminate が呼ばれ、 オフライン状態に遷移するまでブロックします。NgsFacade を破棄する前に NgsFacade::Terminate を呼ぶことを推奨します。

本関数を呼ぶ前に ServiceClient 継承クラス( MatchmakeExtensionClient , NATTraversalClient など)の Unbind() および delete を実行してください。

ネットワークに繋がっていない場合、非同期処理に時間がかかることがあるため、 Core::SetTerminateImmediately() で強制終了モードを設定しても構いません。

引数
[in,out]pContext呼び出し情報。


戻り値一覧:

true 非同期処理の開始に成功。

false 指定した pContext の状態が CallContext::CallInProgress となっており非同期処理を開始出来ない。 これは他の非同期処理で使用中であることを示します。 プログラミングエラーであるため、このケースはリリースビルド以外では内部で Assert により停止します。

Credentials* nn::nex::BackEndServices::GetCredentials ( )
inherited

Credentials (クライアントの証明書情報)を取得します。

Credentials (クライアントの証明書情報)を取得します。有効な Credentials を取得するには、 NGS にログインしている必要があります。

戻り値
Credentials (クライアントの証明書情報)。ログインしていない場合は NULL が返ります。
static void nn::nex::BackEndServices::EnableLoginDataCache ( )
staticinherited

ログインに必要な情報の一部をキャッシュし、2回目以降のログイン時間を短縮できるようにします

ログインに必要な情報をキャッシュすることで、本関数の呼び出し後、2回目以降のログインでは ログインに要する時間を 2.0 秒 程度短縮します。

NEX の初期化を行った後(Initialize() などを呼び出した後)の初回ログイン前に呼び出してください。

NEX ライブラリを終了する際には DisableLoginDataCache() を呼び出してください

static void nn::nex::BackEndServices::DisableLoginDataCache ( )
staticinherited

ログインに必要な情報のキャッシュをクリアします

EnableLoginDataCache() を呼び出している場合、NEX の終了処理を行う前(Finalize() などを呼び出す前)に本関数を呼び出してください。

static qBool nn::nex::BackEndServices::IsAbleLoginDataCache ( )
staticinherited

ログインに必要な情報のキャッシュを有効化しているかを返します

戻り値
ログインに必要な情報のキャッシュを有効化しているかどうか
戻り値一覧:

true キャッシュが有効化されている

false キャッシュが有効化されていない

qBool nn::nex::BackEndServices::RegisterNotificationEventHandler ( NotificationEventHandler pNotificationEventHandler)
inherited

通知イベントハンドラーを登録します

通知イベントハンドラーを登録します。本関数を実行することで、通知イベントを受信するたびに NotificationEventHandler::ProcessNotificationEvent コールバックが実行されるようになります。 すべての通知イベントを受信するためには、本関数を NgsFacade::Login() 呼び出しよりも前に実行してください。 NgsFacade::Login() 実行後に本関数を実行すると、本関数の実行までの間に送られた通知イベントを受信できないことがあります。 イベントハンドラーは複数個登録できます。

引数
[in]pNotificationEventHandler登録する通知イベントハンドラーへのポインタ。
戻り値一覧:

true 成功。

false 同じイベントハンドラーを複数個登録しようとした。

qBool nn::nex::BackEndServices::UnregisterNotificationEventHandler ( NotificationEventHandler pNotificationEventHandler)
inherited

登録した通知イベントハンドラーを削除します。

引数
[in]pNotificationEventHandler登録を取り消す通知イベントハンドラーへのポインタ。
戻り値一覧:

true 成功。

false 指定したイベントハンドラーが見つからなかった。