1. 功能库调用的第一道坎:先把 Java 调用扫描仪 dll 的链路拆开
把扫描仪接进 Java 业务时,厂商通常只给一个 TWAIN 动态库,Java 不能直接调它的 C 函数,于是要用 JNI 把原生功能库包成 Java 类。这就是 Java 调用扫描仪 dll 的典型场景:TwainScanner.dll 只是桥,真正干活的是 twaindsm.dll。它也不是 System.loadLibrary 一下就完事,TWAIN 初始化按状态机走五步,每一步都有返回码。下面按可照做的顺序,从 Java 契约、JNI 头、C 侧 LoadLibrary 到返回码排查,把这条链路拆开。适合要把扫描能力接进桌面工具、又不想重写 C 侧业务的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Java 侧功能库契约:类名、native 方法与 group 参数怎么定
Java 侧不要一上来就写设备枚举,先把“功能库入口”定死:类名、native 方法名、参数个数和返回码约定。C 侧的 JNI 函数名是由这些信息推出来的,类名改一个字,C 侧导出符号就对不上。功能库封装最怕开头随意,后面编译报 UnsatisfiedLinkError 再回头改名,代价比想象中大。
2.1 先写一个最小可调用的 Java 壳
先让 Java 侧只有一个类、一个 native 方法、一个 main 验证入口。这样 C 侧只需要实现一个函数,返回码也能直接打印出来:
java复制public class TwainScanner {
static {
// 加载 JNI 桥 dll,名字对应 TwainScanner.dll,不是 twaindsm.dll
System.loadLibrary("TwainScanner");
}
// group 传 0 走图像组,传非 0 走控制组;返回值 0 成功,负数表示失败步骤
public native int twainInit(int group);
public static void main(String[] args) {
int rc = new TwainScanner().twainInit(0);
System.out.println("twainInit rc=" + rc);
}
}
System.loadLibrary("TwainScanner") 只负责把 JNI 桥加载进 JVM,它不会替你加载 twaindsm.dll。twainInit 返回 int 而不是 void,是因为初始化需要把失败位置带回来;如果写成 void,后面只能靠异常猜,排查会变成黑匣子。group 只影响应用身份里的 SupportedGroups 取值,不是扫描仪编号,也不是设备索引。
2.2 返回码先约定,再写 C
Java 侧不解析 TWAIN 的 TW_UINT16,C 侧把每一步翻译成固定的负整数。这个约定要在写 C 之前定好,否则 Java 拿到 -3 不知道是打开 DSM 失败,还是打开数据源失败:
| 返回值 | 含义 | 对应 C 侧失败点 |
|---|---|---|
| 0 | 初始化成功 | 五步全部返回 TWRC_SUCCESS |
| -1 | 加载 TWAIN 数据源管理器失败 | LoadLibrary("twaindsm.dll") 返回空 |
| -2 | 取 DSM_Entry 入口失败 |
GetProcAddress 返回空 |
| -3 | 打开数据源管理器失败 | MSG_OPENDSM 返回非成功 |
| -4 | 取默认扫描仪失败 | MSG_GETDEFAULT 返回非成功 |
| -5 | 打开扫描仪数据源失败 | MSG_OPENDS 返回非成功 |
这张表要同时给 Java 调用方和 C 维护者看。Java 侧只做“传 group、收返回码、打日志”,不把 TWAIN 常量搬进 Java;C 侧只做“加载、取入口、开 DSM、取默认源、开源”。两边职责清楚,功能库才不会越包越厚。
2.3 group 参数不是设备编号
group 在 C 侧只参与一行赋值:g_appId.SupportedGroups = group == 0 ? DG_IMAGE : DG_CONTROL;。传 0 时应用身份声明支持图像组,传非 0 时声明支持控制组,适合分两步验证初始化和后续能力。它不能拿来选第二台扫描仪;多设备场景要在 C 侧把 MSG_GETDEFAULT 换成 MSG_GET 再遍历设备列表,而不是在 Java 侧传一个“设备号”。
Java 类保持薄封装还有一个现实原因:JNI 符号名与类名、方法名绑定。类叫 TwainScanner,C 函数就必须是 Java_TwainScanner_twainInit;如果以后加包名,符号会变成 Java_包名_TwainScanner_twainInit。一开始就把类名和方法名定稳,比后面改 C 导出名省事得多。
3. 生成 JNI 头并映射 C 侧功能库入口:从 Java_TwainScanner_twainInit 说起
Java 类写完后,不要手写 JNI 函数签名。让 JDK 自带的 javac -h 生成头文件,C 侧照着函数原型实现,能避免参数类型和符号名对不上。生成出来的头文件还会把 JNIEnv *、jobject、jint 这些类型摆清楚,后面 include 进 C 文件即可。
3.1 用 javac -h 把头文件生成出来
先编译 Java 类并生成 JNI 头,输出目录用 native,C 文件就放在这个目录旁边:
bash复制# 先生成 TwainScanner.class,同时把 JNI 头写到 native 目录
javac -h native src/TwainScanner.java
# 生成的头文件通常是 native/TwainScanner.h
# 里面会出现 Java_TwainScanner_twainInit 的原型
-h native 指定头文件输出目录,src/TwainScanner.java 是 Java 源文件路径。如果 Java 类带了包名,生成的头文件名和函数符号都会带包名,C 侧不能只写 Java_TwainScanner_twainInit。生成后先打开头文件确认函数签名,重点看返回值是不是 jint、第三个参数是不是 jint group。这一步不做,靠记忆手写符号,后面很容易编译出一个“看起来有导出、Java 却找不到”的 dll。
3.2 C 侧 include 与全局句柄
C 文件需要三类头:JNI 头、Windows 动态库 API、TWAIN 协议头。全局句柄保存 DSM 模块和函数指针,保证一次初始化里的多次调用用的是同一个入口:
c复制#include <jni.h>
#include <windows.h>
#include <string.h>
#include "twain.h"
// 保存 TWAIN 数据源管理器模块和 DSM_Entry 函数指针
static HMODULE g_hSource = NULL;
static DSMENTRYPROC g_pDSMEntry = NULL;
// 应用身份和扫描仪数据源身份,TWAIN 初始化过程中会被读写
static TW_IDENTITY g_appId;
static TW_IDENTITY g_sourceId;
JNIEXPORT jint JNICALL
Java_TwainScanner_twainInit(JNIEnv *env, jobject obj, jint group) {
(void)env;
(void)obj;
// 具体五步初始化在下一章展开
return 0;
}
jni.h 提供 JNIEXPORT、JNICALL、jint,windows.h 提供 HMODULE、LoadLibrary、GetProcAddress,twain.h 提供 TW_IDENTITY、DSMENTRYPROC、DG_CONTROL、DAT_IDENTITY、MSG_OPENDSM 这些类型和常量。string.h 是给后面的 memset、strcpy 用,材料里的 C 片段用了这两个函数却没有单独列头文件,实际工程里要补上。
全局句柄不是偷懒,是因为 DSM_Entry 返回的函数指针要在 MSG_OPENDSM、MSG_GETDEFAULT、MSG_OPENDS 之间复用。每次调用都重新 LoadLibrary 会让状态和模块引用计数变乱,排查时也说不清是哪一次加载的。
3.3 身份信息与 group 映射
TWAIN 要求调用方先声明应用身份,再打开数据源管理器。身份信息不用填满,但几个关键字段不能漏:
c复制memset(&g_appId, 0, sizeof(TW_IDENTITY));
g_appId.Id = 0;
strcpy(g_appId.AppName, "JavaTwainDemo");
g_appId.MajorNum = 1;
g_appId.MinorNum = 0;
g_appId.Language = TWLG_ENGLISH;
g_appId.Country = 0; // 区域代号按运行环境填,示例用 0 占位
g_appId.SupportedGroups = group == 0 ? DG_IMAGE : DG_CONTROL;
g_appId.ProtocolMajor = TWON_PROTOCOLMAJOR;
g_appId.ProtocolMinor = TWON_PROTOCOLMINOR;
memset 先把整个结构清零,避免未初始化字段带进协议调用。AppName 用短英文名,长度不要贴 TW_IDENTITY 的边界;示例里 "JavaTwainDemo" 足够短。MajorNum、MinorNum 是应用版本号,示例固定 1 和 0,不改协议版本。ProtocolMajor、ProtocolMinor 用 twain.h 里的常量,别自己写数字。
SupportedGroups 这里用三目表达式,传 0 走 DG_IMAGE,传非 0 走 DG_CONTROL,目的是让同一条初始化链路能分别验证图像组和控制组。正式项目里如果需要同时声明多个组,要按 TWAIN 的位掩码规则设置,不能把这个三目当成通用写法照搬。g_sourceId 先不填,等 MSG_GETDEFAULT 把默认扫描仪身份写回来,MSG_OPENDS 再用它打开设备。
4. C 侧把 TWAIN 功能库拉起来:LoadLibrary、DSM_Entry 与五步初始化
C 侧的 twainInit 只做五件事:加载 twaindsm.dll、取 DSM_Entry、打开 DSM、取默认数据源、打开数据源。每一步失败都返回固定负码,Java 侧就能按码定位。顺序不能反,先开数据源再开 DSM 在 TWAIN 状态机里走不通。
4.1 五步顺序先背下来
| 步骤 | 调用 | 成功条件 | 失败返回 |
|---|---|---|---|
| 1 | LoadLibrary("twaindsm.dll") |
返回非空 HMODULE |
-1 |
| 2 | GetProcAddress(g_hSource, "DSM_Entry") |
返回非空函数指针 | -2 |
| 3 | MSG_OPENDSM |
返回 TWRC_SUCCESS |
-3 |
| 4 | MSG_GETDEFAULT |
返回 TWRC_SUCCESS,写入 g_sourceId |
-4 |
| 5 | MSG_OPENDS |
返回 TWRC_SUCCESS |
-5 |
这张表就是排查主线。Java 打印出 -3,就不用怀疑 LoadLibrary;打印出 -4,说明 DSM 已经打开,问题在默认扫描仪或设备枚举。
4.2 完整 twainInit 实现
下面这段 C 代码把五步串起来,返回码与 Java 侧约定一致:
c复制#include <jni.h>
#include <windows.h>
#include <string.h>
#include "twain.h"
static HMODULE g_hSource = NULL;
static DSMENTRYPROC g_pDSMEntry = NULL;
static TW_IDENTITY g_appId;
static TW_IDENTITY g_sourceId;
JNIEXPORT jint JNICALL
Java_TwainScanner_twainInit(JNIEnv *env, jobject obj, jint group) {
(void)env;
(void)obj;
// 第一步:加载 TWAIN 数据源管理器 dll,通常叫 twaindsm.dll
g_hSource = LoadLibrary("twaindsm.dll");
if (!g_hSource) return -1;
// 第二步:获取 DSM_Entry 入口函数
g_pDSMEntry = (DSMENTRYPROC)GetProcAddress(g_hSource, "DSM_Entry");
if (!g_pDSMEntry) return -2;
// 第三步:填充应用身份信息,TWAIN 要求必须声明身份
memset(&g_appId, 0, sizeof(TW_IDENTITY));
g_appId.Id = 0;
strcpy(g_appId.AppName, "JavaTwainDemo");
g_appId.MajorNum = 1;
g_appId.MinorNum = 0;
g_appId.Language = TWLG_ENGLISH;
g_appId.Country = 0; // 区域代号按运行环境填,示例用 0 占位
g_appId.SupportedGroups = group == 0 ? DG_IMAGE : DG_CONTROL;
g_appId.ProtocolMajor = TWON_PROTOCOLMAJOR;
g_appId.ProtocolMinor = TWON_PROTOCOLMINOR;
// 用 DG_CONTROL 和 DAT_IDENTITY 打开数据源管理器
TW_UINT16 rc = g_pDSMEntry(&g_appId, NULL, DG_CONTROL,
DAT_IDENTITY, MSG_OPENDSM,
(TW_MEMREF)&g_appId);
if (rc != TWRC_SUCCESS) return -3;
// 第四步:选中默认扫描仪,MSG_GETDEFAULT 会把数据源身份写回 g_sourceId
rc = g_pDSMEntry(&g_appId, NULL, DG_CONTROL,
DAT_IDENTITY, MSG_GETDEFAULT,
(TW_MEMREF)&g_sourceId);
if (rc != TWRC_SUCCESS) return -4;
// 第五步:打开扫描仪数据源
rc = g_pDSMEntry(&g_appId, NULL, DG_CONTROL,
DAT_IDENTITY, MSG_OPENDS,
(TW_MEMREF)&g_sourceId);
if (rc != TWRC_SUCCESS) return -5;
return 0;
}
第一步的 LoadLibrary("twaindsm.dll") 加载的是 TWAIN 数据源管理器,它负责找你机器上安装的扫描仪驱动。第二步的 GetProcAddress 按导出名 "DSM_Entry" 取函数指针,名字不能猜,必须和 twain.h 里的声明对齐。第三步的 MSG_OPENDSM 把应用身份交给 DSM,pData 传 &g_appId;第四步 MSG_GETDEFAULT 把默认数据源身份写进 g_sourceId;第五步 MSG_OPENDS 才真正打开扫描仪。
rc 用 TW_UINT16 接返回值,不要用 int 直接接。TWAIN 的返回码是 16 位条件码,虽然这里只判断 TWRC_SUCCESS,但类型对齐能避免头文件版本不一致时出现奇怪的值。g_appId.Id = 0 是应用标识,示例不分配动态 ID;MajorNum、MinorNum 固定 1 和 0,别拿它们当协议版本。
4.3 参数怎么改,失败看哪里
LoadLibrary 的参数只有模块名,不需要路径时按系统搜索顺序找 twaindsm.dll。如果现场机器把它放在非标准目录,优先改环境或把 dll 放到进程可搜索的位置,不要在代码里写死盘符。GetProcAddress 的第二个参数必须是 "DSM_Entry",如果这里返回空,先确认 LoadLibrary 成功并且模块位数与 JVM 一致。
MSG_GETDEFAULT 适合“机器上只有一台默认扫描仪”的场景。材料里的做法是:如果装了好几个扫描仪,需要改成 MSG_GET 然后遍历设备列表。改的时候把 DAT_IDENTITY 的读回逻辑放在循环里,每次拿到一个 TW_IDENTITY 再决定打开哪一个,不要仍然只取一个默认值。
group 只改 SupportedGroups。传 0 时走 DG_IMAGE,传 1 时走 DG_CONTROL;如果初始化在 DG_CONTROL 下成功、在 DG_IMAGE 下失败,问题更可能在数据源能力或后续图像调用,而不是加载链路。先把 twainInit(0) 和 twainInit(1) 各跑一次,再看返回码,比一上来就传图像参数更容易定位。
5. 编译、加载与避坑排查:返回码 -1 到 -5 分别说明什么
这条链路有两层 dll:Java 先加载 TwainScanner.dll,C 代码再加载 twaindsm.dll。两层都可能失败,但报错形态不同。Java 层加载失败通常抛 UnsatisfiedLinkError,C 层失败则通过 twainInit 返回 -1 到 -5。把这两类错误分开看,排查会快很多。
5.1 编译与加载:两层 dll 别混淆
编译 JNI 桥时,关键是把 JDK 的 include 和 include/win32 加进头文件搜索路径,twain.h 放在工程目录或额外 include 路径里:
bash复制# 生成 JNI 头文件
javac -h native src/TwainScanner.java
# 用本机 C 工具链编译 JNI 桥;下面这行按你的编译器替换
# 关键是包含 JDK 的 include 和 win32 子目录,以及 twain.h 所在目录
cc -shared -I"$JAVA_HOME/include" -I"$JAVA_HOME/include/win32" -I. -o TwainScanner.dll TwainScanner.c
-shared 生成动态库,-I"$JAVA_HOME/include" 找 jni.h,-I"$JAVA_HOME/include/win32" 找 jni_md.h,-I. 找当前目录的 twain.h。输出名必须是 TwainScanner.dll,因为 Java 侧 System.loadLibrary("TwainScanner") 会按这个名字找。twaindsm.dll 不需要链进 JNI 桥,代码用的是 LoadLibrary 动态加载,不是静态链接。
运行时如果 TwainScanner.dll 不在默认搜索路径,用 -Djava.library.path 指向它所在目录:
bash复制java -Djava.library.path=./native -cp out TwainScanner
-Djava.library.path 只影响 JNI 桥的查找,不影响 C 代码里 LoadLibrary("twaindsm.dll") 的搜索。后者仍按系统模块搜索顺序找,所以不要把“Java 找不到 TwainScanner.dll”和“C 找不到 twaindsm.dll”混成同一个问题。
5.2 五条返回码排查
下面五条按“现象 → 原因 → 解决”写,都是这条链路上最常见的翻车点:
-
现象:Java 启动就抛
UnsatisfiedLinkError,twainInit根本没执行。
原因:System.loadLibrary("TwainScanner")找不到TwainScanner.dll,或者 C 侧导出函数名与类名、包名不匹配。
解决: 先用-Djava.library.path指向 dll 目录,确认 dll 文件名就是TwainScanner.dll;再打开javac -h生成的头文件,核对函数名是不是Java_TwainScanner_twainInit。如果 Java 类加了包名,C 函数名必须带包名,不能只改 Java 不改 C。 -
现象:
twainInit返回 -1。
原因:LoadLibrary("twaindsm.dll")返回空,系统找不到 TWAIN 数据源管理器,或者 JVM 位数与 dll 位数不一致。
解决: 先确认运行环境里确实有twaindsm.dll,再确认 Java 进程和 dll 位数一致。32 位 JVM 不能加载 64 位TwainScanner.dll,反过来也一样;两层 dll 的位数要跟 JVM 对齐。 -
现象:
twainInit返回 -2。
原因:LoadLibrary成功了,但GetProcAddress(g_hSource, "DSM_Entry")取不到入口,常见是导出名不对或拿到的模块不是预期的 TWAIN 管理器。
解决: 不要凭猜改导出名,按twain.h里的DSM_Entry声明核对;用依赖查看工具看twaindsm.dll的导出表里有没有DSM_Entry。如果现场存在多个同名 dll,先确认加载到的是哪一个。 -
现象:
twainInit返回 -4。
原因:MSG_OPENDSM已经成功,但MSG_GETDEFAULT没取到默认扫描仪;机器上没装数据源、装了多台但没有默认项,或者驱动没就绪。
解决: 先確認扫描仪驱动和数据源安装完成;多设备场景把MSG_GETDEFAULT改成MSG_GET遍历设备列表,不要继续等默认项。排查时打印g_sourceId是否被写回,能区分“没默认源”和“源身份为空”。 -
现象:
twainInit返回 -5。
原因:MSG_OPENDS打开数据源失败,常见是设备被其他扫描软件占用、数据源状态不对,或者前一步拿到的g_sourceId不可用。
解决: 先关掉其他可能占用扫描仪的程序,再重试;确认MSG_GETDEFAULT返回成功后g_sourceId确实有内容;如果设备刚插拔,等驱动状态稳定再调。返回 -5 时不要回头怀疑LoadLibrary,链路已经走到打开设备这一步。
注意:返回码只能告诉你失败在哪一步,不能告诉你驱动内部为什么失败。现场排查时把 Java 打印的返回码、JVM 位数、
java.library.path和 C 侧加载到的 dll 路径一起记录,别只留一个“-5”。
5.3 一个可复用的排查顺序
先看 Java 层有没有异常:有 UnsatisfiedLinkError 就先解决桥 dll 的路径和符号名,不要往下看 TWAIN。Java 层通过后,再看 twainInit 返回码:-1、-2 是加载和取入口,-3 是 DSM 打开,-4 是默认源,-5 是数据源打开。这个顺序能把“桥没加载”和“桥加载了但 TWAIN 初始化失败”分开,避免在 C 代码里乱加日志。
6. 进阶验证:把功能库初始化做成可重复、可观测的流程
初始化跑通一次不算完,换一台机器、换一个 JVM 位数、换一台扫描仪,返回码又会变。我的做法是把返回码翻译成可读标签,先在 Java 侧固定输出,再谈图像传输:
java复制static String describe(int rc) {
switch (rc) {
case 0: return "OK";
case -1: return "LOAD_TWAINDSM_FAILED";
case -2: return "GET_DSM_ENTRY_FAILED";
case -3: return "OPENDSM_FAILED";
case -4: return "GETDEFAULT_FAILED";
case -5: return "OPENDS_FAILED";
default: return "UNKNOWN";
}
}
describe 只做一件事:把负码变成能贴进日志的字符串。调用时先打印 System.getProperty("sun.arch.data.model") 和 java.library.path,再打印 describe(new TwainScanner().twainInit(0)),最后用 twainInit(1) 验证控制组。成功路径也要记录,因为下一次失败时你需要知道上一次成功时用的是哪个 dll 路径、哪个位数、哪台默认设备。失败路径则按已完成的步骤回退:取了 DSM_Entry 但没开 DSM,就释放已加载的模块句柄;开了 DSM 但没开数据源,先按 TWAIN 状态机逆序关闭再退出,别把半开状态留给下一次调用。
从那以后我每次接一个新的功能库,都先把 Java 类、JNI 头、C 侧返回码表和加载路径这四件事固定下来,再谈扫描传输。希望帮到你。
