1.8. Error Handling

This section describes the Pia API error-handling process.

How to Verify Errors

There are three main ways to check for errors.

  1. Return values
    For functions that return nn::Result as their processing result, this return value can be checked.
    To learn which nn::Result values are returned by which functions, see the API reference.
  2. Asynchronous processes
    For asynchronous functions with names in the form of XXXAsync(), results can be checked by calling the GetXXXResult() function after the asynchronous process has completed.
    For more information, see  1.6. Asynchronous Processing.
  3. Polling
    Some modules provide functions with names in the form of CheckXXX(). (For more information, see the Pia API Reference.)
    The application periodically calls the CheckXXX() functions to check whether errors have occurred.

Handle the nn::Result values obtained in these ways as appropriate. For more information, see the API reference. Alternatively, you can automate error handling by using the function that determines error handling (described below).

Code 1-8. Error Handling Code
nn::Result result = nn::pia::xxx::Yyy::Zzz();
if (result.IsSuccess())
{
    // Processing when successful.
    ...
}
else
{
    if (result == nn::pia::ResultA())
    {
        // Error handling for ResultA.
        ...
    }
    else if (result == nn::pia::ResultB())
    {
        // Some results might not need any special handling.
    }
    else
    {
        // Rather than handling it during the running of the program,
        // you must make revisions so that the result is not returned.
        // Uses the GetResultString() function to print the Pia Result as a string,
        // and then stops the program.
        PIA_SAMPLE_LOG("Result: %s\n", nn::pia::util::GetResultString(result));
        PIA_SAMPLE_ASSERT(false);
    }
}

As shown in the else portion of the sample code, if a result requires a revision to the program, the reference for that result notes that the application must be implemented.

Converting to Network Error Codes

There is an API that converts error codes so that errors that result from Internet communications and the like can be displayed as network error codes. For more information, see the API reference for the nn::pia::util::NetworkErrorCodeConverter class.

You can pass the network error codes converted with this API to the Error/EULA applet. However, some errors are not appropriate for passing to the Error/EULA applet. For more information about the appropriateness of passing different errors, see the API reference. Alternatively, you can automate error handling by using the function that determines error handling (described below).

Network Error Codes for ResultNexInternalError

Some of the session API functions can return ResultNexInternalError, which is a NEX internal error. Because it is not possible to identify ahead of time which error will be returned for a NEX internal error, the error code conversion API directly returns the NEX network error code.

For more information about whether the obtained network error code is appropriate for passing to the Error/EULA applet, see the NEX section in the network error code list.

The error code that can be obtained is the network error code for the last NEX internal error that occurred.

Automating Error Handling

To enable automatic error handling by the application, an API has been prepared for determining how to handle errors.

Use the pia::util::GetHandlingType() function to tell the application the appropriate way to handle failure Result values returned by the Pia API functions. For more information, see the API reference.

Use the pia::util::GetViewerType() function to determine whether it is all right to pass an error to the error/EULA applet. For more information, see the API reference.

Code 1-9. Determining How to Handle Errors Using the GetHandlingType Function
nn::Result result = nn::pia::xxx::Yyy::Zzz();
if (result.IsFailure())
{
    switch (nn::pia::util::GetHandlingType(result))
    {
    case nn::pia::util::HANDLING_IGNORABLE:
        // Result that requires no special handling and can be ignored.
        break;
    case nn::pia::util::HANDLING_RETRY:
        // Result that calls for trying again after a short while.
        break;
    case nn::pia::util::HANDLING_CLEANUP:
        // Result that requires a cleanup.
        ...
        ...
        break;
    .
    .
    .
    case nn::pia::util::HANDLING_PROGRAMMING_ERROR:
        // A programming error Result.
        // A Pia function may have been called incorrectly.
        // The application source code must be fixed.
        PIA_SAMPLE_ASSERT(false);
        break;
    default:
        PIA_SAMPLE_ASSERT(false);
        break;
    }
}