How to Handle ONVIF Client Errors in C

Introduction

Proper error handling is crucial for building stable ONVIF client applications. The Happytimesoft library provides detailed error information through the ONVIF_DEVICE structure.

This guide explains how to check API call results, handle authentication failures, and interpret specific error codes.

Step 1: Check API Call Results

Always check the return value of every API call (e.g., GetDeviceInformation). A return value of 0 indicates failure.

C Code: Check API Result

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

Step 2: Handle Authentication Failure

Before checking the error code, first check the authFailed flag. This is a special case that indicates invalid credentials.

C Code: Check Authentication

if (g_device.authFailed) 
{   
    printf("Authentication failed: Invalid username or password.\r\n"); 
}

Step 3: Interpret Error Codes

If authentication succeeded but the call failed, inspect the g_device.errCode for the specific error.

C Code: Handle Specific Errors

switch (g_device.errCode) 
{
    // Connection & Network Errors
case ONVIF_ERR_ConnFailure: 
    printf("Error: Connection to device failed. Check IP, port, and network.\r\n");
    break;
case ONVIF_ERR_RecvTimeout: 
    printf("Error: Message receive timeout. Device may be unresponsive.\r\n");
    break;
    
    // Resource & Internal Errors
case ONVIF_ERR_MallocFailure: 
    printf("Error: Memory allocation failed. System may be low on memory.\r\n");
    break;
    
    // Protocol & Message Errors
case ONVIF_ERR_NotSupportHttps: 
    printf("Error: Device requires HTTPS, but client library is not compiled with HTTPS support.\r\n");
    break;
case ONVIF_ERR_InvalidContentType: 
    printf("Error: Device response has invalid Content-Type.\r\n");
    break;
case ONVIF_ERR_NullContent: 
    printf("Error: Device response has no content.\r\n");
    break;
case ONVIF_ERR_ParseFailed: 
    printf("Error: Failed to parse the device's response message.\r\n");
    break;
case ONVIF_ERR_HandleFailed: 
    printf("Error: Internal message handling failed.\r\n");
    break;
    
    // HTTP-Level Errors
case ONVIF_ERR_HttpResponseError: 
    printf("HTTP Error from device:\r\n");
    printf("  Code=%s\r\n", g_device.fault.Code); 
    printf("  Subcode=%s\r\n", g_device.fault.Subcode); 
    printf("  Reason=%s\r\n", g_device.fault.Reason); 
    break;
    
default:
    printf("Unknown error occurred.\r\n");
    break;
}

Error Code Categories

Connection: Network unreachable, timeout.
Resource: Memory allocation failure.
Protocol: HTTPS not supported, invalid message format.
Content: Empty or unparsable response.
HTTP: The device returned a SOAP fault (e.g., invalid action).

Best Practices

Always check authFailed before errCode
Log error codes for debugging production issues.
Implement retry logic for transient errors (e.g., timeout).
Provide user-friendly error messages based on the error code.