类型

Java 绑定只翻译 darra_ai.h 的类型和错误码，不另造语义。本页列出公开类型；会话 / 推理 / 运行时行为见对应页。

公开 runtime 包 没有 加密 / 签发类型或符号。xyz.darra.ai.authoring.Authoring 只在 authoring natives 上真正转发；runtime JNI 调用会抛 InternalException。

一览

类别	属性	类型	访问	说明
会话	AiSession	class	公开	推理会话，AutoCloseable。见 会话 页
	SessionOptions	class	公开	开会话的可扩展选项。构造不加载 native
图像	ImageDesc	class	公开	对应 darra_image_desc。工厂：auto / encoded / rgb888 / bgr888
	PixelFormat	enum	公开	与 darra_image_format 逐值对齐：AUTO(0) / ENCODED(1) / RGB888(2) / BGR888(3)
运行时	AiRuntime	class	公开	ensure / ensureCancel / 版本。见 运行时 页
	AiRuntime.ProgressListener	interface	公开	进度回调。回调内禁止再调本 SDK
	AiDiagnostics	class	公开	collect() 环境自检 JSON（去敏）
加载 / 错误	NativeLoader	class	公开	加载 JNI + Core；HEADER_MAJOR / runtimeClassifier / PROP_NATIVES_DIR
	AiException	class	公开	每个 darra_error_code（除 OK）一个嵌套子类。见 错误处理 页

包名一律 xyz.darra.ai。SessionMeta 是包内实现，不对外。本绑定没有 openPlainEx，没有 GRAY8 / RGBA8888 工厂，SessionOptions 没有 C 头的线程数 / CPU 亲和字段。

PixelFormat

与 darra_image_format 逐值对齐。未知整值 fromCode 抛 InternalException，不静默当成 AUTO。

public enum PixelFormat {
    AUTO(0),     // 按字节魔数自嗅探编码格式（JPG/PNG/BMP）。裸缓冲禁止用 AUTO
    ENCODED(1),  // 显式声明为已编码字节流；行为同 AUTO
    RGB888(2),   // 裸缓冲，RGB 三通道 8bit，须给宽高
    BGR888(3),   // 裸缓冲，BGR 三通道 8bit，须给宽高
}

code()

public int code()

对应 C 枚举整值。

返回值:

• int — darra_image_format 整值

PixelFormat.fromCode(int code)

public static PixelFormat fromCode(int code)

由 C 枚举整值还原。未知值抛契约异常，不静默当成 AUTO。

参数:

• code (int) — C 枚举整值

返回值:

• PixelFormat — 对应枚举

C 头另有 DARRA_IMAGE_GRAY8(4) / DARRA_IMAGE_RGBA8888(5)。本 Java 绑定未暴露这两项；不要自己填 4/5 绕过工厂。

ImageDesc 工厂与字段见 推理。

SessionOptions

开会话的可扩展选项。字段对应 darra_session_open 的可选通道。构造本对象不加载 native。本类型是不可变的：keyPath(...) / password(...) / preferProvider(...) 返回新实例。

SessionOptions opt = SessionOptions.empty()
        .keyPath("model.darmkey")
        .password(null)
        .preferProvider(null);

SessionOptions.empty()

public static SessionOptions empty()

全部可选通道为空。

返回值:

• SessionOptions — 空选项

SessionOptions.of(String keyPath, String password, String preferProvider)

public static SessionOptions of(String keyPath, String password, String preferProvider)

一次给定三个可选通道。任一可为 null。

参数:

• keyPath (String) — .darmkey 路径
• password (String) — 永久密码
• preferProvider (String) — 指名 Provider

返回值:

• SessionOptions — 选项

keyPath(String keyPath)

public SessionOptions keyPath(String keyPath)
public String keyPath()

.darmkey 路径；null = 走密码/试用通道。setter 返回新对象。

参数:

• keyPath (String) — 路径，可为 null

返回值:

• SessionOptions — 新选项（setter）
• String — 当前值（getter）

password(String password)

public SessionOptions password(String password)
public String password()

永久密码；null = 走授权文件/试用通道。setter 返回新对象。

参数:

• password (String) — 密码，可为 null

返回值:

• SessionOptions — 新选项（setter）
• String — 当前值（getter）

preferProvider(String preferProvider)

public SessionOptions preferProvider(String preferProvider)
public String preferProvider()

指名 Provider；null = 自动选。指名但不可用 = fail-closed。setter 返回新对象。Windows 上指名 edge-rknn 在打开时抛 UnsupportedPlatformException。

参数:

• preferProvider (String) — Provider ID，可为 null

返回值:

• SessionOptions — 新选项（setter）
• String — 当前值（getter）

C 的 darra_session_options（intra_op_threads / inter_op_threads / cpu_affinity_mask）尚未出现在本 Java 类型上。openEx 当前翻译到 open；Core 落地 darra_session_open_ex 后只换调用点，本类型已公开字段不变。禁止改 Windows ReservedCpuSets，禁止动 PLC 隔离核。

NativeLoader

加载 JNI 桥接库与 DarraAI.Core。主 jar 不内嵌 dll/so。AiSession / AiRuntime / AiDiagnostics 的静态块都会调 NativeLoader.load()，一般不必手调。

属性	类型	说明
HEADER_MAJOR	int	与 darra_ai.h 的 DARRA_VERSION_MAJOR 对齐（1）
PROP_NATIVES_DIR	String	系统属性名 xyz.darra.ai.natives.dir，指向本地 natives 目录

加载顺序：

1. 系统属性 xyz.darra.ai.natives.dir 指向的目录
2. classpath 上 natives/<os>-<arch>/
3. java.library.path / System.loadLibrary("darraai_jni")（Core 先试 DarraAI.Core，再试 darraai_core）

Windows 仅 x64。macOS / 32 位 / 其它架构 → UnsupportedPlatformException。Windows 无 RKNN。

NativeLoader.load()

public static void load()

幂等加载。major 与头文件不一致则拒绝继续。

NativeLoader.isLoaded()

public static boolean isLoaded()

本进程是否已成功加载 native。

返回值:

• boolean — 已加载则为 true

NativeLoader.osArch()

public static String osArch()

本机标识：windows-x86_64 / linux-x86_64 / linux-aarch64。其它 OS/架构抛 UnsupportedPlatformException。

返回值:

• String — os-arch 标识

NativeLoader.runtimeClassifier()

public static String runtimeClassifier()

Maven classifier，runtime 风味：natives-windows-x86_64 等。

返回值:

• String — classifier

NativeLoader.authoringClassifier()

public static String authoringClassifier()

Maven classifier，authoring 风味（仅 AI Studio）：natives-windows-x86_64-authoring。

返回值:

• String — classifier

ProgressListener

定义见 安装。percent 0..100，每个 stage 内单调不降。stage ∈ probe / manifest / download / verify / install / done。回调在 SDK 工作线程触发：回调里禁止调用任何本 SDK 方法。

版本常量

AiRuntime.VERSION_MAJOR / VERSION_MINOR / VERSION_PATCH 与头文件 DARRA_VERSION_* 对齐，当前 1.0.0。打包查询走 packedVersion() / versionString()，不要自己拼。见 版本与诊断。