1.8. エラー処理

Pia API のエラー処理について説明します。

本ページでは、エラー・EULAアプレットを「ビューア」と表記します。

エラーの確認方法

エラーの確認方法(エラーが発生するタイミング)は、大きく分けて次の 3 種類があります。 

  1. 返値
    処理の実行結果として nn::pia::Result を返す API の場合は、その返値をチェックします。
    どの API がどのような nn::pia::Result を返すかは、関数リファレンスを参照してください。
  2. 非同期処理
    非同期 API の XXXAsync() といった名前の API を使用する場合は、非同期処理の完了後 GetXXXResult() を呼び出して結果をチェックします。
    詳しくは 1.6. 非同期処理 のページを参照してください。
  3. ポーリング
    CheckXXX() のような名前で API が用意されているモジュールがあります(詳細は関数リファレンスを参照してください)。
    この場合、アプリケーションは定期的に CheckXXX() を呼び出して、エラー発生の有無をチェックします。

これらの方法で取得した nn::pia::Result は、各 API の関数リファレンスに従って適切にハンドリングする必要があります。または、後述のエラーハンドリング判別 API を使用することでハンドリングの自動化を行うことも可能です。

コード 1-8. エラーハンドリングのサンプルコード
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 を使用することでハンドリングの自動化を行うことも可能です。

ResultNexInternalError のネットワークエラーコード

一部のセッション 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

セッション離脱の列で※となっているところは、セッション離脱を呼び出す必要はありませんが、呼び出してもかまいません。

コード 1-9. GetHandlingType() によるエラーハンドリング方法の判別
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() を使用することでビューアに渡してよいエラーかどうかを判別することができます。詳細は関数リファレンスを参照してください。

コード 1-10. GetViewrType() によるエラー表示の判別
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);
    }
}