Error checking

All the C API functions (except FreeAR) return a status parameter (ARStatusList) that consists of zero or more notes, warnings, or errors generated from the function call (see Status-information).

Each message consists of a value that indicates the type of message, the message number, and the message text (in the language specified in the control structure). More serious errors are listed first followed by lesser warning and informational messages. Within each category, messages are listed in reverse chronological order, with the most recent message first.

The return of the function itself is an integer value that indicates the success or failure of the call. This value represents the status associated with the first (most recent and most serious) message in the list.

Related topic

Creating-and-executing-AR-System-C-API-programs

You can ignore warnings and informational messages, although reporting warnings is often helpful. Because the C API returns all errors in a common structure, you can perform all error handling by using a single, generic routine. The following example provides a sample routine for checking return values:

ARStatusListstatus;
charapicall[ar_MAX_APICALL_SIZE]; /* function name*/
intrtn; /* function return value*/

rtn = ARGetEntry(&control, ..., &status);
strcpy(apicall,"ARGetEntry");
switch( rtn ){
case AR_RETURN_OK:
printf("\t%s: Successful\n", apicall);
PrintARStatusList( &status );
break;
case AR_RETURN_WARNING:
printf("\t%s: Warning\n", apicall);
PrintARStatusList( &status );
break;
case AR_RETURN_ERROR:
printf("\t%s: Error\n", apicall);
PrintARStatusList( &status );
exit(3);
break;
case AR_RETURN_FATAL:
printf("\t%s: Fatal\n", apicall);
exit(3);
break;
case AR_RETURN_BAD_STATUS:
printf("\t%s: Bad Status\n", apicall);
exit(3);
break;
default:
printf("\t%s: Invalid return value: %d\n", apicall, rtn);
exit(3);
}

Because the status structure uses allocated memory, you must free that memory after every C API call by using FreeARStatusList. You can call these functions regardless of whether the status structure contains any messages, because they perform no action if there are no messages to free. For more information, see Freeing allocated memory.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*