エラーハンドリングについて

本項では、CRI Atomライブラリが取り扱うエラーの種別や、エラー検知の方法について説明します。

エラーの種別について

エラーには、大きく分けて以下の2種類があります。

• 致命的なエラー（起きてはいけないエラー）
  
• 起こり得るエラー（正常な運用方法でも起こり得るエラー）
  

致命的なエラーとしては、関数に不正なアドレスが渡されたり、メモリ不足で処理が継続できない場合等があげられます。
これに対し、起こり得るエラーとしては、デバイスの読み込みエラー（ディスクメディアの表面に汚れが付着してデータが読めない場合）等があげられます。

CRIミドルウェアでは、これら2種類のエラーに対し、それぞれ以下に示すエラー検知方法を提供しています。

「致命的なエラー」について

致命的なエラーを検知する仕組みとして、CRI BaseライブラリにCRI Error APIが用意されています。

CRI Errorは、CRI製のライブラリで共通に利用可能な、エラー処理専用のAPI群です。
CRI Atomライブラリに限らず、CRI AudioライブラリやCRI File Systemライブラリ等、エラー処理にCRI Errorを使用しているライブラリ群に関しては、共通の手続きでエラー情報を取得可能です。

CRI Errorは致命的なエラーを検知する方法として、"コールバック関数によるエラー通知"の仕組みを用意しています。

コールバック関数によるエラー通知

criErr_SetCallback 関数にエラーコールバック関数を設定することで、 致命的なエラーを検知することができます。
コールされた関数には、エラーの原因を特定するために必要な情報（文字列など）が渡されます。

コールバック関数を使用してエラーをハンドリングする場合、処理の流れは以下のようになります。

1. CRI AtomライブラリのAPI実行前（初期化処理よりも前）に、 criErr_SetCallback 関数を使用し、エラーコールバック関数を登録する。
   
2. CRI AtomライブラリのAPIを実行する。
   
3. 関数内でエラーが発生した場合、手順(1)で登録したコールバック関数が呼び出されます。エラーの内容に応じて適宜エラー処理を行う。
   

具体的なソースコードは、以下のようになります。

/* エラーコールバック関数 */
void user_error_callback_func(const CriChar8 *errid, CriUint32 p1, CriUint32 p2, CriUint32 *parray)
{
    const CriChar8 *err_message;
    
    /* エラー発生時はこの部分に処理が移ります */
    
    /* 引数群にエラー情報が入っていますが、                   */
    /* そのままでは可読性が悪いので、一旦書式を変換します    */
    
    /* エラー情報を書式化されたエラー文字列に変換 */
    err_message = criErr_ConvertIdToMessage(errid, p1, p2);
    
    /* エラー情報をデバッガーに出力 */
    OutputDebugString(err_message);
    
    /* エラー処理 */
        ：
}
 
/* メイン処理 */
main()
{
        ：
    /* エラーコールバック関数の登録 */
    /* 備考）この処理は1度実行するだけでOKです */
    criErr_SetCallback(user_error_callback_func);
    
    /* CRI AtomライブラリAPIの呼び出し */
    criAtomEx_Initialize(…);
        ：
}

［重要］デバッグ版ライブラリについて
CRI Atomライブラリには、リリース版ライブラリの他に、デバッグ版ライブラリが用意されています。
リリース版ライブラリでは、アプリケーションが呼び出す関数の引数や、プラットフォームの提供する関数の入出力チェック等、最小限のエラーチェックのみを行っています。
これに対し、デバッグ版ライブラリではエラーチェックが強化されています。
（ライブラリ内部のパラメーターが不正になっていないかどうかや、ハンドルの整合性等もチェックします。）

アプリケーションでアクセス違反等の問題が発生しているにも関わらず、リリース版ライブラリでエラーコールバックが発生しない場合、デバッグ版ライブラリを使用してエラーコールバックが発生するか確認してください。

［備考］エラーコールバック関数の登録について
CRI製ライブラリはエラー処理に共通のCRI Errorを利用しており、エラーコールバック関数も共通となります。
エラーコールバック関数の登録を実行すると、新しいコールバック関数に置き換えられることに注意してください。

「起こり得るエラー」について

「致命的エラー」とは別に、ディスクの読み込みエラー等の「起こり得るエラー」があります。
CRI Atomライブラリでは、起こり得るエラーの検知には"ステータスのチェック"を使用します。

AtomExプレーヤ等、使用中にエラーが起き得るモジュールについては、 criAtomExPlayer_GetStatus 関数のような、ステータスを取得する関数が用意されています。
AtomExプレーヤで音声ファイルの再生を行った際に、指定されたファイルが存在しない場合や、リードエラーが起きて読み込みに失敗した場合、 criAtomExPlayer_GetStatus 関数が CRIATOMEXPLAYER_STATUS_ERROR を返します。
ユーザは定期的にAtomExプレーヤのステータスをチェックすることで、エラーの発生を検知することが可能です。

具体的なソースコードは、以下のようになります。

main()
{
        :
    /* 音声データをセット */
    criAtomExPlayer_SetData(player, buffer, size);
    
    /* セットされた音声データを再生 */
    criAtomExPlayer_Start(player);
    
    /* 再生完了待ち */
    for (;;) {
        /* ステータスの取得 */
        status = criAtomExPlayer_GetStatus(player);
        
        /* ステータスのチェック */
        if (status == CRIATOMEXPLAYER_STATUS_ERROR) {
            /* エラー発生時はエラー処理を行う */
                :
        }
        
        /* サーバ処理の実行 */
        criAtomEx_ExecuteMain();
        
        /* 画面表示の更新等 */
            :
    }
        :
}

Next:ライブラリの初期化／終了処理について