Pia API のエラー処理について説明します。
本ページでは、エラー・EULAアプレットを「ビューア」と表記します。
エラーの確認方法(エラーが発生するタイミング)は、大きく分けて次の 3 種類があります。
これらの方法で取得した nn::pia::Result は、各 API の関数リファレンスに従って適切にハンドリングする必要があります。または、後述のエラーハンドリング判別 API を使用することでハンドリングの自動化を行うことも可能です。
nn::pia::Result result = nn::pia::xxx::Yyy::Zzz();
if (result.IsSuccess()) { // 成功時の処理を行います。 ... } else { if (result == nn::pia::ResultA()) { // ResultA の場合のエラーハンドルを行います。 ... } else if (result == nn::pia::ResultB()) { // 特に何も行わなくていい Result もあります。 } else { // 実行時にハンドルするのではなく、その Result が返されないように // プログラムを修正する必要がある Result もあります。 // ここでは Pia の Result を文字列としてプリントしてから // プログラムを停止させています。 PIA_SAMPLE_PRINT("Result: %s\n", result.ToString()); PIA_SAMPLE_ASSERT(false); } } |
サンプルコードの else 部分にあるような、プログラムを修正する必要のある Result は、その Result リファレンスに「この Result が返らないようにアプリケーションを実装する必要があります。」と記載してあります。
インターネット通信などで発生するエラーをネットワークエラーコードとして表示するためにエラーコード変換 API を用意しています。詳細は nn::pia::Result クラスの関数リファレンスを参照してください。
この API で変換したネットワークエラーコードは、ビューアに渡すことができます。ただし、エラーによってはビューアに渡すことが適切でないものもあります。適切かどうかについては関数リファレンスを参照してください。または、後述のエラーハンドリング判別 API を使用することでハンドリングの自動化を行うことも可能です。
一部のセッション API は NEX の内部エラー ResultNexInternalError を返すことがあります。NEX 内部エラーについてはどのエラーが返るかをあらかじめ特定することができないため、エラーコード変換 API は NEX のネットワークエラーコードを直接返します。
取得できたネットワークエラーコードをビューアに渡すことが適切かどうかは、ネットワークエラーコードリストの NEX の項目を参照してください。
取得できるネットワークエラーコードは最後に発生した NEX の内部エラーのネットワークエラーコードになります。
アプリケーションによるハンドリングを自動化するために、ハンドリング方法を判別するための API が用意されています。
ハンドリングタイプ取得 API の nn::pia::Result::GetHandlingType() を使用することで Pia API が返した失敗の Result に適したハンドリング方法をアプリケーションが知ることができます。詳細は関数リファレンスを参照してください。
主なハンドリングタイプについて必要なエラー処理を次の表にまとめます。"WithLeave" がつく名前のハンドリングタイプのときはセッション離脱を呼ぶことで他のステーションでのゲームプレイへの影響を抑えることができます。
行:ハンドリングタイプ 列:エラー処理名 |
Leave セッション離脱 |
Cleanup セッションクリーンアップ |
Logout ログアウト |
Shutdown ネットワークシャットダウン |
Finalize 終了処理 |
---|---|---|---|---|---|
HandlingType_Cleanup | ※ | O | |||
HandlingType_CleanupWithLeave | O | O | |||
HandlingType_LogoutWithLeave | O | O | O | ||
HandlingType_ShutdownNetwork | ※ | O | O | O | |
HandlingType_Finalize | ※ | O | O | O | O |
セッション離脱の列で※となっているところは、セッション離脱を呼び出す必要はありませんが、呼び出してもかまいません。
nn::pia::Result result = nn::pia::xxx::Yyy::Zzz();
if (result.IsFailure()) { switch (result.GetHandlingType()) { case nn::pia::Result::HandlingType_Ignorable: // 特に何も行わなくてよい、無視できる Result です。 break; case nn::pia::Result::HandlingType_Retry: // 少し時間をおいてから再実行することが期待される Result です。 break; case nn::pia::Result::HandlingType_Cleanup: // クリーンアップ処理が必要とされる Result です。 nns::pia::Session_CleanupSession(); break; case nn::pia::Result::HandlingType_CleanupWithLeave: // セッション離脱処理、クリーンアップ処理が必要とされる Result です。 nns::pia::Session_LeaveSession(); nns::pia::Session_CleanupSession(); break; case nn::pia::Result::HandlingType_LogoutWithLeave: // セッション離脱処理、クリーンアップ処理、ログアウト処理が必要とされる Result です。 nns::pia::Session_LeaveSession(); nns::pia::Session_CleanupSession(); nns::pia::Inet_Logout(); break; case nn::pia::Result::HandlingType_ShutdownNetwork: // クリーンアップ処理、ログアウト処理、ネットワークの終了処理が必要とされる Result です。 nns::pia::Session_CleanupSession(); nns::pia::Inet_Logout(); nns::pia::Net_FinalizeNetwork(); break; case nn::pia::Result::HandlingType_Finalize: // クリーンアップ処理、ログアウト処理、ネットワークの終了処理、終了処理が必要とされる Result です。 nns::pia::Session_CleanupSession(); nns::pia::Inet_Logout(); nns::pia::Net_FinalizeNetwork(); // Pia の終了処理を含めたネットワーク種別毎の終了処理を行います。 break; case nn::pia::Result::HandlingType_ProgrammingError: // プログラミングエラーの Result です。 // Pia API の呼び出し方などが誤っている可能性があるので、 // アプリケーションプログラムを修正する必要があります。 PIA_SAMPLE_ASSERT(false); break; default: PIA_SAMPLE_ASSERT(false); break; } } |
ビューワータイプ取得 API の nn::pia::Result::GetViewerType() を使用することでビューアに渡してよいエラーかどうかを判別することができます。詳細は関数リファレンスを参照してください。
nn::pia::Result result = nn::pia::xxx::Yyy::Zzz();
if (result.IsFailure()) { if (result.GetViewerType() == nn::pia::Result::ViewerType_ShouldUse) { // エラービューアにエラーを渡してください。 } else if (result.GetViewerType() == nn::pia::Result::ViewerType_MayUse) { // エラービューアにエラーを渡しても構いませんし、アプリケーションでハンドリングしても構いません。 } else if (result.GetViewerType() == nn::pia::Result::ViewerType_ShouldNotUse) { // エラービューアにエラーを渡さず、アプリケーションでハンドリングしてください。 } else { PIA_SAMPLE_ASSERT(false); } } |