Error Handling

This tutorial explains how to use the error callback function for error handling.

Files Needed for Playback

This tutorial intentionally generates errors and terminates itself without any audio process, therefore there is no test data file to prepare for running.

Project File and Source Code

The project file and source codes are located at following folders.

Location of Tutorial source code

	CRIWARE SDK pc tutorials criatomex error_handling pcvc error_handling.sln error_handling.vcxproj error_handling.vcxproj.filters   error_handling.c
		[Platform dependent]
		: Tutorial programs
		: Error handling tutorial
		: Project file folder
		: Visual Studio solution file
		: Visual Studio project file
		: Visual Studio filter file
		: Error Handling Tutorial

Program Flow

Program flow is as follows:

1. Include header files
2. Registration of error callback
3. CRI Atom library initialization
4. Evoke error callback
5. Library finalization
6. Verification
   

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

/* main function */
CriSint32 main(CriSint32 argc, CriChar8 *argv[])
{
    /* Initialization (minimum)*/
    tutorial_initialize();
 
    /* Registration of error callback function */
    criErr_SetCallback(tutorial_error_callback_func);
 
    /* Registration of memory allocator */
    criAtomEx_SetUserAllocator(tutorial_alloc, tutorial_free, NULL);
    
    /* Library initialization */
    criAtomEx_Initialize_PC(NULL, NULL, 0);
    
    /* Read and register ACF file */
    criAtomEx_RegisterAcfFile(NULL, NULL, NULL, 0);
    
    /* Finalize library */
    criAtomEx_Finalize_PC();
 
    /*  Finalization */
    tutorial_finalize();
 
    return 0;
}
 
/* Error callback function */
static void tutorial_error_callback_func(const CriChar8 *errid, CriUint32 p1, CriUint32 p2, CriUint32 *parray)
{
    const CriChar8 *errmsg;
    UNUSED(parray);
    /* Display Error message string */
    errmsg = criErr_ConvertIdToMessage(errid, p1, p2);
    tutorial_printf(errmsg);
    return;
}

Description of Program

Detail explanation for each step.

1. Include header files

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

Include cri_xpt.h first, as it contains CRI specific type definitions.
Other header files have no restriction for their order.

cri_atom_ex.h contains API declaration of functions for CRI Atom.
It must be included.

2. Registration of error callback

CriSint32 main(CriSint32 argc, CriChar8 *argv[])
{
    /* Error callback function registration */
    criErr_SetCallback(tutorial_error_callback_func);
    :
    :
    :
}
 
/* Error callback function */
static void tutorial_error_callback_func(const CriChar8 *errid, CriUint32 p1, CriUint32 p2, CriUint32 *parray)
{
    const CriChar8 *errmsg;
    UNUSED(parray);
    /* Display error message */
    errmsg = criErr_ConvertIdToMessage(errid, p1, p2);
    tutorial_printf(errmsg);
    return;
}

Register a error callback which is used over all CRI runtime library by calling criErr_SetCallback function.
The function registered here is excuted when an error occurs in CRI runtime library
Error ID, error message and additional argument, if necessary, are passed to error callback function.
criErr_ConvertIdToMessage converts the ID to a string which shows short description of the error for debug output.
This error callback feature enables to detect errors that asynchronously behind main process, and details error information more than function return value. Error ID helps us investigate the cause of errors, though function return value is not useless.

3. CRI Atom library initialization

/* Registration of memory allocator */
criAtomEx_SetUserAllocator(tutorial_alloc, tutorial_free, NULL);
 
/* Initialization of library */
criAtomEx_Initialize_PC(NULL, NULL, 0);

Initialize CRI Atom library. For the detail of library initialization, see other tutorials.

4. Evoke error callback

/* Read and register ACF file */
criAtomEx_RegisterAcfFile(NULL, NULL, NULL, 0);

To read ACF file, use criAtomEx_RegisterAcfFile function. Here, as a tutorial for error handling, NULL is passed as a ACF file name to generate error intentionally.
Calling criAtomEx_RegisterAcfFile function with NULL argument as a file name evokes an error, and the error callback function, tutorial_error_callback_func, which is set by criErr_SetCallback, is executed.

5. Library finalization

/* Library finalization */
criAtomEx_Finalize_PC();

In this tutorial initializes only , then just call criAtomEx_Finalize_PC as the finalization.

6. Verificaion

As this tutorial program is executed, following error information will be shown in debug output window.

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

Error ID is specific identifier for each error, which has the form which starts 'E' and followed by numbers and the rest part after ':' is description of the error.

Next:Samples