# MOZA_SDK API Reference

> Document type: API Reference
> Audience: developers who need a quick lookup for public MOZA_SDK interfaces
> Public headers: `include/moza/moza.h`, `include/moza/moza.hpp`

This document provides an English reference-style overview of the public `MOZA_SDK` API.

---

## 1. Header Files

### C API

```c
#include "moza/moza.h"
```

### C++ Wrapper

```cpp
#include "moza/moza.hpp"
```

---

## 2. Fundamental Types

### `MOZA_BOOL`

Boolean type used by the C API.

Constants:

- `MOZA_FALSE`
- `MOZA_TRUE`

### `MOZA_SIZE`

Unsigned size and count type used by the API.

### `MOZA_DEVICE_ID`

Runtime-assigned device identifier.

### `MOZA_LOG_LEVEL`

Log severity used by the public log callback API.

### `MOZA_LOG_CONTEXT`

Reserved log context delivered to the public log callback API.

Public fields include:

- `level`
- `message`
- `messageSize`
- `category`
- `categorySize`

Reserved fields remain internal and must not be interpreted by applications.

### `MOZA_COMMAND_ID`

Command identifier recognized by the API.

### `MOZA_PARAMETER_ID`

Parameter identifier recognized by the API.

### `MOZA_DEVICE_HANDLE`

Opaque device handle type.

Invalid handle constant:

- `MOZA_INVALID_DEVICE_HANDLE`

### Version Macros

The generated version header provides these compile-time macros:

- `MOZA_SDK_VERSION_MAJOR`
- `MOZA_SDK_VERSION_MINOR`
- `MOZA_SDK_VERSION_PATCH`
- `MOZA_SDK_VERSION_TWEAK`
- `MOZA_SDK_VERSION_STRING`
- `MOZA_SDK_VERSION_NUMBER`
- `MOZA_SDK_MAKE_VERSION(Major, Minor, Patch, Tweak)`

---

## 3. Error Codes

Public error type:

- `MOZA_ERRNO`

Important values include:

- `MOZA_ERR_NO_ERROR`
- `MOZA_ERR_SERVICE_NOT_FOUND`
- `MOZA_ERR_SERVICE_VERSION_MISMATCH`
- `MOZA_ERR_INVALID_ARGUMENT`
- `MOZA_ERR_NOT_INITIALIZED`
- `MOZA_ERR_ALREADY_INITIALIZED`
- `MOZA_ERR_BUFFER_TOO_SMALL`
- `MOZA_ERR_DEVICE_NOT_FOUND`
- `MOZA_ERR_DEVICE_NOT_OPEN`
- `MOZA_ERR_INVALID_HANDLE`
- `MOZA_ERR_BUSY`
- `MOZA_ERR_TIMEOUT`
- `MOZA_ERR_NOT_SUPPORTED`
- `MOZA_ERR_PARAMETER_READ_COMMAND_ERROR`
- `MOZA_ERR_PARAMETER_WRITE_COMMAND_ERROR`
- `MOZA_ERR_INDEX_OUT_OF_BOUNDS`
- `MOZA_ERR_PENDING`

---

## 4. Enumerations

### Device Categories

- `MOZA_DEVICE_CATEGORY`
- `MOZA_DC_UNKNOWN`
- `MOZA_DC_RS`
- `MOZA_DC_AS`

### Racing Device Types

- `MOZA_DEVICE_TYPE_RS`
- values such as `MOZA_DT_RS_WHEELBASE`, `MOZA_DT_RS_STEERING_WHEEL`, `MOZA_DT_RS_PEDAL`

### Aircraft Device Types

- `MOZA_DEVICE_TYPE_AS`
- values such as `MOZA_DT_AS_WHEELBASE`, `MOZA_DT_AS_THROTTLE`, `MOZA_DT_AS_STICK`

### Device State

- `MOZA_DEVICE_STATE`
- `MOZA_DS_UNKNOWN`
- `MOZA_DS_NORMAL`
- `MOZA_DS_DISCONNECTED`

### Value Type

- `MOZA_VALUE_TYPE`
- `MOZA_VT_INVALID`
- `MOZA_VT_NULL`
- `MOZA_VT_INT`
- `MOZA_VT_UINT`
- `MOZA_VT_DOUBLE`
- `MOZA_VT_BOOL`
- `MOZA_VT_STRING`
- `MOZA_VT_BINARY`
- `MOZA_VT_LIST`

### HID Axis

- `MOZA_HID_AXIS`
- `MOZA_HA_X` through `MOZA_HA_HAT_SWITCH`
- `MOZA_HA_MAX`

### Event Type

- `MOZA_EVENT_TYPE`

Supported event values:

- `MOZA_ET_SERVICE_CONNECTION_CLOSED`
- `MOZA_ET_DEVICE_CONNECTED`
- `MOZA_ET_DEVICE_DISCONNECTED`
- `MOZA_ET_DEVICE_PARAMETER_VALUE_CHANGED`
- `MOZA_ET_DEVICE_PARAMETER_ERROR_OCCURRED`
- `MOZA_ET_DEVICE_COMMAND_REPLIED`
- `MOZA_ET_DEVICE_COMMAND_ERROR_OCCURRED`
- `MOZA_ET_HID_AXIS_DATA_CHANGED`
- `MOZA_ET_HID_BUTTON_PRESSED`
- `MOZA_ET_HID_BUTTON_RELEASED`

---

## 5. Public Structures

### `MOZA_VALUE`

Variant value container used by the C API.

Main fields:

- `type`
- `data.intValue`
- `data.uintValue`
- `data.doubleValue`
- `data.boolValue`
- `data.stringValue`
- `data.binaryValue`
- `data.listValue`

### `MOZA_HID_AXIS_DATA`

Represents a single HID axis sample.

Fields:

- `rawValue`
- `normalizedValue`

### `MOZA_HID_INPUT_STATE`

Represents a HID input snapshot.

Fields:

- `timestamp`
- `axes`
- `buttons`

Helper macro:

- `MOZA_HID_INPUT_STATE_IS_BUTTON_PRESSED`

### `MOZA_EVENT_DATA`

Top-level event payload delivered to the event callback.

Contains:

- `timestamp`
- `type`
- `data.*` union payloads for each event type

Important payload members include:

- `deviceConnected`
- `deviceDisconnected`
- `parameterValueChanged`
- `parameterErrorOccurred`
- `commandReplied`
- `commandErrorOccurred`
- `hidAxisDataChanged`
- `hidButtonPressed`
- `hidButtonReleased`

Value-carrying payload fields use the generic member name `value`.

### `MOZA_DEVICE_INFO`

Basic device information snapshot.

Fields:

- `id`
- `name`
- `portName`
- `vendorId`
- `productId`
- `category`
- `type`
- `state`
- `hidDeviceCount`

### `MOZA_HID_DEVICE_INFO`

Basic HID device information snapshot.

Fields:

- `vendorId`
- `productId`
- `interfaceNumber`
- `collectionNumber`
- `productName`
- `axisCount`
- `buttonCount`

### `MOZA_PARAMETER_INFO`

Basic parameter information snapshot.

Fields:

- `id`
- `name`
- `readable`
- `writable`
- `reserved`

### `MOZA_COMMAND_INFO`

Basic command information snapshot.

Fields:

- `id`
- `name`
- `reserved`

---

## 6. Initialization and Shutdown

### `Moza_Initialize`

Initializes the SDK.

### `Moza_GetSdkVersionNumber`

Returns the encoded runtime SDK version number.

### `Moza_GetSdkVersionString`

Returns the runtime SDK version string.

### `Moza_Shutdown`

Shuts down the SDK and releases all resources.

### C++ Wrapper

- `moza::initialize()`
- `moza::getSdkVersionNumber()`
- `moza::getSdkVersionString()`
- `moza::shutdown()`

If an application wants to receive initialization-time internal logs, register the log callback before `Moza_Initialize`.

---

## 7. Event Callback API

### `MOZA_EVENT_CALLBACK`

C callback signature for event delivery.

### `Moza_SetEventCallback`

Registers the global C event callback.

### `MOZA_LOG_CALLBACK`

C callback signature for forwarded internal SDK/DeviceSDK log records.

Log data is delivered through `MOZA_LOG_CONTEXT`, while its reserved fields remain internal-only.

### `Moza_SetLogCallback`

Registers the global C log callback.

The callback is optional. If not registered, the public SDK does not expose internal logs to the application.

`message` and `category` are exposed through `MOZA_LOG_CONTEXT` as pointer-and-size fields and are not guaranteed to be null-terminated.

### `Moza_SetHidAxisEventMinInterval`

Configures the minimum dispatch interval for HID axis change events.

### C++ Wrapper

- `moza::setEventCallback(MOZA_EVENT_CALLBACK, void*)`
- `moza::setEventCallback(moza::EventCallback, void*)`
- `moza::setLogCallback(MOZA_LOG_CALLBACK, void*)`
- `moza::setLogCallback(moza::LogCallback, void*)`
- `moza::setHidAxisEventMinInterval()`

---

## 8. `MOZA_VALUE` Utility Functions

### `Moza_ValueCreate`

Creates a heap-backed variable-size value.

### `Moza_ValueCopy`

Deep-copies a `MOZA_VALUE`.

### `Moza_ValueDestroy`

Releases heap-backed memory owned by a `MOZA_VALUE`.

### C++ Wrapper

Primary wrapper type:

- `moza::Value`

Important members include:

- constructors for scalar, string, binary, and list values
- `isValid()`
- `isNull()`
- `type()`
- `raw()`
- `reset()`
- `asInt()`
- `asUInt()`
- `asDouble()`
- `asBool()`
- `asString()`
- `asBinary()`
- `asList()`
- `fromRaw()`

---

## 9. Device Enumeration and Device Information API

### C API

- `Moza_DeviceGetList`
- `Moza_DeviceGetInfoById`
- `Moza_DeviceOpen`
- `Moza_DeviceClose`

### C++ Wrapper

- `moza::getDeviceList(std::vector<DeviceInfo>&)`
- `moza::getDeviceList()`
- `moza::getDeviceInfoById(DeviceId, DeviceInfo*)`
- `moza::getDeviceInfoById(DeviceId)`
- `moza::Device::open(DeviceId)`
- `moza::Device::close()`
- `moza::Device::isOpen()`
- `moza::Device::raw()`

---

## 10. Parameter API

### C API

- `Moza_DeviceParameterGetIdByName`
- `Moza_DeviceParameterGetInfoById`
- `Moza_DeviceParameterGetInfoByName`
- `Moza_DeviceParameterGetList`
- `Moza_DeviceParameterFetch` (asynchronous)
- `Moza_DeviceParameterFetchSync` (synchronous)
- `Moza_DeviceParameterGetValue` (non-blocking cached read)
- `Moza_DeviceParameterGetValueSync` (synchronous)
- `Moza_DeviceParameterSetValue` (asynchronous)
- `Moza_DeviceParameterSetValueSync` (synchronous)

Notes:

- `Moza_DeviceParameterFetch` and `Moza_DeviceParameterSetValue` return after the request is accepted and do not wait for the parameter reply.
- `Moza_DeviceParameterGetValue` reads only the current cached value and may return `MOZA_ERR_BUSY` when no cached value is available yet.
- When `Moza_DeviceParameterGetValue` returns `MOZA_ERR_BUSY`, the SDK also triggers one background fetch request, and the later result can be observed through `MOZA_ET_DEVICE_PARAMETER_VALUE_CHANGED`.
- The `...Sync` variants block until a reply is received or the timeout expires.
- Asynchronous parameter operations can still be observed through `MOZA_ET_DEVICE_PARAMETER_VALUE_CHANGED` and `MOZA_ET_DEVICE_PARAMETER_ERROR_OCCURRED`.

### C++ Wrapper Types

#### `moza::RawParameter`

Important members:

- `isValid()`
- `deviceHandle()`
- `id()`
- `fetch()`
- `fetchSync()`
- `getInfo(ParameterInfo*)`
- `getInfo()`
- `getValue(Value*)`
- `getValue()`
- `getValueSync()`
- `setValue(const Value&)`
- `setValueSync(const Value&, int32_t)`

Obtain a `RawParameter` through `moza::Device::parameter()` or `moza::Device::getParameter()`.

> Generated device classes from `moza/device_as.hpp` also expose typed parameter wrappers such as `moza::Parameter<TRead, TWrite>`. Refer to the generated header bundled with the SDK package for the exact typed wrapper methods.

#### `moza::Device`

Parameter-related members:

- `getParameterIdByName()`
- `getParameterList()`
- `parameter()`
- `getParameter()`
- `getParameterInfo()`
- `getParameterInfoByName()`

---

## 11. Command API

### C API

- `Moza_DeviceCommandSend` (asynchronous)
- `Moza_DeviceCommandSendSync` (synchronous)
- `Moza_DeviceCommandGetInfoById`
- `Moza_DeviceCommandGetInfoByName`
- `Moza_DeviceCommandGetList`

Notes:

- `Moza_DeviceCommandSend` returns after the request is accepted and does not wait for the command reply.
- `Moza_DeviceCommandSendSync` blocks until the reply is received or the timeout expires.
- Asynchronous command operations can still be observed through `MOZA_ET_DEVICE_COMMAND_REPLIED` and `MOZA_ET_DEVICE_COMMAND_ERROR_OCCURRED`.
- Command arguments are passed as a single `MOZA_VALUE`. For multiple arguments, use a `MOZA_VT_LIST` value.

### C++ Wrapper Types

#### `moza::RawCommand`

Important members:

- `isValid()`
- `deviceHandle()`
- `id()`
- `send()`
- `send(const Value&)`
- `send(const std::vector<Value>&)`
- `sendSync(int32_t)`
- `sendSync(const Value&, int32_t)`
- `sendSync(const std::vector<Value>&, int32_t)`
- `getInfo(CommandInfo*)`
- `getInfo()`

Obtain a `RawCommand` through `moza::Device::command()` or `moza::Device::getCommand()`.

> Generated device classes from `moza/device_as.hpp` also expose typed command wrappers such as `moza::Command<TRequest, TResponse>`. Refer to the generated header bundled with the SDK package for the exact typed wrapper methods.

#### `moza::Device`

Command-related members:

- `command()`
- `getCommand()`
- `getCommandInfo()`
- `getCommandInfoByName()`
- `getCommandList()`

---

## 12. HID API

### C API

- `Moza_DeviceHidGetList`
- `Moza_DeviceHidOpen`
- `Moza_DeviceHidClose`
- `Moza_DeviceHidGetInputState`

### C++ Wrapper Types

#### `moza::HidDevice`

Important members:

- `isValid()`
- `deviceHandle()`
- `index()`
- `getInfo(HidDeviceInfo*)`
- `getInfo()`
- `open()`
- `close()`
- `getInputState(HidInputState*)`
- `getInputState()`

#### `moza::Device`

HID-related members:

- `getHidList()`
- `getHidInfo()`
- `getHid()`

#### Utility Helper

- `moza::isHidButtonPressed()`

---

## 13. C++ Type Aliases

Common aliases in `moza` include:

- `moza::Errno`
- `moza::Bool`
- `moza::Size`
- `moza::DeviceId`
- `moza::CommandId`
- `moza::ParameterId`
- `moza::DeviceHandle`
- `moza::EventType`
- `moza::EventData`
- `moza::EventCallback`
- `moza::LogLevel`
- `moza::LogContext`
- `moza::LogCallback`
- `moza::DeviceCategory`
- `moza::DeviceState`
- `moza::ValueType`
- `moza::HidAxis`
- `moza::DeviceInfo`
- `moza::HidDeviceInfo`
- `moza::ParameterInfo`
- `moza::CommandInfo`
- `moza::HidAxisData`
- `moza::HidInputState`

---

## 14. Notes for Developers

- Event pointer fields are valid only during the callback.
- `MOZA_VALUE` objects that own heap memory must be destroyed when using the C API.
- `ApiDebugTool.exe` is the recommended tool for discovering parameter and command IDs and names.
- Parameter read and write command failures are exposed through dedicated public error codes.

---

## 15. Related Documentation

- Chinese Developer Guide: `docs/MOZA_SDK开发者指南.md`
- English Developer Guide: `docs/MOZA_SDK_Developer_Guide.md`
- Chinese Wheelbase Force Feedback Guide: `docs/基座力反馈指令使用说明.md`
- Wheelbase Force Feedback Command Guide: `docs/Wheelbase_Force_Feedback_Command_Guide.md`
