エラー処理について

本項では、Sofdec ライブラリが取り扱うエラーの種別や、エラー検知の方法について説明します。
基本的にはADXライブラリと同様ですが、ハンドルがエラー状態になった時の対処に注意してください。

エラーの種別について

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

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

致命的なエラーとしては、関数に不正なアドレスが渡されたり、メモリ不足で処理が継続できない場合等があげられます。
これに対し、起こり得るエラーとしては、デバイスの読み込みエラー（ディスクが抜かれていてファイルオープンできないなど）があげられます。

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

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

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

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

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

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

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

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

1. CRI ManaライブラリのAPI実行前（初期化処理よりも前）に、 criErr_SetCallback 関数を使用し、エラーコールバック関数を登録する。
   
2. CRI Manaライブラリの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);
    
    /* SofdecライブラリAPIの呼び出し */
    criMana_Initialize(…);
        ：
}

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

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

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

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

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

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

エラー状態が発生した場合の対処

CriManaPlayer ハンドルの状態がエラーになった場合は、そのままハンドルを破棄したり、別のムービーを再生したりすることは出来ません。
criManaPlayer_Stop 関数を呼び出して、ハンドル状態を CRIMANAPLAYER_STATUS_STOP に遷移するのを待ってから次の処理に進んでください。