Introduction

Proper error handling is crucial for building stable ONVIF client applications. The Happytimesoft library provides detailed error information through the ONVIF_DEVICE structure. The official onviftest2.cpp program ships a ready-to-use errorHandler() function that combines the authFailed flag, the errCode switch, and SOAP fault details.

This guide explains how to check API call results, handle authentication failures, interpret each error code, and extract HTTP/SOAP fault information.

Step 1: Check API Call Results

Every API call returns a boolean (BOOL): a return value of FALSE (0) indicates failure. Always check the result, and on failure call the error handler to diagnose the cause.

if (!GetDeviceInformation(&g_device))
{
    errorHandler(&g_device);
    printf("%s, GetDeviceInformation failed\r\n", g_device.binfo.XAddr.host);
}

Step 2: The Complete errorHandler Function

The recommended pattern is a single errorHandler(ONVIF_DEVICE *) function that first checks the authFailed flag, then switches on errCode. For HTTP-level errors it also prints the SOAP fault code, subcode, and reason:

void errorHandler(ONVIF_DEVICE * p_device)
{
    if (p_device->authFailed) // Authentication failed
    {
        printf("Authentication failed\r\n");
    }

    switch (p_device->errCode)
    {
    case ONVIF_ERR_ConnFailure:          // Connection failed
        printf("connect failure\r\n"); break;
    case ONVIF_ERR_MallocFailure:         // Failed to allocate memory
        printf("memory malloc failure\r\n"); break;
    case ONVIF_ERR_NotSupportHttps:       // Device requires HTTPS, library lacks HTTPS
        printf("not support https\r\n"); break;
    case ONVIF_ERR_RecvTimeout:           // Message receiving timeout
        printf("message receive timeout\r\n"); break;
    case ONVIF_ERR_InvalidContentType:    // Invalid content type in response
        printf("invalid content type\r\n"); break;
    case ONVIF_ERR_NullContent:           // No content in response
        printf("null content\r\n"); break;
    case ONVIF_ERR_ParseFailed:           // Failed to parse the message
        printf("message parse failed\r\n"); break;
    case ONVIF_ERR_HandleFailed:          // Message handling failed
        printf("message handle failed\r\n"); break;
    case ONVIF_ERR_HttpResponseError:     // Device responded with an error
        printf("code=%s\r\n", p_device->fault.Code);
        printf("subcode=%s\r\n", p_device->fault.Subcode);
        printf("reason=%s\r\n", p_device->fault.Reason);
        break;
    default:
        break;
    }
}

Step 3: Handle Authentication Failure First

Before switching on errCode, always check the authFailed flag. It is set when the device rejects the supplied credentials (wrong username or password). This is distinct from a connection error and should be reported separately:

if (p_device->authFailed)
{
    printf("Authentication failed: Invalid username or password.\r\n");
    // Prompt the user to re-enter credentials and retry
}

Error Code Reference

The complete set of error codes reported through errCode, grouped by category:

Best Practices

• Check authFailed before errCode: authentication failures are a special case that the error-code switch does not cover.
• Always inspect fault on HTTP errors: for ONVIF_ERR_HttpResponseError, print fault.Code, fault.Subcode, and fault.Reason to get the exact SOAP fault from the device.
• Log error codes for production debugging: use the library log (log_init + log_set_level(HT_LOG_DBG)) and your own application log.
• Implement retry logic for transient errors: timeouts and connection failures are often temporary; retry after a short delay.
• Provide user-friendly messages: map each error code to a clear, actionable message for end users.
• Reuse one error handler: a single errorHandler() called after every failed API keeps your code consistent and easy to maintain.