17370845950

本文详解如何在 scala/java 中使用 jna 正确调用接受 `byte**` 参数的原生函数（如 voicevox core 的 `voicevox_wav_synthesis`），重点解决内存分配、指针解引用与字节数组安全提取问题。

在 Java Native Access（JNA）中，C 函数签名中的 byte** 表示“指向 byte* 的指针”，即函数将动态分配一块内存，并通过该二级指针将新分配的 byte*（数据起始地址）写回调用方。这与 byte*（单级指针，通常对应 byte[] 或 Pointer）有本质区别：前者要求传入一个可被修改的指针容器，而非直接传数组。

JNA 提供了 com.sun.jna.PointerByReference 专为此类场景设计——它封装了一个可被原生代码写入的 void** 级别指针。因此，正确的接口声明应为：

import com.sun.jna.{Library, PointerByReference}
import com.sun.jna.platform.win32.WinDef.HRESULT

class NativeLibrary extends Library {
  // ✅ 正确：接收 byte**，由 native 写入新分配的 buffer 地址
  def voicevox_wav_synthesis(
    coreHandle: Pointer,
    query: Pointer,
    outputWav: PointerByReference
  ): Int
}

调用时需按以下步骤操作：

1. 创建 PointerByReference 实例：作为 byte** 的 Java 端载体；
2. 调用原生函数：函数内部完成 malloc 并将结果地址写入 outputWav；
3. *解引用获取 `byte**：调用pbr.getValue()` 得到实际数据指针；
4. 读取字节数组：必须提前知晓或通过其他方式获知缓冲区长度（如配套的 voicevox_wav_get_size() 函数），再调用 pointer.getByteArray(0, size) 安全拷贝；
5. 显式释放内存：调用对应的 free 函数（如 voicevox_wav_free(dataPointer)），避免 C 层内存泄漏。

完整示例（Scala）：

val pbr = new PointerByReference()
val result = NativeLibrary.INSTANCE.voicevox_wav_synthesis(core, query, pbr)

if (result == 0) {
  val dataPtr = pbr.getValue()
  val size = NativeLibrary.INSTANCE.voicevox_wav_get_size() // 假设存在此辅助函数
  val wavBytes = dataPtr.getByteArray(0, size)

  // ✅ 使用 wavBytes（注意：此时数据已复制到 JVM 堆，安全）
  // ... 处理 WAV 数据

  // ⚠️ 必须释放原生分配的内存
  NativeLibrary.INSTANCE.voicevox_wav_free(dataPtr)
} else {
  throw new RuntimeException(s"Synthesis failed: $result")
}

⚠️ 关键注意事项：

• ❌ 不要使用 Memory 模拟 byte**：虽然 Memory 是 Pointer 子类，但其内存由 JVM 管理，原生函数向其中写入地址会导致未定义行为（如 SEGV）；
• ❌ 不要尝试 Array[Array[Byte]]：JNA 不支持多维数组映射，且语义完全不符；
• ✅ 长度信息不可省略：getByteArray 需明确长度，否则可能越界读取或截断；务必查阅原生库文档确认长度获取方式（常见于配套 getter 函数或输出参数）；
• ✅ 释放责任在调用方：由 func(byte**) 分配的内存，必须由对应 free 函数释放，不可依赖 JVM GC。

综上，PointerByReference 是 JNA 中桥接 T** 输出参数的标准且唯一可靠方式。掌握其生命周期管理（创建 → 调用 → 解引用 → 读取 → 释放）是安全调用此类原生 API 的核心。