Error Handling

Error types and the way to detect an error for CRI Atom library are described in this topic.

Error Types

Errors are classified mainly into the following two types.

• Fatal error (it should not occurr.)
  
• Possible error (it may occur even in the normal use.)
  

Fatal error will occurr in the case, for example, where illegal memory address is passed to the function, or where some process cannot be continued due to memory shortage.
In the meanwhile, for example, read error from device (it occurs when data cannot be read due to dust or dirt on disk media.) is one of possible errors.

CRI middleware provides the following ways to detect an error for these two error types.

Fatal Error

CRI Error API is prepared in the CRI Base library to detect a fatal error.

CRI Error is the API set specialized for error handling that can be used also for other CRI libraries.
Not only CRI Atom library but CRI Audio library and CRI File System library , which use CRI Error for error handling, can retrieve error information by the common procedure.

CRI Error provides the error notification method by the callback function to detect a fatal error.

Error notification by the callback function

By setting the criErr_SetCallback function as the error callback function, a fatal error can be detected.
Necessary information (character string) is passed to the function to identify cause of error.

The procedure for error handling by the callback function is as follows:

1. Register an error callback function by the criErr_SetCallback function before executing CRI Atom library API's (before initialization process).
   
2. Execute CRI Atom library APIs.
   
3. If an error occurs in some function, the registered callback function is called, and then handle the error depending on error type.
   

Sample source code is shown below:

/* error callback function */
void user_error_callback_func(const CriChar8 *errid, CriUint32 p1, CriUint32 p2, CriUint32 *parray)
{
    const CriChar8 *err_message;
    
    /* Transferred to the callback function when an error occurred. */
    
    /* Arguments convey error information but readability is not good. */
    
    /* Convert error information to formatted error character string */
    err_message = criErr_ConvertIdToMessage(errid, p1, p2);
    
    /* Error information is output to debugger console */
    OutputDebugString(err_message);
    
    /* error handling process */
        :
}
 
/* main process */
main()
{
        :
    /* Register the error callback function */
    /* Note: This process needs to be done just one time */
    criErr_SetCallback(user_error_callback_func);
    
    /* Call the CRI Atom library API */
    criAtom_Initialize(...);
        :
}

[Important] Debug version library
In the CRI Atom library, the debug version library is provided in addition to the release version library.
In the release version library, minimal error checks are performed, for example, checking the function arguments called from an application, and checking the input/output of function provided by the platform SDK.
In the debug version library, the error checks are enhanced.
(Checks whether internal library parameters are valid, and checks handle consistency.)

If error callback function is not called even though a problem such as access violation occurs in the application, use the debug version library and check whether the callback happens.

[Note] Registration of error callback function
CRI libraries use CRI Error for error handling and the error callback function is shared.
Note that when perforing registration of error callback function, the error callback function is replaced by a new one.

Possible Errors

Apart from fatal error, there is a "possible error" like disk read error.
In the CRI Atom library, to detect a possible error, the "status check" method is used.

For a module like AtomEx player in which an error occurs during operations, the status retrieval function such as the criAtomExPlayer_GetStatus function is available.
In the case, for example, where specified file does not exist when playing audio file through AtomEx player, or where file read fails due to read error, the criAtomExPlayer_GetStatus function returns CRIATOMEXPLAYER_STATUS_ERROR .
It is possible to detect an error by regularly checking the AtomEx player status.

Sample source code is shown below:

main()
{
        :
    /* Set audio data */
    criAtomExPlayer_SetData(player, buffer, size);
    
    /* Play back the audio data */
    criAtomExPlayer_Start(player);
    
    /* Wait for completion of playback */
    for (;;) {
        /* Get status */
        status = criAtomExPlayer_GetStatus(player);
        
        /* Check the status */
        if (status == CRIATOMEXPLAYER_STATUS_ERROR) {
            /* Handle the error when it occurred. */
                :
        }
        
        /* Execute the server processing */
        criAtomEx_ExecuteMain();
        
        /* Update screen display */
            :
    }
        :
}

Next:Initialization and Finalization of the Library