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