C ABI & Handles

The rules every call obeys: calling convention, handles, strings, errors, threading.

Calling convention & export macros

Every exported symbol is declared like this:

YUCAD_EXPORT <ret> YUCAD_API CadXxx(...);

#if defined(YUCAD_BUILDING_DLL)
  #define YUCAD_EXPORT __declspec(dllexport)
#else
  #define YUCAD_EXPORT __declspec(dllimport)
#endif
#define YUCAD_API __stdcall

__stdcall matches Vecad and is what Delphi's default stdcall and C#'s CallingConvention.StdCall expect. Names are exported undecorated.

Types at the boundary

ABI type	Definition	Meaning
`YuHandle`	`std::int32_t`	Opaque 32-bit handle to a document, entity, layer, block, style… 0 = invalid.
`YuHwnd`	`void*`	A Win32 `HWND` passed opaquely (host window in, viewport window out).
coordinates	`double`	X, Y, Z world coordinates. Drawings are 2D; Z is carried for DXF fidelity.
angles	`double`	Radians, counter-clockwise, math convention (0 = +X axis).
strings	`const char` / `char buf, int n`	UTF-8. Output strings are written into a caller-supplied buffer.

The handle model

yucad never returns a pointer to an internal object. Instead an internal handle table maps each 32-bit handle to the real C++ object. This is what makes the ABI safe across language and compiler boundaries.

Documents — CadCreate → hDwg. Most calls take hDwg as the first argument.
Entities — every CadAdd* returns hEnt. In yucad the entity handle is the entity id (the two are the same integer), so the CadGetEntityByID family resolves directly against the handle table.
Layers, blocks, text styles, dim styles — their own handles from the matching CadAdd* / CadGet* calls.

Strings are UTF-8

All text crossing the ABI is UTF-8. Input strings are const char*. Output strings follow the caller-allocates pattern:

char buf[256];
CadEntityGetLayerName(dwg, ent, buf, sizeof(buf));

A host that speaks a legacy code page can opt into a code-page bridge via the CadOnEventSelCodepage callback, but the default boundary is UTF-8.

Error handling

No C++ exception ever escapes the DLL. Every extern "C" body is wrapped so a failure returns a sentinel instead of unwinding across the ABI:

Functions returning a handle return 0 on failure.
Functions returning a status return 0/non-zero as documented per family.
Getters write nothing (or a zero value) into out-parameters on failure.

Threading

All calls for a given document must be made on the thread that owns its window — in practice the host's UI thread. yucad does not spin up worker threads that touch document or GL state, and callbacks fire on that same thread.

Constants

The header defines ~400 CAD_* constants — command IDs, snap modes, colours, text-alignment codes, entity types and event IDs — with the same numeric values as Vecad. Browse them on the Constants page.