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

再生に必要なファイル

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

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

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

チュートリアルソースコードの場所
	cri pc tutorials criatomex error_handling pcvc error_handling.sln error_handling.vcxproj error_handling.vcxproj.filters error_handling.c

		[プラットフォーム固有]
		: チュートリアルプログラム

		: エラーハンドリングチュートリアル
		: プロジェクトファイルフォルダー
		: Visual Studio ソリューションファイル
		: Visual Studio プロジェクトファイル
		: Visual Studio フィルターファイル

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

プログラムの流れ

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

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

/* CRI SDK Header */
#include <cri_xpt.h>
 
/* CRI ADX 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;
}

プログラムの解説

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

１．ヘッダーファイルのインクルード

/* CRI SDK Header */
#include <cri_xpt.h>
 
/* CRI ADX Headers */
#include <cri_atom_ex.h>
#include <cri_atom_wasapi.h>

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

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

２．エラーコールバックの登録

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は問題発生時に原因調査に役立ちます。

３．CRI Atomライブラリの初期化

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

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

４．エラーコールバックを起こす

/* ACFファイルの読み込みと登録 */

criAtomEx_RegisterAcfFile(NULL, NULL, NULL, 0);

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

ファイル名にNULLを指定して::criAtomEx_RegisterAcfFile 関数を実行したため、エラーが発生し、::criErr_SetCallback 関数で登録したtutorial_error_callback_func 関数が実行されます。

５．終了処理

/* ライブラリの終了 */

criAtomEx_Finalize_WASAPI();

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

６．再生の確認

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

E2008073181:Invalid parameter.

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

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

本チュートリアルは以上です。

Next:サンプル