エラーハンドリング


本チュートリアルでは、エラーコールバック機能を使ったエラーハンドリングについて説明します。

再生に必要なファイル

ランタイム側で必要なデータファイルはありません。本チュートリアルでは意図的にエラーを発生させ、オーディオ処理を行わずに終了します。

プロジェクトファイルとソースコード

チュートリアルのプロジェクトファイルとソースコードは以下の場所にあります。

チュートリアルソースコードの場所
  * cri

  \ * pc

    \ * tutorials

      \ * criatomex

        \ * error_handling

          o * pcvc

          | o * error_handling.sln

          | o * error_handling.vcxproj

          | \ * error_handling.vcxproj.filters

          |  

          \ * error_handling.c

 

[プラットフォーム固有]

: チュートリアルプログラム

 

: エラーハンドリングチュートリアル

: プロジェクトファイルフォルダー

: Visual Studio ソリューションファイル

: Visual Studio プロジェクトファイル

: Visual Studio フィルターファイル

 

: エラーハンドリングチュートリアル

 


プログラムの流れ

プログラムの流れを以下に示します。

  1. ヘッダーファイルのインクルード
  2. エラーコールバックの登録
  3. CRI Atomライブラリの初期化
  4. エラーコールバックを起こす
  5. 終了処理
  6. エラーの確認

/* CRI SDK Header */
#include <cri_xpt.h>

/* CRI ADX2 Headers */
#include <cri_atom_ex.h>
#include <cri_atom_wasapi.h>

/* main関数 */
CriSint32 main(CriSint32 argc, CriChar8 *argv[])
{
    /* 最低限の初期化 */
    tutorial_initialize();

    /* エラーコールバック関数の登録 */
    criErr_SetCallback(tutorial_error_callback_func);

    /* メモリアロケーターの登録 */
    criAtomEx_SetUserAllocator(tutorial_alloc, tutorial_free, NULL);
    
    /* ライブラリの初期化 */
    criAtomEx_Initialize_WASAPI(NULL, NULL, 0);
    
    /* ACFファイルの読み込みと登録 */
    criAtomEx_RegisterAcfFile(NULL, NULL, NULL, 0);
    
    /* ライブラリの終了 */
    criAtomEx_Finalize_WASAPI();

    /*  最小限の終了処理*/
    tutorial_finalize();

    return 0;
}

/* エラーコールバック関数 */
static void tutorial_error_callback_func(const CriChar8 *errid, CriUint32 p1, CriUint32 p2, CriUint32 *parray)
{
    const CriChar8 *errmsg;
    UNUSED(parray);
    /* エラー文字列の表示 */
    errmsg = criErr_ConvertIdToMessage(errid, p1, p2);
    tutorial_printf(errmsg);
    return;
}

プログラムの解説

各処理の詳細について説明します。

1.ヘッダーファイルのインクルード


/* CRI SDK Header */
#include <cri_xpt.h>

/* CRI ADX2 Headers */
#include <cri_atom_ex.h>
#include <cri_atom_wasapi.h>

cri_xpt.hは、CRI独自の型定義等が記述されているので、一番最初にインクルードします。 他のヘッダーファイルについては、インクルードする順番に依存関係はありません。

cri_atom_ex.hは、CRI Atomの機能を使うためのAPIが宣言されたヘッダーファイルです。 必ずインクルードしてください。

2.エラーコールバックの登録


CriSint32 main(CriSint32 argc, CriChar8 *argv[])
{
    /* エラーコールバック関数の登録 */
    criErr_SetCallback(tutorial_error_callback_func);
    :
    :
    :
}

/* エラーコールバック関数 */
static void tutorial_error_callback_func(const CriChar8 *errid, CriUint32 p1, CriUint32 p2, CriUint32 *parray)
{
    const CriChar8 *errmsg;
    UNUSED(parray);
    /* エラー文字列の表示 */
    errmsg = criErr_ConvertIdToMessage(errid, p1, p2);
    tutorial_printf(errmsg);
    return;
}

CRIランタイムライブラリ全体で共有するエラーコールバック関数を登録します。 エラーコールバックの登録には、criErr_SetCallback関数を使用します。
CRIランタイムライブラリ内でエラーが発生した場合に、ここで登録した関数が実行されます。
エラーコールバック関数にはエラーID、エラーメッセージ、場合によってエラー固有の引数が渡されます。 criErr_ConvertIdToMessage関数を使って文字列に変換し、デバッグ出力等でエラーが起きている事を判断できます。
エラーコールバックを使う利点は、メイン処理と非同期に発生するエラーを捉えることが可能な点、 戻り値と異なり、エラーの情報をある程度詳しく知ることが出来る点です。 (関数の戻り値によるエラー判定が不要というわけではありません。) 特に、エラーIDは問題発生時に原因調査に役立ちます。

3.CRI Atomライブラリの初期化


    /* メモリアロケーターの登録 */
    criAtomEx_SetUserAllocator(tutorial_alloc, tutorial_free, NULL);
    
    /* ライブラリの初期化 */
    criAtomEx_Initialize_WASAPI(NULL, NULL, 0);

CRI Atomライブラリを初期化します。初期化の詳細については他のチュートリアルを参考にしてください。

4.エラーコールバックを起こす


    /* ACFファイルの読み込みと登録 */
    criAtomEx_RegisterAcfFile(NULL, NULL, NULL, 0);

criAtomEx_RegisterAcfFile関数を使用してACFファイルをランタイム側で読み込みます。 本チュートリアルでは意図的にエラーを起こすために、ファイル名にNULLを指定します。
ファイル名にNULLを指定してcriAtomEx_RegisterAcfFile関数を実行したため、 エラーが発生し、criErr_SetCallback関数で登録したtutorial_error_callback_func関数が実行されます。

5.終了処理


    /* ライブラリの終了 */
    criAtomEx_Finalize_WASAPI();

本チュートリアルではを初期化しただけなので、 終了処理ではcriAtomEx_Finalize_WASAPI関数を実行するだけです。

6.再生の確認

本チュートリアルを実行すると、エラーが発生し、デバッグ出力ウィンドウに以下のエラー情報が出力されるはずです。(デバッグ実行する必要があります。)

E2008073181:Invalid parameter. 
E2010052671:Can not open ACF file. (path = (null))

「E」からはじまる数字列がエラーIDで、発生したエラーに固有の番号です。「:」以降がエラー内容です。
本チュートリアルは以上です。

Next:サンプル

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