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

本項では、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:ライブラリの初期化/終了処理について

CRI Middleware logo Copyright (c) 2006-2018 CRI Middleware Co., Ltd.