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 with lesser warnings and informational messages following. 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 (see the following table). This value represents the status associated with the first (most recent and most serious) message in the list.

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;
char			apicall[ar_MAX_APICALL_SIZE]; /* function name*/
int			rtn; /* 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).