Status information

The last return value of almost all API functions is a status parameter. This parameter contains information about the success or failure of the call. The status variable is a pointer to a structure (see the following figure).

Structure used to return function status

Like all list structures in AR System (see Lists-and-structures), ARStatusList has zero or more ARStatusStruct items. Each ARStatusStruct item represents a message that the function call generates and has the following elements:

The following figure shows an example of the layout of the ARStatusList structure. 

Example of ARStatusList structure 


In this example, the status parameter is defined as a stack variable of type ARStatusList and has an integer that specifies the number of messages in the list (three in this case) and a pointer to their location on the heap. Based on the size and number of the returned messages, the system dynamically allocates the memory space.

The messages themselves are stored in an array of ARStatusStruct structures, each containing the message type, message number, and pointers to the message text and any appended text. The messages are sorted in decreasing order of severity, based on the message type value (see Error-checking). The return value for the function is the message type associated with the first (most recent and most serious) message in the list. In this example, the return value is 2.

To access individual elements in the list, use standard array notation. For example, status.statusList.messageText identifies the message text associated with the first message, and status.statusList.messageNum provides the message number for the second message

After a program processes a returned status list, it must call FreeARStatusList to free any allocated memory. If numItems equals zero, the call is optional.