CRI Sofdec  Last Updated: 2024-01-10 18:57 p
エラー処理について

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

エラーの種別について

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

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

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

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

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

致命的なエラーを検知する仕組みとして、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の呼び出し */
}
void criMana_Initialize(const CriManaLibConfig *config, void *work, CriSint32 work_size)
ライブラリの初期化



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

アプリケーションでアクセス違反等の問題が発生しているにも関わらず、リリース版ライブラリでエラーコールバックが発生しない場合、デバッグ版ライブラリを使用してエラーコールバックが発生するか確認してください。
[備考]エラーコールバック関数の登録について
CRI製ライブラリはエラー処理に共通のCRI Errorを利用しており、エラーコールバック関数も共通となります。
エラーコールバック関数の登録を実行すると、新しいコールバック関数に置き換えられることに注意してください。

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

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

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

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

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