議實現(xiàn)掃描儀對接完整源碼與避坑指南)
簡介這份源碼資源面向需要在 Windows 平臺下開發(fā)掃描儀控制程序的 VC 開發(fā)者基于 TWAIN 協(xié)議實現(xiàn)完整的圖像采集流程涵蓋從初始化數(shù)據(jù)源管理器、枚舉并選擇掃描設備到設置分辨率與掃描區(qū)域、啟動掃描、處理位圖數(shù)據(jù)以及關閉會話釋放資源的全過程。資源包共 66 個文件約 21.79MB以 h 頭文件、cpp 源文件、obj 編譯中間文件、rc 資源腳本、vcxproj 工程配置及 sln 解決方案為主另含 manifest、pdb、ico 等輔助文件工程結(jié)構(gòu)完整可直接在 Visual Studio 中打開編譯調(diào)試。目前已有 1574 人學習下載。通過研讀源碼讀者能夠掌握 TWAIN 接口的調(diào)用方式、掃描參數(shù)的用戶界面控制邏輯以及掃描結(jié)果的處理思路對圖像處理、文檔數(shù)字化等方向的 Windows 應用開發(fā)具有實際參考價值。1. 掃描儀對接這件事為什么TWAIN到今天還在用接手一個文檔電子化項目時最容易被低估的環(huán)節(jié)就是掃描儀對接。業(yè)務方覺得“點一下掃描按鈕”就完事實際動手才發(fā)現(xiàn)驅(qū)動型號五花八門、廠商SDK各不相同、有的設備只認TWAIN、有的只認WIA還有的兩種都支持但行為不一致。VC 使用TWAIN協(xié)議實現(xiàn)掃描儀完整源碼這個方向解決的正是“不依賴廠商私有SDK、用一套通用接口把掃描儀接進自己程序”的問題。TWAIN是一套跨廠商的圖像采集接口標準Windows上絕大多數(shù)平板掃描儀、饋紙式掃描儀都支持它。它適合誰適合需要在MFC或Win32桌面程序里內(nèi)嵌掃描功能、又不想為每個品牌單獨適配的開發(fā)者。核心思路是你的程序作為“數(shù)據(jù)源管理器”的客戶端通過一個動態(tài)庫加載目標掃描儀的數(shù)據(jù)源用消息回調(diào)驅(qū)動整個掃描流程。聽起來繞但拆開看就是幾個固定步驟。2. TWAIN的三層結(jié)構(gòu)和消息驅(qū)動模型2.1 數(shù)據(jù)源管理器、數(shù)據(jù)源、應用程序各管什么TWAIN的架構(gòu)是三層應用程序你的VC程序、數(shù)據(jù)源管理器DSM通常是一個叫TWAIN_32.DLL或TWAINDSM.DLL的動態(tài)庫、數(shù)據(jù)源DS每個掃描儀廠商提供的驅(qū)動。應用程序不直接跟掃描儀對話而是先加載DSM由DSM去枚舉和打開具體的DS。這個設計的好處是應用程序只需要認識DSM這一套接口換掃描儀時只要換DS就行。三層之間的通信靠兩種機制一種是調(diào)用DSM導出的函數(shù)比如DSM_Entry另一種是DS向應用程序窗口發(fā)送消息。消息驅(qū)動是TWAIN最容易讓人懵的地方——掃描不是“調(diào)用一個函數(shù)然后等返回”而是“發(fā)一個命令然后等DS往你的窗口發(fā)消息你在消息處理里回應”。整個流程像一場來回傳球而不是一次直線調(diào)用。我一般會把狀態(tài)機畫在紙上再寫代碼。TWAIN定義了7個狀態(tài)從狀態(tài)1DSM未加載到狀態(tài)7數(shù)據(jù)傳輸中。每個操作都要求當前狀態(tài)匹配狀態(tài)不對就返回失敗。很多新手翻車就翻在這里沒打開DS就直接調(diào)能力設置或者傳輸沒結(jié)束就關DS結(jié)果程序卡死或者掃描儀報錯。2.2 從狀態(tài)1到狀態(tài)7一次掃描要經(jīng)過哪些狀態(tài)狀態(tài)1是初始態(tài)DSM還沒加載。調(diào)用DSM_Entry的MSG_OPENDSM后進入狀態(tài)2此時DSM已加載但沒打開任何DS。接著MSG_OPENDS打開指定掃描儀進入狀態(tài)3。狀態(tài)3是“DS已打開但未啟用”這時可以查詢和設置能力比如分辨率、色彩模式、掃描區(qū)域。調(diào)用MSG_ENABLEDS后進入狀態(tài)4DS開始工作。如果DS需要顯示自己的配置界面會進入狀態(tài)5如果直接開始傳輸圖像進入狀態(tài)6。狀態(tài)6是數(shù)據(jù)傳輸中DS會不斷發(fā)消息告訴你有一張圖傳過來了。傳輸完成后回到狀態(tài)5或狀態(tài)4最后MSG_DISABLEDS回到狀態(tài)3MSG_CLOSEDS回到狀態(tài)2MSG_CLOSEDSM回到狀態(tài)1。這套狀態(tài)機是TWAIN的骨架。寫代碼時我會用一個變量記錄當前狀態(tài)每次調(diào)用DSM_Entry前先檢查狀態(tài)是否允許。下面這張表是我常用的狀態(tài)與操作對照放在手邊隨時查。當前狀態(tài)允許的操作典型調(diào)用1加載DSMMSG_OPENDSM2打開DS、查詢DSM能力MSG_OPENDS3設置能力、啟用DSMSG_ENABLEDS、MSG_GET/SET4傳輸圖像、禁用DSMSG_ENABLEDS(帶傳輸)、MSG_DISABLEDS5傳輸圖像、關閉UIMSG_ENABLEDS6接收數(shù)據(jù)、結(jié)束傳輸處理MSG_XFERREADY7結(jié)束傳輸MSG_ENDXFER2.3 消息回調(diào)為什么你的窗口過程要處理TWAIN消息DS向應用程序發(fā)消息時用的是你注冊時提供的窗口句柄。所以你的主窗口或一個隱藏窗口的WindowProc里必須處理幾個TWAIN專用消息。最核心的是MSG_XFERREADY表示DS已經(jīng)準備好一張圖像等你來取。還有MSG_CLOSEDSREQ表示DS請求關閉MSG_DEVICEEVENT表示設備事件比如掃描儀上的按鈕被按下。處理這些消息時不能做耗時操作否則會阻塞DS。我一般只做標記把實際的數(shù)據(jù)獲取放到主循環(huán)或單獨線程里。下面是一個窗口過程里處理TWAIN消息的骨架// 假設已經(jīng)定義了全局的TWAIN會話結(jié)構(gòu) LRESULT CALLBACK WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam) { switch (msg) { case WM_TWAIN_XFERREADY: // 自定義消息由DS發(fā)來 // 只做標記不在這里做耗時傳輸 g_bXferReady TRUE; PostMessage(hWnd, WM_APP 1, 0, 0); // 投遞到主循環(huán)處理 return 0; case WM_TWAIN_CLOSEDSREQ: // DS請求關閉需要走禁用和關閉流程 g_bCloseRequest TRUE; PostMessage(hWnd, WM_APP 2, 0, 0); return 0; case WM_TWAIN_DEVICEEVENT: // 設備事件比如掃描儀按鈕 // 一般記錄事件類型按需處理 return 0; default: return DefWindowProc(hWnd, msg, wParam, lParam); } }這段代碼的關鍵點是窗口過程只做消息分發(fā)不直接調(diào)用DSM_Entry去取圖像。因為取圖像可能觸發(fā)DS再次發(fā)消息如果在窗口過程里遞歸調(diào)用容易造成死鎖或狀態(tài)混亂。用PostMessage投遞到主消息隊列讓主循環(huán)在合適的狀態(tài)下處理是更穩(wěn)的做法。參數(shù)方面WM_TWAIN_XFERREADY這類消息的數(shù)值需要根據(jù)TWAIN頭文件里的定義來不同版本的DSM可能略有差異但核心幾個是固定的。3. 用VC把TWAIN會話跑起來的最小實現(xiàn)3.1 加載DSM和打開數(shù)據(jù)源的完整代碼第一步是加載DSM。TWAIN的DSM通常以動態(tài)庫形式存在32位程序用TWAIN_32.DLL64位程序用TWAINDSM.DLL。加載后拿到DSM_Entry函數(shù)指針后續(xù)所有操作都通過它。下面是我常用的加載和打開DS的代碼// 定義DSM_Entry函數(shù)指針類型 typedef TW_UINT16 (FAR PASCAL *DSMENTRYPROC)(pTW_IDENTITY, pTW_IDENTITY, TW_UINT32, TW_UINT16, TW_UINT16, TW_MEMREF); DSMENTRYPROC g_pDSMEntry nullptr; TW_IDENTITY g_AppIdentity {0}; TW_IDENTITY g_SrcIdentity {0}; TW_UINT16 g_CurrentState 1; // 初始狀態(tài) bool LoadDSM() { // 根據(jù)程序位數(shù)選擇DSM庫名 const char* dsmName TWAINDSM.DLL; // 64位 HMODULE hDSM LoadLibraryA(dsmName); if (!hDSM) { // 嘗試32位庫名 hDSM LoadLibraryA(TWAIN_32.DLL); if (!hDSM) return false; } g_pDSMEntry (DSMENTRYPROC)GetProcAddress(hDSM, DSM_Entry); if (!g_pDSMEntry) return false; // 填充應用程序標識 g_AppIdentity.Id 0; g_AppIdentity.Version.MajorNum 1; g_AppIdentity.Version.MinorNum 0; g_AppIdentity.Version.Language TWLG_CHINESE_SIMPLIFIED; g_AppIdentity.Version.Country TWCY_CHINA; strcpy_s(g_AppIdentity.Version.Info, 1.0.0); strcpy_s(g_AppIdentity.ProductName, MyScanApp); strcpy_s(g_AppIdentity.Manufacturer, MyCompany); strcpy_s(g_AppIdentity.ProductFamily, Document); g_AppIdentity.ProtocolMajor TWON_PROTOCOLMAJOR; g_AppIdentity.ProtocolMinor TWON_PROTOCOLMINOR; g_AppIdentity.SupportedGroups DG_IMAGE | DG_CONTROL; // 打開DSM狀態(tài)1 - 狀態(tài)2 TW_UINT16 rc g_pDSMEntry(g_AppIdentity, nullptr, DG_CONTROL, DAT_PARENT, MSG_OPENDSM, (TW_MEMREF)g_hWnd); if (rc ! TWRC_SUCCESS) return false; g_CurrentState 2; return true; } bool OpenDataSource() { if (g_CurrentState ! 2) return false; // 打開默認數(shù)據(jù)源狀態(tài)2 - 狀態(tài)3 TW_UINT16 rc g_pDSMEntry(g_AppIdentity, nullptr, DG_CONTROL, DAT_IDENTITY, MSG_OPENDS, (TW_MEMREF)g_SrcIdentity); if (rc ! TWRC_SUCCESS) return false; g_CurrentState 3; return true; }邏輯說明LoadDSM先嘗試加載64位DSM庫失敗再試32位。拿到DSM_Entry后填充應用程序標識這個標識告訴DSM是誰在調(diào)用。MSG_OPENDSM需要傳入一個窗口句柄DS后續(xù)的消息會發(fā)到這個窗口。OpenDataSource用MSG_OPENDS打開默認數(shù)據(jù)源如果機器上有多個掃描儀可以先枚舉再選擇。參數(shù)方面g_AppIdentity里的ProtocolMajor和ProtocolMinor要和DSM支持的版本匹配一般用頭文件里的宏。SupportedGroups聲明你支持的能力組DG_IMAGE和DG_CONTROL是必須的。3.2 設置分辨率、色彩模式和掃描區(qū)域打開DS后狀態(tài)3下可以設置能力。TWAIN的能力用“能力容器”管理每個能力有一個ID比如ICAP_XRESOLUTION是水平分辨率ICAP_PIXELTYPE是像素類型。設置能力用MSG_SET查詢用MSG_GET。下面是一個設置分辨率和色彩模式的例子bool SetResolution(TW_UINT16 xRes, TW_UINT16 yRes) { if (g_CurrentState ! 3) return false; // 設置水平分辨率 TW_UINT16 rc g_pDSMEntry(g_AppIdentity, g_SrcIdentity, DG_IMAGE, DAT_IMAGEINFO, MSG_SET, (TW_MEMREF)xRes); // 注意實際設置分辨率用的是ICAP_XRESOLUTION這里簡化示意 // 正確做法是構(gòu)造TW_CAPABILITY結(jié)構(gòu) return rc TWRC_SUCCESS; }上面這段是簡化示意實際設置能力需要構(gòu)造TW_CAPABILITY結(jié)構(gòu)指定能力ID、容器類型和值。我一般封裝一個SetCapability函數(shù)把能力ID和值傳進去內(nèi)部處理容器分配和釋放。色彩模式常用的是TWPT_RGB彩色、TWPT_GRAY灰度、TWPT_BW黑白。掃描區(qū)域用ICAP_FRAMES設置單位是英寸的千分之一。這些參數(shù)設不好掃出來的圖要么太大要么太小要么顏色不對。提示設置能力前先用MSG_GET查詢當前值和支持范圍不要盲目設一個超出范圍的值否則DS可能返回失敗或者用默認值覆蓋。3.3 觸發(fā)掃描并接收圖像數(shù)據(jù)設置完能力后調(diào)用MSG_ENABLEDS進入狀態(tài)4或5。如果傳入的TW_USERINTERFACE結(jié)構(gòu)里ShowUI為TRUEDS會彈出自己的配置界面用戶點“掃描”后開始傳輸。如果ShowUI為FALSEDS直接開始傳輸。傳輸過程中DS會發(fā)MSG_XFERREADY消息你在窗口過程里標記后在主循環(huán)里調(diào)用MSG_GET獲取圖像數(shù)據(jù)。獲取圖像數(shù)據(jù)用DG_IMAGE / DAT_IMAGENATIVEXFER拿到的是一個句柄里面是設備無關位圖DIB格式的數(shù)據(jù)。你可以把它保存成BMP文件或者轉(zhuǎn)成其他格式。下面是一個獲取并保存BMP的簡化流程void OnXferReady() { if (g_CurrentState ! 6 g_CurrentState ! 5) return; HANDLE hBitmap nullptr; TW_UINT16 rc g_pDSMEntry(g_AppIdentity, g_SrcIdentity, DG_IMAGE, DAT_IMAGENATIVEXFER, MSG_GET, (TW_MEMREF)hBitmap); if (rc TWRC_XFERDONE hBitmap) { // hBitmap是DIB數(shù)據(jù)可以保存為BMP SaveDIBToBmp(hBitmap, scan_output.bmp); GlobalFree(hBitmap); } // 結(jié)束傳輸狀態(tài)6 - 狀態(tài)5或4 g_pDSMEntry(g_AppIdentity, g_SrcIdentity, DG_CONTROL, DAT_PENDINGXFERS, MSG_ENDXFER, nullptr); }邏輯說明MSG_GET拿到的是DIB句柄不是HBITMAP需要按DIB格式解析文件頭和信息頭。SaveDIBToBmp是我自己封裝的函數(shù)把DIB數(shù)據(jù)加上BMP文件頭寫盤。傳輸結(jié)束后必須調(diào)MSG_ENDXFER否則DS會一直停在傳輸狀態(tài)。如果有多頁MSG_ENDXFER后DS可能再次發(fā)MSG_XFERREADY循環(huán)處理即可。4. 多頁掃描、內(nèi)存管理和UI線程的避坑記錄4.1 現(xiàn)象掃第二頁時程序卡死原因第一頁傳輸結(jié)束后沒有正確調(diào)用MSG_ENDXFER或者調(diào)用后沒有檢查返回值。DS在等待應用程序確認傳輸結(jié)束應用程序卻在等DS發(fā)下一張的消息雙方互相等死鎖。解決每次MSG_GET成功后無論是否還有下一頁都要調(diào)MSG_ENDXFER。如果返回值是TWRC_SUCCESS且后續(xù)還有頁DS會再發(fā)MSG_XFERREADY如果返回值里帶TWRC_XFERDONE說明沒有更多頁了。4.2 現(xiàn)象掃描大圖時內(nèi)存暴漲原因每次MSG_GET返回的DIB句柄需要應用程序自己釋放。如果只保存不釋放或者保存后忘記GlobalFree內(nèi)存會持續(xù)增長。另外如果開了多頁掃描每頁都保留在內(nèi)存里也會爆。解決每頁處理完立即釋放句柄需要多頁合并的話只保留必要的數(shù)據(jù)或者直接寫盤。我一般掃一頁存一頁不在內(nèi)存里堆。4.3 現(xiàn)象DS的配置界面彈不出來原因調(diào)用MSG_ENABLEDS時傳入的窗口句柄不對或者ShowUI設了FALSE。另外如果DSM加載的是32位版本而程序是64位或者反過來也會導致界面無法顯示。解決確認程序位數(shù)和DSM庫位數(shù)一致。ShowUI根據(jù)需求設置需要用戶選參數(shù)就設TRUE。窗口句柄用主窗口的不要用臨時窗口。4.4 現(xiàn)象設置分辨率后掃描儀沒反應原因能力設置失敗但沒檢查返回值。有些掃描儀不支持某些分辨率或者支持的范圍和你想的不一樣。解決設置前先MSG_GET查詢支持的范圍在范圍內(nèi)取值。設置后檢查返回值失敗就回退到默認值。不要假設所有掃描儀都支持300dpi或600dpi。4.5 現(xiàn)象程序退出時掃描儀燈不滅原因沒有按順序關閉DS和DSM。正確的關閉順序是MSG_DISABLEDS狀態(tài)4/5到3、MSG_CLOSEDS狀態(tài)3到2、MSG_CLOSEDSM狀態(tài)2到1。漏掉任何一步DS可能保持打開狀態(tài)。解決在程序退出或掃描完成時按狀態(tài)機順序逐步關閉每步檢查返回值。5. 把TWAIN封裝成可復用類的幾個技巧5.1 用狀態(tài)機類管理會話生命周期把狀態(tài)變量、DSM句柄、DS標識封裝到一個類里所有操作作為成員函數(shù)每次調(diào)用前檢查狀態(tài)。這樣調(diào)用方不需要關心狀態(tài)轉(zhuǎn)換細節(jié)只調(diào)Open、SetCap、Scan、Close幾個方法。我一般會寫一個CTwainSession類構(gòu)造函數(shù)里加載DSM析構(gòu)函數(shù)里確保關閉。狀態(tài)轉(zhuǎn)換用私有方法失敗時記錄錯誤碼。5.2 異步掃描與進度反饋TWAIN的消息機制天然適合異步。把掃描放在工作線程里主線程處理UI。工作線程調(diào)用MSG_ENABLEDS后進入消息循環(huán)收到MSG_XFERREADY就取數(shù)據(jù)取完發(fā)通知給主線程更新進度。注意DSM_Entry不是線程安全的所有TWAIN調(diào)用要在同一個線程里。我一般把TWAIN會話固定在一個線程其他線程通過消息和它通信。5.3 兼容不同DSM版本的注意事項不同版本的DSM對某些能力的支持不一樣。比如老版本可能不支持ICAP_AUTODISCARDBLANKPAGES新版本支持。調(diào)用前先MSG_GET查詢返回TWRC_FAILURE就跳過。另外32位和64位DSM的庫名不同加載時要根據(jù)編譯目標選擇。如果程序需要同時支持兩種可以用條件編譯或者運行時判斷。5.4 一個可復用的能力設置封裝下面這個函數(shù)封裝了能力設置傳入能力ID和值內(nèi)部處理容器分配和釋放bool SetCapability(TW_UINT16 capId, TW_UINT16 type, void* pValue, TW_UINT32 size) { if (g_CurrentState ! 3) return false; TW_CAPABILITY cap {0}; cap.Cap capId; cap.ConType TWON_ONEVALUE; cap.hContainer GlobalAlloc(GHND, sizeof(TW_ONEVALUE) size); if (!cap.hContainer) return false; pTW_ONEVALUE pVal (pTW_ONEVALUE)GlobalLock(cap.hContainer); pVal-ItemType type; memcpy(pVal-Item, pValue, size); GlobalUnlock(cap.hContainer); TW_UINT16 rc g_pDSMEntry(g_AppIdentity, g_SrcIdentity, DG_CONTROL, DAT_CAPABILITY, MSG_SET, (TW_MEMREF)cap); GlobalFree(cap.hContainer); return rc TWRC_SUCCESS; }邏輯說明TW_CAPABILITY結(jié)構(gòu)里ConType指定容器類型TWON_ONEVALUE表示單值。hContainer是全局內(nèi)存句柄里面放TW_ONEVALUE結(jié)構(gòu)加實際值。設置完必須釋放容器否則內(nèi)存泄漏。參數(shù)capId是能力IDtype是值類型如TWTY_UINT16pValue指向?qū)嶋H值size是值的大小。這個封裝把容器管理藏起來調(diào)用方只需要關心能力ID和值。5.5 驗證掃描結(jié)果是否正確的幾個檢查點掃出來的圖不對先查這幾個地方分辨率設置是否生效看圖像像素尺寸和預期是否一致、色彩模式是否正確彩色圖是不是灰度了、掃描區(qū)域是否覆蓋了文檔有沒有截斷。我一般會在保存圖像后打印圖像寬高和位深和預期對比。如果DS支持還可以用ICAP_PIXELTYPE查詢當前像素類型確認設置生效。這套TWAIN方案我用了幾年最大的教訓是不要假設掃描儀會按你想的行為工作。每臺設備的能力支持范圍、默認值、對異常狀態(tài)的反應都不一樣。寫代碼時多查返回值多打日志遇到問題先看狀態(tài)機走到哪一步了。希望幫到你。本文還有配套的精品資源點擊獲取 VC++ 使用TWAIN協(xié)議實現(xiàn)掃描儀對接完整源碼與避坑指南
簡介這份源碼資源面向需要在 Windows 平臺下開發(fā)掃描儀控制程序的 VC 開發(fā)者基于 TWAIN 協(xié)議實現(xiàn)完整的圖像采集流程涵蓋從初始化數(shù)據(jù)源管理器、枚舉并選擇掃描設備到設置分辨率與掃描區(qū)域、啟動掃描、處理位圖數(shù)據(jù)以及關閉會話釋放資源的全過程。資源包共 66 個文件約 21.79MB以 h 頭文件、cpp 源文件、obj 編譯中間文件、rc 資源腳本、vcxproj 工程配置及 sln 解決方案為主另含 manifest、pdb、ico 等輔助文件工程結(jié)構(gòu)完整可直接在 Visual Studio 中打開編譯調(diào)試。目前已有 1574 人學習下載。通過研讀源碼讀者能夠掌握 TWAIN 接口的調(diào)用方式、掃描參數(shù)的用戶界面控制邏輯以及掃描結(jié)果的處理思路對圖像處理、文檔數(shù)字化等方向的 Windows 應用開發(fā)具有實際參考價值。1. 掃描儀對接這件事為什么TWAIN到今天還在用接手一個文檔電子化項目時最容易被低估的環(huán)節(jié)就是掃描儀對接。業(yè)務方覺得“點一下掃描按鈕”就完事實際動手才發(fā)現(xiàn)驅(qū)動型號五花八門、廠商SDK各不相同、有的設備只認TWAIN、有的只認WIA還有的兩種都支持但行為不一致。VC 使用TWAIN協(xié)議實現(xiàn)掃描儀完整源碼這個方向解決的正是“不依賴廠商私有SDK、用一套通用接口把掃描儀接進自己程序”的問題。TWAIN是一套跨廠商的圖像采集接口標準Windows上絕大多數(shù)平板掃描儀、饋紙式掃描儀都支持它。它適合誰適合需要在MFC或Win32桌面程序里內(nèi)嵌掃描功能、又不想為每個品牌單獨適配的開發(fā)者。核心思路是你的程序作為“數(shù)據(jù)源管理器”的客戶端通過一個動態(tài)庫加載目標掃描儀的數(shù)據(jù)源用消息回調(diào)驅(qū)動整個掃描流程。聽起來繞但拆開看就是幾個固定步驟。2. TWAIN的三層結(jié)構(gòu)和消息驅(qū)動模型2.1 數(shù)據(jù)源管理器、數(shù)據(jù)源、應用程序各管什么TWAIN的架構(gòu)是三層應用程序你的VC程序、數(shù)據(jù)源管理器DSM通常是一個叫TWAIN_32.DLL或TWAINDSM.DLL的動態(tài)庫、數(shù)據(jù)源DS每個掃描儀廠商提供的驅(qū)動。應用程序不直接跟掃描儀對話而是先加載DSM由DSM去枚舉和打開具體的DS。這個設計的好處是應用程序只需要認識DSM這一套接口換掃描儀時只要換DS就行。三層之間的通信靠兩種機制一種是調(diào)用DSM導出的函數(shù)比如DSM_Entry另一種是DS向應用程序窗口發(fā)送消息。消息驅(qū)動是TWAIN最容易讓人懵的地方——掃描不是“調(diào)用一個函數(shù)然后等返回”而是“發(fā)一個命令然后等DS往你的窗口發(fā)消息你在消息處理里回應”。整個流程像一場來回傳球而不是一次直線調(diào)用。我一般會把狀態(tài)機畫在紙上再寫代碼。TWAIN定義了7個狀態(tài)從狀態(tài)1DSM未加載到狀態(tài)7數(shù)據(jù)傳輸中。每個操作都要求當前狀態(tài)匹配狀態(tài)不對就返回失敗。很多新手翻車就翻在這里沒打開DS就直接調(diào)能力設置或者傳輸沒結(jié)束就關DS結(jié)果程序卡死或者掃描儀報錯。2.2 從狀態(tài)1到狀態(tài)7一次掃描要經(jīng)過哪些狀態(tài)狀態(tài)1是初始態(tài)DSM還沒加載。調(diào)用DSM_Entry的MSG_OPENDSM后進入狀態(tài)2此時DSM已加載但沒打開任何DS。接著MSG_OPENDS打開指定掃描儀進入狀態(tài)3。狀態(tài)3是“DS已打開但未啟用”這時可以查詢和設置能力比如分辨率、色彩模式、掃描區(qū)域。調(diào)用MSG_ENABLEDS后進入狀態(tài)4DS開始工作。如果DS需要顯示自己的配置界面會進入狀態(tài)5如果直接開始傳輸圖像進入狀態(tài)6。狀態(tài)6是數(shù)據(jù)傳輸中DS會不斷發(fā)消息告訴你有一張圖傳過來了。傳輸完成后回到狀態(tài)5或狀態(tài)4最后MSG_DISABLEDS回到狀態(tài)3MSG_CLOSEDS回到狀態(tài)2MSG_CLOSEDSM回到狀態(tài)1。這套狀態(tài)機是TWAIN的骨架。寫代碼時我會用一個變量記錄當前狀態(tài)每次調(diào)用DSM_Entry前先檢查狀態(tài)是否允許。下面這張表是我常用的狀態(tài)與操作對照放在手邊隨時查。當前狀態(tài)允許的操作典型調(diào)用1加載DSMMSG_OPENDSM2打開DS、查詢DSM能力MSG_OPENDS3設置能力、啟用DSMSG_ENABLEDS、MSG_GET/SET4傳輸圖像、禁用DSMSG_ENABLEDS(帶傳輸)、MSG_DISABLEDS5傳輸圖像、關閉UIMSG_ENABLEDS6接收數(shù)據(jù)、結(jié)束傳輸處理MSG_XFERREADY7結(jié)束傳輸MSG_ENDXFER2.3 消息回調(diào)為什么你的窗口過程要處理TWAIN消息DS向應用程序發(fā)消息時用的是你注冊時提供的窗口句柄。所以你的主窗口或一個隱藏窗口的WindowProc里必須處理幾個TWAIN專用消息。最核心的是MSG_XFERREADY表示DS已經(jīng)準備好一張圖像等你來取。還有MSG_CLOSEDSREQ表示DS請求關閉MSG_DEVICEEVENT表示設備事件比如掃描儀上的按鈕被按下。處理這些消息時不能做耗時操作否則會阻塞DS。我一般只做標記把實際的數(shù)據(jù)獲取放到主循環(huán)或單獨線程里。下面是一個窗口過程里處理TWAIN消息的骨架// 假設已經(jīng)定義了全局的TWAIN會話結(jié)構(gòu) LRESULT CALLBACK WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam) { switch (msg) { case WM_TWAIN_XFERREADY: // 自定義消息由DS發(fā)來 // 只做標記不在這里做耗時傳輸 g_bXferReady TRUE; PostMessage(hWnd, WM_APP 1, 0, 0); // 投遞到主循環(huán)處理 return 0; case WM_TWAIN_CLOSEDSREQ: // DS請求關閉需要走禁用和關閉流程 g_bCloseRequest TRUE; PostMessage(hWnd, WM_APP 2, 0, 0); return 0; case WM_TWAIN_DEVICEEVENT: // 設備事件比如掃描儀按鈕 // 一般記錄事件類型按需處理 return 0; default: return DefWindowProc(hWnd, msg, wParam, lParam); } }這段代碼的關鍵點是窗口過程只做消息分發(fā)不直接調(diào)用DSM_Entry去取圖像。因為取圖像可能觸發(fā)DS再次發(fā)消息如果在窗口過程里遞歸調(diào)用容易造成死鎖或狀態(tài)混亂。用PostMessage投遞到主消息隊列讓主循環(huán)在合適的狀態(tài)下處理是更穩(wěn)的做法。參數(shù)方面WM_TWAIN_XFERREADY這類消息的數(shù)值需要根據(jù)TWAIN頭文件里的定義來不同版本的DSM可能略有差異但核心幾個是固定的。3. 用VC把TWAIN會話跑起來的最小實現(xiàn)3.1 加載DSM和打開數(shù)據(jù)源的完整代碼第一步是加載DSM。TWAIN的DSM通常以動態(tài)庫形式存在32位程序用TWAIN_32.DLL64位程序用TWAINDSM.DLL。加載后拿到DSM_Entry函數(shù)指針后續(xù)所有操作都通過它。下面是我常用的加載和打開DS的代碼// 定義DSM_Entry函數(shù)指針類型 typedef TW_UINT16 (FAR PASCAL *DSMENTRYPROC)(pTW_IDENTITY, pTW_IDENTITY, TW_UINT32, TW_UINT16, TW_UINT16, TW_MEMREF); DSMENTRYPROC g_pDSMEntry nullptr; TW_IDENTITY g_AppIdentity {0}; TW_IDENTITY g_SrcIdentity {0}; TW_UINT16 g_CurrentState 1; // 初始狀態(tài) bool LoadDSM() { // 根據(jù)程序位數(shù)選擇DSM庫名 const char* dsmName TWAINDSM.DLL; // 64位 HMODULE hDSM LoadLibraryA(dsmName); if (!hDSM) { // 嘗試32位庫名 hDSM LoadLibraryA(TWAIN_32.DLL); if (!hDSM) return false; } g_pDSMEntry (DSMENTRYPROC)GetProcAddress(hDSM, DSM_Entry); if (!g_pDSMEntry) return false; // 填充應用程序標識 g_AppIdentity.Id 0; g_AppIdentity.Version.MajorNum 1; g_AppIdentity.Version.MinorNum 0; g_AppIdentity.Version.Language TWLG_CHINESE_SIMPLIFIED; g_AppIdentity.Version.Country TWCY_CHINA; strcpy_s(g_AppIdentity.Version.Info, 1.0.0); strcpy_s(g_AppIdentity.ProductName, MyScanApp); strcpy_s(g_AppIdentity.Manufacturer, MyCompany); strcpy_s(g_AppIdentity.ProductFamily, Document); g_AppIdentity.ProtocolMajor TWON_PROTOCOLMAJOR; g_AppIdentity.ProtocolMinor TWON_PROTOCOLMINOR; g_AppIdentity.SupportedGroups DG_IMAGE | DG_CONTROL; // 打開DSM狀態(tài)1 - 狀態(tài)2 TW_UINT16 rc g_pDSMEntry(g_AppIdentity, nullptr, DG_CONTROL, DAT_PARENT, MSG_OPENDSM, (TW_MEMREF)g_hWnd); if (rc ! TWRC_SUCCESS) return false; g_CurrentState 2; return true; } bool OpenDataSource() { if (g_CurrentState ! 2) return false; // 打開默認數(shù)據(jù)源狀態(tài)2 - 狀態(tài)3 TW_UINT16 rc g_pDSMEntry(g_AppIdentity, nullptr, DG_CONTROL, DAT_IDENTITY, MSG_OPENDS, (TW_MEMREF)g_SrcIdentity); if (rc ! TWRC_SUCCESS) return false; g_CurrentState 3; return true; }邏輯說明LoadDSM先嘗試加載64位DSM庫失敗再試32位。拿到DSM_Entry后填充應用程序標識這個標識告訴DSM是誰在調(diào)用。MSG_OPENDSM需要傳入一個窗口句柄DS后續(xù)的消息會發(fā)到這個窗口。OpenDataSource用MSG_OPENDS打開默認數(shù)據(jù)源如果機器上有多個掃描儀可以先枚舉再選擇。參數(shù)方面g_AppIdentity里的ProtocolMajor和ProtocolMinor要和DSM支持的版本匹配一般用頭文件里的宏。SupportedGroups聲明你支持的能力組DG_IMAGE和DG_CONTROL是必須的。3.2 設置分辨率、色彩模式和掃描區(qū)域打開DS后狀態(tài)3下可以設置能力。TWAIN的能力用“能力容器”管理每個能力有一個ID比如ICAP_XRESOLUTION是水平分辨率ICAP_PIXELTYPE是像素類型。設置能力用MSG_SET查詢用MSG_GET。下面是一個設置分辨率和色彩模式的例子bool SetResolution(TW_UINT16 xRes, TW_UINT16 yRes) { if (g_CurrentState ! 3) return false; // 設置水平分辨率 TW_UINT16 rc g_pDSMEntry(g_AppIdentity, g_SrcIdentity, DG_IMAGE, DAT_IMAGEINFO, MSG_SET, (TW_MEMREF)xRes); // 注意實際設置分辨率用的是ICAP_XRESOLUTION這里簡化示意 // 正確做法是構(gòu)造TW_CAPABILITY結(jié)構(gòu) return rc TWRC_SUCCESS; }上面這段是簡化示意實際設置能力需要構(gòu)造TW_CAPABILITY結(jié)構(gòu)指定能力ID、容器類型和值。我一般封裝一個SetCapability函數(shù)把能力ID和值傳進去內(nèi)部處理容器分配和釋放。色彩模式常用的是TWPT_RGB彩色、TWPT_GRAY灰度、TWPT_BW黑白。掃描區(qū)域用ICAP_FRAMES設置單位是英寸的千分之一。這些參數(shù)設不好掃出來的圖要么太大要么太小要么顏色不對。提示設置能力前先用MSG_GET查詢當前值和支持范圍不要盲目設一個超出范圍的值否則DS可能返回失敗或者用默認值覆蓋。3.3 觸發(fā)掃描并接收圖像數(shù)據(jù)設置完能力后調(diào)用MSG_ENABLEDS進入狀態(tài)4或5。如果傳入的TW_USERINTERFACE結(jié)構(gòu)里ShowUI為TRUEDS會彈出自己的配置界面用戶點“掃描”后開始傳輸。如果ShowUI為FALSEDS直接開始傳輸。傳輸過程中DS會發(fā)MSG_XFERREADY消息你在窗口過程里標記后在主循環(huán)里調(diào)用MSG_GET獲取圖像數(shù)據(jù)。獲取圖像數(shù)據(jù)用DG_IMAGE / DAT_IMAGENATIVEXFER拿到的是一個句柄里面是設備無關位圖DIB格式的數(shù)據(jù)。你可以把它保存成BMP文件或者轉(zhuǎn)成其他格式。下面是一個獲取并保存BMP的簡化流程void OnXferReady() { if (g_CurrentState ! 6 g_CurrentState ! 5) return; HANDLE hBitmap nullptr; TW_UINT16 rc g_pDSMEntry(g_AppIdentity, g_SrcIdentity, DG_IMAGE, DAT_IMAGENATIVEXFER, MSG_GET, (TW_MEMREF)hBitmap); if (rc TWRC_XFERDONE hBitmap) { // hBitmap是DIB數(shù)據(jù)可以保存為BMP SaveDIBToBmp(hBitmap, scan_output.bmp); GlobalFree(hBitmap); } // 結(jié)束傳輸狀態(tài)6 - 狀態(tài)5或4 g_pDSMEntry(g_AppIdentity, g_SrcIdentity, DG_CONTROL, DAT_PENDINGXFERS, MSG_ENDXFER, nullptr); }邏輯說明MSG_GET拿到的是DIB句柄不是HBITMAP需要按DIB格式解析文件頭和信息頭。SaveDIBToBmp是我自己封裝的函數(shù)把DIB數(shù)據(jù)加上BMP文件頭寫盤。傳輸結(jié)束后必須調(diào)MSG_ENDXFER否則DS會一直停在傳輸狀態(tài)。如果有多頁MSG_ENDXFER后DS可能再次發(fā)MSG_XFERREADY循環(huán)處理即可。4. 多頁掃描、內(nèi)存管理和UI線程的避坑記錄4.1 現(xiàn)象掃第二頁時程序卡死原因第一頁傳輸結(jié)束后沒有正確調(diào)用MSG_ENDXFER或者調(diào)用后沒有檢查返回值。DS在等待應用程序確認傳輸結(jié)束應用程序卻在等DS發(fā)下一張的消息雙方互相等死鎖。解決每次MSG_GET成功后無論是否還有下一頁都要調(diào)MSG_ENDXFER。如果返回值是TWRC_SUCCESS且后續(xù)還有頁DS會再發(fā)MSG_XFERREADY如果返回值里帶TWRC_XFERDONE說明沒有更多頁了。4.2 現(xiàn)象掃描大圖時內(nèi)存暴漲原因每次MSG_GET返回的DIB句柄需要應用程序自己釋放。如果只保存不釋放或者保存后忘記GlobalFree內(nèi)存會持續(xù)增長。另外如果開了多頁掃描每頁都保留在內(nèi)存里也會爆。解決每頁處理完立即釋放句柄需要多頁合并的話只保留必要的數(shù)據(jù)或者直接寫盤。我一般掃一頁存一頁不在內(nèi)存里堆。4.3 現(xiàn)象DS的配置界面彈不出來原因調(diào)用MSG_ENABLEDS時傳入的窗口句柄不對或者ShowUI設了FALSE。另外如果DSM加載的是32位版本而程序是64位或者反過來也會導致界面無法顯示。解決確認程序位數(shù)和DSM庫位數(shù)一致。ShowUI根據(jù)需求設置需要用戶選參數(shù)就設TRUE。窗口句柄用主窗口的不要用臨時窗口。4.4 現(xiàn)象設置分辨率后掃描儀沒反應原因能力設置失敗但沒檢查返回值。有些掃描儀不支持某些分辨率或者支持的范圍和你想的不一樣。解決設置前先MSG_GET查詢支持的范圍在范圍內(nèi)取值。設置后檢查返回值失敗就回退到默認值。不要假設所有掃描儀都支持300dpi或600dpi。4.5 現(xiàn)象程序退出時掃描儀燈不滅原因沒有按順序關閉DS和DSM。正確的關閉順序是MSG_DISABLEDS狀態(tài)4/5到3、MSG_CLOSEDS狀態(tài)3到2、MSG_CLOSEDSM狀態(tài)2到1。漏掉任何一步DS可能保持打開狀態(tài)。解決在程序退出或掃描完成時按狀態(tài)機順序逐步關閉每步檢查返回值。5. 把TWAIN封裝成可復用類的幾個技巧5.1 用狀態(tài)機類管理會話生命周期把狀態(tài)變量、DSM句柄、DS標識封裝到一個類里所有操作作為成員函數(shù)每次調(diào)用前檢查狀態(tài)。這樣調(diào)用方不需要關心狀態(tài)轉(zhuǎn)換細節(jié)只調(diào)Open、SetCap、Scan、Close幾個方法。我一般會寫一個CTwainSession類構(gòu)造函數(shù)里加載DSM析構(gòu)函數(shù)里確保關閉。狀態(tài)轉(zhuǎn)換用私有方法失敗時記錄錯誤碼。5.2 異步掃描與進度反饋TWAIN的消息機制天然適合異步。把掃描放在工作線程里主線程處理UI。工作線程調(diào)用MSG_ENABLEDS后進入消息循環(huán)收到MSG_XFERREADY就取數(shù)據(jù)取完發(fā)通知給主線程更新進度。注意DSM_Entry不是線程安全的所有TWAIN調(diào)用要在同一個線程里。我一般把TWAIN會話固定在一個線程其他線程通過消息和它通信。5.3 兼容不同DSM版本的注意事項不同版本的DSM對某些能力的支持不一樣。比如老版本可能不支持ICAP_AUTODISCARDBLANKPAGES新版本支持。調(diào)用前先MSG_GET查詢返回TWRC_FAILURE就跳過。另外32位和64位DSM的庫名不同加載時要根據(jù)編譯目標選擇。如果程序需要同時支持兩種可以用條件編譯或者運行時判斷。5.4 一個可復用的能力設置封裝下面這個函數(shù)封裝了能力設置傳入能力ID和值內(nèi)部處理容器分配和釋放bool SetCapability(TW_UINT16 capId, TW_UINT16 type, void* pValue, TW_UINT32 size) { if (g_CurrentState ! 3) return false; TW_CAPABILITY cap {0}; cap.Cap capId; cap.ConType TWON_ONEVALUE; cap.hContainer GlobalAlloc(GHND, sizeof(TW_ONEVALUE) size); if (!cap.hContainer) return false; pTW_ONEVALUE pVal (pTW_ONEVALUE)GlobalLock(cap.hContainer); pVal-ItemType type; memcpy(pVal-Item, pValue, size); GlobalUnlock(cap.hContainer); TW_UINT16 rc g_pDSMEntry(g_AppIdentity, g_SrcIdentity, DG_CONTROL, DAT_CAPABILITY, MSG_SET, (TW_MEMREF)cap); GlobalFree(cap.hContainer); return rc TWRC_SUCCESS; }邏輯說明TW_CAPABILITY結(jié)構(gòu)里ConType指定容器類型TWON_ONEVALUE表示單值。hContainer是全局內(nèi)存句柄里面放TW_ONEVALUE結(jié)構(gòu)加實際值。設置完必須釋放容器否則內(nèi)存泄漏。參數(shù)capId是能力IDtype是值類型如TWTY_UINT16pValue指向?qū)嶋H值size是值的大小。這個封裝把容器管理藏起來調(diào)用方只需要關心能力ID和值。5.5 驗證掃描結(jié)果是否正確的幾個檢查點掃出來的圖不對先查這幾個地方分辨率設置是否生效看圖像像素尺寸和預期是否一致、色彩模式是否正確彩色圖是不是灰度了、掃描區(qū)域是否覆蓋了文檔有沒有截斷。我一般會在保存圖像后打印圖像寬高和位深和預期對比。如果DS支持還可以用ICAP_PIXELTYPE查詢當前像素類型確認設置生效。這套TWAIN方案我用了幾年最大的教訓是不要假設掃描儀會按你想的行為工作。每臺設備的能力支持范圍、默認值、對異常狀態(tài)的反應都不一樣。寫代碼時多查返回值多打日志遇到問題先看狀態(tài)機走到哪一步了。希望幫到你。本文還有配套的精品資源點擊獲取