关于错误处理

本节将介绍CRI Atom运行时库处理的错误类型及如何检测错误。

关于错误类型

错误大致可以分为以下两种类型。

• 致命错误（不允许发生的错误）
  
• 可能发生的错误（正常操作中可能发生的错误）
  

致命错误包括将无效地址传递给函数，或因内存不足而无法继续处理的情况。
与此相对，可能发生的错误包括设备的读取错误（因磁盘表面脏污而无法读取数据）等。

CRI Middleware针对这两种类型的错误，分别提供下列错误检测方法。

关于“致命错误”

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()
{
        ：
    /* 注册错误回调函数 */
    /* 备注）此处理只需执行一次 */
    criErr_SetCallback(user_error_callback_func);
 
    /* 调用CRI Atom运行时库API */
    criAtomEx_Initialize(…);
        ：
}

［重要］关于调试版运行时库
除发布版运行时库外，CRI Atom运行时库还提供调试版运行时库。
在发布版运行时库中，仅执行最低限度的错误检查，例如应用程序调用的函数的参数、平台提供的函数的输入输出检查等。
与此相对，调试版运行时库加强了错误检查。
（还要检查运行时库内部参数是否正确及句柄的一致性等。）

无论应用程序中是否发生访问冲突等问题，如果发布版运行时库没有发生错误回调，请使用调试版运行时库确认是否发生错误回调。

［备注］关于注册错误回调函数
CRI运行时库使用共同的CRI Error进行错误处理，并且使用共同的错误回调函数。
注意：执行错误回调函数的注册时，将被新的回调函数替换。

关于“可能发生的错误”

除“致命的错误”之外，还有磁盘读取错误等“可能发生的错误”。
CRI Atom运行时库使用"状态检查"来检测可能发生的错误。

关于可能在使用中发生错误的AtomExPlayer等模块，提供::criAtomExPlayer_GetStatus 函数等获取状态的函数。
使用AtomExPlayer播放音频文件时，如果指定的文件不存在或发生读取错误导致读取失败，则::criAtomExPlayer_GetStatus 函数将返回::CRIATOMEXPLAYER_STATUS_ERROR。
用户可通过定期检查AtomExPlayer的状态来检测错误。

具体源代码如下。

main()
{
        :
    /* 设置音频数据 */
    criAtomExPlayer_SetData(player, buffer, size);
 
    /* 播放已设置的音频数据 */
    criAtomExPlayer_Start(player);
 
    /* 等待播放完成 */
    for (;;) {
        /* 获取状态 */
        status = criAtomExPlayer_GetStatus(player);
 
        /* 状态检查 */
        if (status == CRIATOMEXPLAYER_STATUS_ERROR) {
            /* 发生错误时执行错误处理 */
                :
        }
 
        /* 执行Server处理 */
        criAtomEx_ExecuteMain();
 
        /* 更新屏幕显示等 */
            :
    }
        :
}

Next:关于运行时库的初始化／结束处理