检查状态码以确定失败的原因。会话状态为6。没有为DIB或PICT分配任何内存。图像依然处于挂起状态。如果是由内存不足引起,可以选择释放额外的内存或执行DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER以丢弃挂起的图像。
4.2.2 磁盘文件传输模式
从版本1.9开始,有两种可用的文件传输机制。Windows开发者可继续使用TWSX_FILE选项,Macintosh开发者则必须使用TWSX_FILE2,以在新版本的操作系统上正确地定位图像和音频文件。
判断源是否支持磁盘文件传输模式:
? 使用DG_CONTROL / DAT_CAPABILITY / MSG_GET操作。 ? 将TW_CAPABILITY.Cap域设置为ICAP_XFERMECH。
? 源通过TW_CAPABILITY.hContainer返回它所支持的传输模式信息。磁盘文件模式用TWSX_FILE或TWSX_FILE2标识。源没有被强制要求支持磁盘文件传输模式,因此验证十分必要。
4.2.2.1 确定支持文件传输模式后,启动传输
在状态4下:
? 使用DG_CONTROL / DAT_CAPABILITY / MSG_SET操作,ICAP_XFERMECH设置为TWSX_FILE 或 TWSX_FILE2。
? 将 TW_CAPABILITY. Cap设置为ICAP_IMAGEFILEFORMAT,使用 DG_CONTROL / DAT_CAPABILITY / MSG_GET 确定源支持何种文件格式。源返回所支持的格式的标识符,这些标识符以 TWFF_ 为前缀,包括 TWFF_PICT, TWFF_BMP, TWFF_TIFF等。 在状态4、5、6下:
可使用DG_CONTROL/ DAT_SETUPFILEXFER 的 SG_GET, MSG_GETDEFAULT 和 MSG_SET 操作。此操作相关的数据结构是TW_SETUPFILEXFER 。
应用程序可使用MSG_GETDEFAULT操作来确定默认文件格式和文件名(TWAIN.TMP或TWAIN.AUD)。若要设置文件名和格式:
1. 分配一个TW_SETUPFILEXFER结构,填充适当的域: a. FileName - 在Windows中请确保包含完整的路径。
b. Format - 以TWFF_开始的常量,如果设置为不支持的格式,则操作将返回TWRC_FAILURE / TWCC_BADVALUE,并且源将重围为输出数据到默认文件。 c. VrefNum - 在Macintosh中,设置为文件的卷标;在Windows中设置为TWON_DONTCARE16。
2. 调用DG_CONTROL / DAT_SETUPFILEXFER / MSG_SET。 4.2.2.2 传输到文件
在应用程序收到MSG_XFERREADY通知并发送DG_CONTROL / DAT_SETUPFILEXFER / MSG_GET后:使用DG_IMAGE / DAT_IMAGEFILEXFER / MSG_GET ,此操作没有与之关联的数据结构,在DSM_Entry调用中pData为NULL。
? 如果应用程序未指定文件名(在Set Up中),源将使用默认文件名或最后一次指定的文件信息。
? 如果应用程序指定的文件不存在,源将创建该文件。
? 如果文件存在但已包含数据,源将覆盖已有数据。所以若对多个文件传输使用相同的文件名,则必须在两次传输之间将文件数据复制到其它地方。
注:一旦开始,应用程序就无法取消文件传输操作。但是,源可能通过其用户界面向用户提供取消传输的功能。
在此操作后,确保检查返回码:
TWRC_XFERDONE:文件成功写入。应用程序应调用DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER使会话返回状态6(或5)。 TWRC_CANCEL:用户取消传输。文件内容未定义,调用DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER使会话返回状态6(或5)。
TWRC_FAILURE:源处于状态6;文件内容未定义;图像依然处于挂起状态。若要放弃图像,可使用DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER。 检查状态以确定失败的原因:
TWCC_BADDEST——指定了无效源。
TWCC_OPERATIONERROR——文件存在但无法存取或在写入时发生系统错误。 TWCC_SEQERROR——在无效状态下操作。
4.2.3 缓存传输模式
数据通常以非压缩格式传输,如果想知道源在缓存传输模式下是否能传输压缩数据,请对ICAP_COMPRESSION使用DG_CONTROL / DAT_CAPABILITY / MSG_GET操作,结果可能为TWCP_NONE ,也可能为TWCP_PACKBITS 、TWCP_JPEG等。 4.2.3.1 启动传输
在状态4下:
使用DG_CONTROL / DAT_CAPABILITY / MSG_SET,ICAP_XFERMECH 设置为TWSX_MEMORY。 在状态4、5、6下:
应用程序使用DG_CONTROL / DAT_SETUPMEMXFER / MSG_GET来确定源想要多大的缓存来传输。在状态6下源可能有更精确的信息。此操作相关数据结构为TW_SETUPMEMXFER,源将根据设备填充合适的值。 对用于非压缩传输的缓存:
? 应用程序负责分配和释放缓存传输所用的所有内存。 ? 作为一个可选行为,创建一个所选尺寸大小的缓存。
? 在所有情况下,分配的内存应遵循MinBufSize和MaxBufSize的限制。否则源将操作失败(返回TWRC_FAILURE/TWCC_BADVALUE)。 ? 使用多个缓冲区时,各个缓冲区大小必须相同。 ? 建议光栅线应对齐到双字并以0填充。 4.2.3.2 执行缓存传输:
应用程序收到MSG_XFERREADY通知并发出DG_CONTROL / DAT_SETUPMEMXFER / MSG_GET后:
? 分配一个或多个相同尺寸的缓冲区,最好是TW_SETUPMEMXFER.Freferred域所声明的尺寸。如果不能,则确保缓冲区尺寸在MinBufSize和MaxBufSize之间。
? 分配一个 TW_IMAGEMEMXFER,第一个域设置为TWON_DONTCARE16,接下来六个域设置为 TWON_DONTCARE32。最后一个TW_MEMORY结构的Memory域如下填充:
Memory.Flags - 描述Memory.TheMem的类型,值为TWMF_POINTER 或 TWMF_HANDLE。
Memory.Length - 缓冲区尺寸,以字符为单位
Memory.TheMem - 指向上述分配的缓冲区的句柄或指针(是句柄还是指针由Flags域指定)。 每传输完一个缓冲区后,源将填充除Memory外的所有域。 缓存传输的流程如下: 步骤一:
缓存传输不提供嵌入的头信息,因此,应用程序必须确定图像属性。例如在状态6下收到MSG_XFERREADY后,发送DG_IMAGE / DAT_IMAGEINFO / MSG_GET 和DG_IMAGE / DAT_IMAGELAYOUT / MSG_GET来了解图像的位图特征、尺寸以及在当前页面上的位置。若需要其它额外的信息,请使用 DG_CONTROL / DAT_CAPABILITY / MSG_GET操作。 步骤二:
发送DG_IMAGE / DAT_IMAGEMEMXFER / MSG_GET。 步骤三: 检查返回码
? TWRC_SUCCESS - 检查TW_IMAGEMEMXFER结构中关于缓冲区的信息。如果想重用缓冲区,将数据拷贝到其它地方去。
若有必要,回到步骤二,重新获取一个缓冲区,重新初始化TW_IMAGEMEMXFER结构,再发送另一个DG_IMAGE / DAT_IMAGEMEMXFER / MSG_GET。 ? TWRC_XFERDONE - 这表示源已经成功地传输完了最后一个缓冲区。 ? TWRC_CANCEL - 用户取消了传输,应用程序必须发送 DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER以从状态7回到状态6(或5)。
? TWRC_FAILURE - 检查状态码以确定原因。如果失败在首个缓冲区的传输过程中,则会话仍处于状态6;若发生在随后的缓冲区传输过程中,则会话处于状态7。此时缓冲区内容无效且缓冲区传输仍处于挂起状态,若要取消,请使用DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER。 步骤四:
一旦返回了TWRC_XFERDONE,应用程序就必须发送 DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER来结束传输。
注:在使用缓存传输时,大多数源将图像数据分割成条。每个条是一个水平带,从图像左端开始横跨整个图像宽度,但只覆盖部分图像长度(高度)。如果在源返回的TW_IMAGEMEMXFER中,XOffset域为零,Columns域等于TW_IMAGEINFO.ImageWidth域,则可以断定源采用了这种分割方式。
还有一种只有少数源使用的片方式。请参见第八章有关TW_IMAGEMEMXFER的信息。
4.2.4 文件格式的缓存传输模式
此方式与缓冲传输模式非常类似,只是传输的数据遵循之前通过DG_IMAGE /
DAT_SETUPFILEXFER / MSG_GET指定的图像文件格式。此方式不要求数据作为完整的图像线传输和任何填充,数据被认为是自包含和自描述的。
4.3 图像数据及其布局
从源传送到应用程序的图像有数个属性。其中一些描述图像尺寸,一些描述图像在原始页面中的位置,还有一些描述分辨率或像素位数等信息。TWAIN为应用程序提供了了解这些属性的途径。 用户通常可通过源用户界面选择和更改图像的属性。额外地,TWAIN也提供了支持在采集和传输前影响这些属性的的性能和操作。
4.3.1 获取将要传输的图像的信息
在传输开始前(状态6),源可向应用程序提供将要传输的真实图像的信息。注意一旦传输开始这样信息将丢失,因此应用程序应在必要时将其保存。这些信息可通过以下操作查询: DG_IMAGE / DAT_IMAGELAYOUT / MSG_GET DG_IMAGE / DAT_IMAGEINFO / MSG_GET
采集的图像区域始终是一个称为“框架”(Frame)的矩形。在一个页面上可能分配有多个框架。框架可由用户选择或应用程序指定。TW_IMAGELAYOUT结构指示图像在当前页面上相对于页面起点的位置,同时其FrameNumber域指示这是从页面上采集到的第几个框架。
TW_FRAME结构描述框架的Top、Bottom、Left和Right值。其单位由ICAP_UNITS指定。