# API reference

The public C headers are the binary contract. C++ wrappers are local convenience
types, compiled into your library. Link `EpicTuner::SDK` for C or
`EpicTuner::SDKCpp` for C++20. No Qt types appear in either public surface.

## Header and service map

| Header | Public surface | Detailed contract |
|---|---|---|
| [plugin.h](../include/epictuner/plugin.h) | Query, host/plugin tables, versions, capabilities, errors, values, handles, async options | [Foundation](FOUNDATION.md), [ABI/wire contract](CONTRACT.md) |
| [ui.h](../include/epictuner/ui.h) | Nodes/properties, panel definitions, patches, UI events/actions | [UI](UI.md), [prefabs](PREFABS.md) |
| [read.h](../include/epictuner/read.h) | Project, channels, datalog and settings request/reply tables | [Reads](READ.md) |
| [tune.h](../include/epictuner/tune.h) | Calibration catalog, snapshots, proposals, apply, undo/redo, status and burn | [Tune](TUNE.md) |
| [plugin.h jobs declarations](../include/epictuner/plugin.h) | Cancellation-aware background work and bounded result buffers | [Jobs](JOBS.md) |
| [license.h](../include/epictuner/license.h) | Entitlement status, challenge, activation and deactivation | [Licensing](LICENSE.md) |
| [window.h](../include/epictuner/window.h) | Independent native-window registration and dispatcher ticks | [Windows](WINDOW.md) |

## C++ wrappers

| Type | Purpose |
|---|---|
| [Context, Plugin, Adapter](../include/epictuner/sdk/plugin.hpp) | Service discovery, capabilities, logging, exception-contained entry/lifecycle adapters |
| [PanelBuilder, Ui](../include/epictuner/sdk/ui.hpp) | Own construction storage, define/open/patch panels and dispatch UI callbacks |
| [Reads, ReadCallback](../include/epictuner/sdk/read.hpp) | Initialize bounded requests and wrap read completions |
| [Tune, TuneChange](../include/epictuner/sdk/tune.hpp) | Encode finite normalized-edit proposals without locale-dependent number formatting |
| [Jobs](../include/epictuner/sdk/jobs.hpp) | Submit and cancel worker background tasks |
| [et_license_service](../include/epictuner/license.h) | Negotiate the C licensing table with Context::service |
| [Window](../include/epictuner/sdk/window.hpp) | Register an independent worker-owned native window |

## Entry point and negotiation

Export `et_plugin_query(const et_query*, et_plugin_api*)` with the calling
convention and visibility macros supplied in `plugin.h`. C++ authors normally
use `ET_PLUGIN(MyPlugin)`. Query fills a caller-sized table and negotiates the
supported ABI minor; incompatible majors fail.

Declare capabilities in both the plugin's static bitmask and its manifest.
The host grants only those authorized for that plugin. Required named features
must be available before startup. Optional features must still be negotiated
before use. SDK package version 1.0.0 does not change C ABI 1.1.

## Service call patterns

`Context::service` obtains a sized/versioned table. Wrapper `connect` methods
perform this negotiation. Check the result before calling methods on the wrapper.
`Reads::make(operation, generation)` initializes fields including `struct_size`
and the default bounded count. Supply only the fields described by the service.

`Ui::define`, `Ui::open`, `Ui::patch` and `Ui::action` return immediate validation
or queue status and optionally deliver an `et_completion`. Read-derived services
deliver an `et_read_reply` through `ReadCallback`. Do not confuse request
acceptance with completion.

UI patch revisions and tune revisions are independent. Use the latest UI
event/completion revision for patches, and the tune catalog/snapshot revision
for edit proposals. An edit proposal also needs the definition identity,
project generation and expected stored values.

## Common errors

For every control's event type and payload, see the
[UI control event and property tables](UI.md#event-value-types). Selects emit
`ET_VALUE_F64` zero-based indexes through `ET_UI_EVENT_SELECTED`; set their value
using `ET_UI_SELECTED_INDEX`, not the legacy event constant `ET_UI_SELECTED`.

| Result | Meaning and next action |
|---|---|
| `ET_ERROR_ARGUMENT` | Invalid type, size, reserved field or value; fix the request |
| `ET_ERROR_ABI` / `ET_ERROR_UNSUPPORTED` | Version/feature unavailable; check negotiation and host version |
| `ET_ERROR_CAPABILITY` | Missing grant; align manifest, plugin declaration and authorized action |
| `ET_ERROR_STATE` | Wrong thread or lifecycle/context state; dispatch correctly and refresh context |
| `ET_ERROR_LIMIT` | Bounded queue/data limit; reduce the request, page data or wait for completion |
| `ET_ERROR_STALE` | Expired session/project token; obtain a new handle |
| `ET_ERROR_CONFLICT` | Base revision/expected value changed; reread and recompute the preview |
| `ET_ERROR_CANCELLED` | Operation cancelled; release local ownership without replay |
| `ET_ERROR_CALLBACK` | Callback threw or violated its contract; inspect worker diagnostics |

The exact values, additional error codes and structure layouts are in
[plugin.h](../include/epictuner/plugin.h). [Troubleshooting](TROUBLESHOOTING.md)
covers loading, dependencies and host diagnostics.

## Complete working code

Use the [starter](../templates/panel/plugin.cpp) for lifecycle/UI,
[telemetry](../examples/live-telemetry/telemetry.cpp) for subscriptions,
[analyzer](../examples/log-analyzer/analyzer.cpp) for cancellable background
statistics, and [calibration helpers](../examples/common/calibration.hpp) for
normalized proposals. These sources are built as SDK consumers in the release
gate, so they are the preferred copyable references.