Twain Practice

Official Website:http://www.twain.org

一、简介

    TWAIN 数据源管理程序 (DSM) 工业标准的软件库，用于从静态图像设备提取图像。绝大部分的扫描仪和数码相机都提供了 TWAIN 驱动程序，利用统一的 TWAIN 接口，应用程序可以非常方便地从这些设备中获取图像。

二、使用步骤

    互联网上关于 TWAIN 编程的中文资料很少，代码更是难找到，因为我不得不仔细阅读了 www.twain.org 提供的 TWAIN Specification。下面说说使用 TWAIN 接口获取图像的简要步骤。

    Windows 系统中存在一个 TWAIN_32.dll，所有的 TWAIN 操作都是通过这个 DLL 导出的 DSM_Entry 函数来实现的 (说实在话，我个人觉得 TWAIN 接口设计得太差了，看看 MS 的WIA，逻辑上非常清晰)。这个函数的声明如下:

        TW_UINT16 FAR PASCAL DSM_Entry(
            pTW_IDENTITY pOrigin,   // Source of message
            pTW_IDENTITY pDest,     // Destination of message
            TW_UINT32 DG,           // Data group ID: DG_xxxx
            TW_UINT16 DAT,          // Data argument type: DAT_xxxx
            TW_UINT16 MSG,          // Message ID: MSG_xxxx
            TW_MEMREF pData         // Pointer to data
            );

1. 打开 DSM (Data Source Manager: 数据源管理器)

    TWAIN 是一个数据源管理程序，应用程序首先要使用 MSG_OPENDSM 消息，打开数据源管理器。这里需要指定一个窗口句柄，应用程序应该在此窗口的消息循环中处理 TWAIN 消息 (MSG_PROCESSEVENT)。

2. 选择 DS (Data Source: 数据源)

    因为一个系统中可能存在多个 TWAIN 设备，因此必须选择一个数据源。选择数据源通常有两种方式:  选择默认数据源 (MSG_GETDEFAULT) 和显示选择数据源对话框，由用户来选择数据源 (MSG_USERSELECT)。

3. 打开 DS

    使用 MSG_OPENDS 消息打开数据源。

4. 设置参数

    消息为 MSG_SET，设置各种参数，如获取方式、图像数量等。有些参数由设备驱动支持才有效。

5. 显示扫描界面

    使用 MSG_ENABLEDS 消息，显示设备驱动提供的用户界面 (UI)。

6. 获取图像

    如果用户选择扫描什么的，可以在窗口的消息循环中获取到这个事件 (MSG_XFERREADY)。此时，应用程序可以通过 DAT_SETUPFILEXFER 设置文件名，然后用 DAT_IMAGEFILEXFER 获取图像到文件中。

7. 关闭扫描界面

    在窗口的消息循环中获取到 MSG_CLOSEDSREQ 或 MSG_CLOSEDSOK 消息，可以关闭扫描界面 (MSG_DISABLEDS)。

8. 关闭 DS

    消息为 MSG_CLOSEDS。

9. 关闭数据源
   
    消息为 MSG_CLOSEDSM。

三、CTwainHelper 助手类

    为了使用方便，我写了一个静态 TWAIN 助手类 CTwainHelper。使用 CTwainHelper 的五个函数，就可以简单地从 TWAIN 设备获取图像到文件中。使用方法如下:

1. 调用 CTwainHelper::Initialize() 确定是否有可用的设备。
2. 在窗口消息循环中，调用 CTwainHelper::ProcessMessage() 处理 TWAIN 消息。
3. 要获取图像时，调用 CTwainHelper::GetImage()。
4. 如果图像已准备好 (如用户确定扫描图像)，窗口会收到 WM_COMMAND 消息，wParam 为 IDC_TwainHelper。此时应用程序可以调用 CTwainHelper::TransferImage() 获取图像到文件中。

    具体使用方法请参看示例代码。
   
    CTwainHelper 可以在 Visual C++ 6.x/7.x 工程中使用，支持 UNICODE 编译。因为是静态类，要改写成 C 代码只需要做一点点少量的工作。
   

四、后话

    当然，上面只是一种常用的步骤。其实应用程序完全可以自定义所有的步骤，比如不使用 TWAIN 驱动提供扫描对话框而直接扫描，或者扫描图像到内存中等等。详细情况请参考 TWAIN Specification，步骤大同小异，消息和参数千差万别，仔细看看应该很容易的。

    如果没有 TWAIN 设备又要进行 TWAIN 程序开发，可以到 TWAIN 官方网站下载 TWAIN Developers Toolkit，安装后会有一个虚拟的 TWAIN 设备。不过应用程序在这个虚拟 TWAIN 设备中正常工作，不代表一定能在实际的 TWAIN 设备正常使用，这点需要注意。以前 CTwainHelper 就碰到过这样的情况  在虚拟 TWAIN 设备中明明是好的，在我的扫描仪上却不能扫描图像。检查后发现，原来设置了不支持的参数。
   
    最后，TWAIN 是 Technology Without A Interesting Name 缩写，直译为没有“没有让人感兴趣名字的技术”，真是一个让人摸不着头脑的名字。

    TWAIN 助手类: CTwainHelper (包含示例代码 35K)
    TWAIN 官方网站: http://www.twain.org
    TWAIN 头文件: http://www.twain.org/devfiles/twain.h
    TWAIN Specification: http://www.twain.org/docs/Spec1_9_197.pdf
    TWAIN Developers Toolkit: http://www.twain.org/devfiles/twainkit.exe

Load the Source Manager and Get the DSM_Entry (State 1 to 2)
Open the Source Manager (State 2 to 3)
Select the Source (during State 3)
Open the Source (State 3 to 4)
Negotiate Capabilities with the Source (during State 4)
Request the Acquisition of Data from the Source (State 4 to 5)
Recognize that the Data Transfer is Ready (State 5 to 6)
Start and Perform the Transfer (State 6 to 7)
Conclude the Transfer (State 7 to 6 to 5)
Disconnect the TWAIN Session (State 5 to 1 in sequence)

VC++ Call Twain

Header

[cpp]  view plain copy

1. #ifndef __TWAINCPP_  
2. #define __TWAINCPP_  
3.   
4. #include "Twain.h"  
5.   
6.   
7. #define TWCPP_ANYCOUNT        (-1)  
8. #define TWCPP_CANCELTHIS    (1)  
9. #define TWCPP_CANCELALL        (2)  
10. #define TWCPP_DOTRANSFER    (0)  
11.   
12. class CTwain  
13. {  
14. public:  
15.     void Deskew(LPSTR lpFilename);  
16.   
17.   
18.     CTwain(HWND hWnd = NULL);  
19.     virtual ~CTwain();  
20.     BOOL InitTwain(HWND hWnd);  
21.     void ReleaseTwain();  
22.   
23.   
24.     /*   
25.       This routine must be implemented by the dervied class  
26.       After setting the required values in the m_AppId structure, 
27.       the derived class should call the parent class implementation 
28.       Refer Pg: 51 of the Twain Specification version 1.8 
29.     */  
30.     virtual void GetIdentity();  
31.     virtual BOOL SelectSource();  
32.     virtual BOOL OpenSource(TW_IDENTITY *pSource=NULL);  
33.     virtual int  ShouldTransfer(TW_IMAGEINFO& info) { return TWCPP_DOTRANSFER;};  
34.   
35.     void SetPara(int nFileFormat,LPCTSTR lpFileName,int nAD,int nPage,int nStep,BOOL bDeskdw);  
36.     void GetPara(UINT &nPage);  
37.   
38.     BOOL ProcessMessage(MSG msg);  
39.   
40.     BOOL SelectDefaultSource();  
41.     BOOL IsValidDriver() const;  
42.     BOOL SourceSelected() const {return m_bSourceSelected;} ;  
43.     BOOL DSMOpen() const;  
44.     BOOL DSOpen() const;  
45.     BOOL SourceEnabled() const { return m_bSourceEnabled;};  
46.     BOOL ModalUI() const { return m_bModalUI; };  
47.   
48.     TW_INT16 GetRC() const { return m_returnCode; };  
49.     TW_STATUS GetStatus() const { return m_Status; };  
50.   
51.     BOOL SetImageCount(TW_INT16 nCount = 1);  
52.     BOOL Acquire(int numImages=1);  
53.     void DoFileTransfer();  
54.     void CloseDSM();  
55. protected:  
56.     BOOL CallTwainProc(pTW_IDENTITY pOrigin,pTW_IDENTITY pDest,  
57.                        TW_UINT32 DG,TW_UINT16 DAT,TW_UINT16 MSG,  
58.                        TW_MEMREF pData);  
59.   
60.     void CloseDS();  
61.   
62.     BOOL GetCapability(TW_CAPABILITY& twCap,TW_UINT16 cap,TW_UINT16 conType=TWON_DONTCARE16);  
63.     BOOL GetCapability(TW_UINT16 cap,TW_UINT32& value);  
64.     BOOL SetCapability(TW_UINT16 cap,TW_UINT16 value,BOOL sign=FALSE);  
65.     BOOL SetCapability(TW_CAPABILITY& twCap);  
66.     BOOL EnableSource(BOOL showUI = TRUE);  
67.   
68.     BOOL GetImageInfo(TW_IMAGEINFO& info);  
69.   
70.     virtual BOOL DisableSource();  
71.     virtual BOOL CanClose()  { return TRUE; };  
72.   
73.     void TranslateMessage(TW_EVENT& twEvent);  
74.     void TransferImage();  
75.     BOOL EndTransfer();  
76.     void CancelTransfer();  
77.     BOOL ShouldContinue();  
78.     BOOL GetImage(TW_IMAGEINFO& info);  
79.   
80. //    virtual void CopyImage(HANDLE hBitmap,TW_IMAGEINFO& info)=0;  
81.   
82. protected:  
83.     HINSTANCE m_hTwainDLL;  
84.     DSMENTRYPROC m_pDSMProc;  
85.   
86.     TW_IDENTITY m_AppId;  
87.     TW_IDENTITY m_Source;  
88.     TW_STATUS m_Status;  
89.     TW_INT16  m_returnCode;  
90.     HWND m_hMessageWnd;  
91.   
92.     BOOL m_bSourceSelected;  
93.     BOOL m_bDSMOpen;  
94.     BOOL m_bDSOpen;  
95.     BOOL m_bSourceEnabled;  
96.     BOOL m_bModalUI;  

Cpp

[cpp]  view plain copy

1. #include "stdafx.h"  
2. #include "twaincpp.h"  
3. #include "showpic.h"  
4. #include "tiff2pdfdll.h"  
5.   
6. CTwain::CTwain(HWND hWnd)  
7. {  
8.     m_hTwainDLL = NULL;  
9.     m_pDSMProc = NULL;  
10.     m_bSourceSelected = FALSE;  
11.     m_bDSOpen = m_bDSMOpen = FALSE;  
12.     m_bSourceEnabled = FALSE;  
13.     m_bModalUI = TRUE;  
14.     m_nImageCount = TWCPP_ANYCOUNT;  
15.     if(hWnd)  
16.     {  
17.         InitTwain(hWnd);  
18.     }  
19. }  
20.   
21. CTwain::~CTwain()  
22. {  
23.     ReleaseTwain();  
24. }  
25.   
26. /* 
27. 初始化TWAIN 接口. 构造函数中已经调用，不过如果调用了ReleaseTwain的话就需要再次调用. 
28. hWnd是接受Twain消息的窗口句柄，通常应该是主应用程序的窗口句柄 
29. */  
30. BOOL CTwain::InitTwain(HWND hWnd)  
31. {  
32. char libName[512];  
33.     if(IsValidDriver())   
34.     {  
35.         return TRUE;  
36.     }  
37.     memset(&m_AppId,0,sizeof(m_AppId));  
38.     if(!IsWindow(hWnd))  
39.     {  
40.         return FALSE;  
41.     }  
42.     m_hMessageWnd = hWnd;  
43.     strcpy(libName,"TWAIN_32.DLL");  
44.       
45.     m_hTwainDLL  = LoadLibrary(libName);  
46.     if(m_hTwainDLL != NULL)  
47.     {  
48.         if(!(m_pDSMProc = (DSMENTRYPROC)GetProcAddress(m_hTwainDLL,MAKEINTRESOURCE(1))))  
49.         {  
50.             FreeLibrary(m_hTwainDLL);  
51.             m_hTwainDLL = NULL;  
52.         }  
53.     }  
54.     if(IsValidDriver())  
55.     {  
56.         GetIdentity();  
57.         m_bDSMOpen= CallTwainProc(&m_AppId,NULL,DG_CONTROL,DAT_PARENT,MSG_OPENDSM,(TW_MEMREF)&m_hMessageWnd);  
58.         return TRUE;  
59.     }  
60.     else  
61.     {  
62.         return FALSE;  
63.     }  
64. }  
65.   
66. /* 
67. 释放Twain接口，除非不再使用Twain接口，否则就无需调用 
68. */  
69. void CTwain::ReleaseTwain()  
70. {  
71.     if(IsValidDriver())  
72.     {  
73.         CloseDSM();  
74.         FreeLibrary(m_hTwainDLL);  
75.         m_hTwainDLL = NULL;  
76.         m_pDSMProc = NULL;  
77.     }  
78. }  
79.   
80. /* 
81. 如果正确的装载了驱动程序，就返回TRUE 
82. */  
83. BOOL CTwain::IsValidDriver() const  
84. {  
85.     return (m_hTwainDLL && m_pDSMProc);  
86. }  
87.   
88. BOOL CTwain::CallTwainProc(pTW_IDENTITY pOrigin,pTW_IDENTITY pDest,  
89.                        TW_UINT32 DG,TW_UINT16 DAT,TW_UINT16 MSG,  
90.                        TW_MEMREF pData)  
91. {  
92.     if(IsValidDriver())  
93.     {  
94.     USHORT ret_val;  
95.         ret_val = (*m_pDSMProc)(pOrigin,pDest,DG,DAT,MSG,pData);  
96.         m_returnCode = ret_val;  
97.         if(ret_val != TWRC_SUCCESS)  
98.         {  
99.             (*m_pDSMProc)(pOrigin,pDest,DG_CONTROL,DAT_STATUS,MSG_GET,&m_Status);  
100.         }  
101.         return (ret_val == TWRC_SUCCESS);  
102.     }  
103.     else  
104.     {  
105.         m_returnCode = TWRC_FAILURE;  
106.         return FALSE;  
107.     }  
108. }  
109.   
110. /* 
111. 设置Twain的一些入口参数 
112. */  
113. void CTwain::GetIdentity()  
114. {  
115.     // Expects all the fields in m_AppId to be set except for the id field.  
116.     m_AppId.Id = 0; // Initialize to 0 (Source Manager  
117.     m_AppId.Version.MajorNum = 1; //Your app's version number  
118.     m_AppId.Version.MinorNum = 5;  
119.     m_AppId.Version.Language = TWLG_USA;  
120.     m_AppId.Version.Country = TWCY_USA;  
121.     strcpy (m_AppId.Version.Info, "3.5");  
122.     m_AppId.ProtocolMajor = TWON_PROTOCOLMAJOR;  
123.     m_AppId.ProtocolMinor = TWON_PROTOCOLMINOR;  
124.     m_AppId.SupportedGroups = DG_IMAGE | DG_CONTROL;  
125.     strcpy (m_AppId.Manufacturer, "MICSS");  
126.     strcpy (m_AppId.ProductFamily, "Generic");  
127.     strcpy (m_AppId.ProductName, "Twain Test");  
128.   
129. }  
130.   
131.   
132. /* 
133. 调用此函数显示选择扫描设备窗口 
134. */  
135. BOOL CTwain::SelectSource()  
136. {  
137.     memset(&m_Source,0,sizeof(m_Source));  
138.     if(!SourceSelected())  
139.     {  
140.         SelectDefaultSource();  
141.     }  
142.     if(CallTwainProc(&m_AppId,NULL,DG_CONTROL,DAT_IDENTITY,MSG_USERSELECT,&m_Source))  
143.     {  
144.         m_bSourceSelected = TRUE;  
145.     }  
146.     return m_bSourceSelected;  
147. }  
148.   
149. /* 
150. 用于选择缺省扫描设备 
151. */  
152. BOOL CTwain::SelectDefaultSource()  
153. {  
154.     m_bSourceSelected = CallTwainProc(&m_AppId,NULL,DG_CONTROL,DAT_IDENTITY,MSG_GETDEFAULT,&m_Source);  
155.     return m_bSourceSelected;  
156. }  
157.   
158. /* 
159. 关闭数据源（即扫描仪） 
160. */  
161. void CTwain::CloseDS()  
162. {  
163.     if(DSOpen())  
164.     {  
165.         DisableSource();  
166.         CallTwainProc(&m_AppId,NULL,DG_CONTROL,DAT_IDENTITY,MSG_CLOSEDS,(TW_MEMREF)&m_Source);  
167.         m_bDSOpen = FALSE;  
168.     }  
169. }  
170.   
171. /* 
172. 关闭数据源管理器 
173. */  
174. void CTwain::CloseDSM()  
175. {  
176.     if(DSMOpen())  
177.     {  
178.         CloseDS();  
179.         CallTwainProc(&m_AppId,NULL,DG_CONTROL,DAT_PARENT,MSG_CLOSEDSM,(TW_MEMREF)&m