API Buffer Statuses

API buffer statuses are stored in the ApiBufferStatus class.

The current status of an API buffer channel can be retrieved with the GetStatus function in the ApiBuffer class. A brief description of the statuses that may be obtained can be found at GetStatus.

All statuses of an API buffer channel are cleared when the API buffer is freed with the FreeApiBuffer function.

The API buffer statuses are explained below.

State

The state status contains the current state of the API buffer channel as one of the members of the ApiBufferState enumerator.

Each state is explained in the following table.

State	Description
Idle	The API buffer is not created yet. All API buffer channels are in this state when the WMX3 engine is started.
Active	The API buffer is executing APIs. The API buffer channel will change to this state when the Execute function is called while in the Stop state. While in this state, the API functions in the API buffer will be executed sequentially. API functions will be executed with as fast as possible; to add a delay between the execution of API functions, add the ApiBuffer::Wait or ApiBuffer::Sleep functions to the API buffer. The API buffer channel will remain in this state after the last API function in the buffer is executed. As long as the API buffer channel remains in this state, API functions that are added to the buffer will be executed. If the stopOnLastBlock option is enabled using the SetOptions function, the API buffer channel state will change to Stop when the last API function in the buffer is executed.
Stop	The API buffer is not executing APIs. The API buffer channel changes to this state when one of the following occurs: When the CreateApiBuffer function is called successfully, the state changes from Idle to Stop. When the Halt function is called, the state changes from Active to Stop. When the last API function in the buffer is executed and the stopOnLastBlock option is enabled, the state changes from Active to Stop.
Delay	Execution of the API buffer is temporarily stopped. This occurs when the ApiBuffer::Wait or ApiBuffer::Sleep function is executed from the buffer. The state changes from Active to Delay when this occurs. After the ApiBuffer::Wait or ApiBuffer::Sleep function finishes executing, the state changes from Delay to Active. The API buffer does not change to this state when the Motion::Wait function is executed from the buffer.

The possible state transitions are summarized in the following state diagram.

Blocks

Among the statuses that can be obtained, several statuses reference blocks. Each block is equivalent to an API call.

The block number of the API is an identification number that is assigned to every API function that is passed to the buffer. The block number begins at 0 and is incremented by 1 each time an API is added to the buffer. After the assigned block number reaches 2^32 = 4294967296, the block number loops back to 0.

Statuses with units of blocks are summarized in the following table.

Status	Description
blockCount	The total number of blocks in the API buffer. Each time an API function is added to the buffer, this value increments by one. This value is reset to 0 when the Clear function is called for the API buffer channel.
remainingBlockCount	The number of blocks that remain to be executed in the API buffer. Each time an API function is added to the buffer, this value increments by one. Each time an API function is executed from the buffer, this value decrements by one. This value is reset to 0 when the Clear function is called for the API buffer channel.
execBlockCount	The number of blocks that have been executed from the API buffer. Each time an API function is executed from the buffer, this value increments by one. This value is reset to 0 when the Clear function is called for the API buffer channel.

Buffer Memory

Among the statuses, that can be obtained, several statuses reference the buffer memory size. These statuses have units of bytes.

These statuses can be observed to measure the amount of bytes that an API function added to

Statuses with units of bytes are summarized in the following table.

Status	Description
bufferSize	The size of the API buffer in bytes. The buffer size is specified when the API buffer is created using the CreateApiBuffer function.
freeSize	The size of the remaining space in the API buffer in bytes. The size of the free space in the API buffer in bytes. An API function may fail to be added to the API buffer if there is not enough space remaining in the buffer. Once an API function has been executed from the buffer, the space it occupied will be freed and this status will increase by the freed amount.

Error Log

The error log (errorLog) stores the error codes that are returned by API functions that are called from the API buffer. Each entry in the error log consists of the block number (contained in execBlockNumber) and the error code (contained in errorCode).

The block number is equal to the value of blockCount before the API function is added to the API buffer. For example, if blockCount is 10 when an API function is added to the API buffer (raising blockCount to 11), if that API function returns an error when it is executed from the API buffer, an error log is added with execBlockNumber equal to 10.

The error code is equivalent to the error codes defined in ErrorCode and the classes that inherit this class (such as CoreMotionErrorCode).

The error log is an array with maxApiBufferErrorLog elements. Only the last maxApiBufferErrorLog errors are stored in the error log. If additional errors are detected, errors are removed from the error log, starting with the oldest errors.

The smallest index in the error log contains the newest error. For example, the first error is stored in the first index of the error log. When the second error is detected, this error is now stored in the first index of the error log, and the first error is moved to the second index of the error log.

The following figure shows an example of the change in the error log when the first error is detected.

The following figure shows an example of the change in the error log when the second error is detected.

The following figure shows an example of the change in the error log when an error is detected when the error log is full.

Watch Error

The watch error statuses return the statuses of the watch function. For additional information, see SetWatch.

The watch error statuses are watchError, watchErrorCode, and watchErrorAxis.