列代码段说明。容器可灵活地定义用于包含许多种数据之一。请参考工具包以了解容器可用的所有封装和拆包功能。
4.1.6 延迟协商-在状态4之后进行性能协商
应用程序可能在会话期间的任何时刻向源询问性能数据。但是，一个原则是应用程序只能在状态4下请求设置性能。此限制背后的基本原因与源启用时源用户界面的显示有关。许多源需要更改其用户界面的内容以响应应用程序的设置请求。这些更改可预防用户选择与应用程序要求不一致的选项。源用户界面不会在状态4下显示因而可以在用户不查觉的情况下改变。而用户界面在状态5至7时则会显示。
一些性能对用户界面没有影响并且应用程序可能希望在状态4之后进行设置。为了允许延迟协商，应用程序必须在状态4下请求特定的性能能够在稍后进行设置（状态5至6），源可以同意或拒绝此请求。此请求通过在CAP_EXTENDEDCAPS上使用DG_CONTROL/DAT_CAPABILITY操作来协商。
在CAP_EXTENDEDCAPS性能上的DG_CONTROL / DAT_CAPABILITY操作： MSG_GET
指示源希望在状态5至6下进行协商的所有性能。 MSG_SET
指定应用程序希望在状态5至6下协商哪些性能。 MSG_GETCURRENT
指示源和应用程序均同意在状态5至6下协商的所有性能。
与其它性能一样，若源不支持CAP_EXTENDEDCAPS，它将返回返回码TWRC_FAILURE和状态码TWCC_CAPUNSUPPORTED。
若应用程序尝试在状态5或6下设置性能但源没有事先同意此安排，此操作将失败，其返回码为TWRC_FAILURE，状态码为TWCC_SEQERROR。
若应用程序不使用源用户界面，则应用程序将控制源的状态。若应用程序想设置性能的值，它可以使源返回状态4再进行此操作。因此使用自己的用户界面的应用程序无需使用CAP_EXTENDEDCAPS。
4.2 数据传送选项
之前已经讨论过，TWAIN为数据传送定义了三种模式：本地、文件和缓存模式。 源被要求支持本地和缓存传送模式。
4.2.1 本地传输模式
此模式的使用在第3章中已介绍。本地模式的一个潜在的局限是可能没有足够大的RAM块可用于保存图像。这种情况直到应用程序发送DG_IMAGE / DAT_IMAGENATIVEXFER / MSG_GET操作尝试进行传输时才会被发现。 当出现内存不足的情况下，源可能的响应方式有多种： ? 简单地使操作失败。
? 裁剪图像使其能够置入可用的内存。源应通知用户由于内存限制而进行了此操作。裁剪应保持图像和外观比例和起点（左上角）。
? 和用户进行沟通以允许变更图像尺寸或取消操作。
DG_IMAGE / DAT_IMAGENATIVEXFER / MSG_GET返回的返回码/状态码可指示发生了哪种动作：
TWRC_XFERDONE：
表示传输已完成并且会话状态为7。但这不能保证源没有裁剪图像。即使应用程序在传输前使用DG_IMAGE/DAT_IMAGEINFO/MSG_GET来确定图像尺寸，也不能认为返回的
ImageWidth和ImageHeight适用于最终传输过来的图像。如果图像尺寸对应用程序很重要，则应在传输完成后却检查最终的图像尺寸，如下：
? 调用DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER操作使会话状态从7变更为6（或5）。
? 判断传输的真实的图像的尺寸： Windows —— 读取DIB头信息；Macintosh—— 检查图像的PicFrame。 TWRC_CANCEL：
获取操作被用户取消，会话状态为7。执行DG_CONTROL / DAT_PENDINGXFERS / MSG_ENDXFER操作以使会话状态从7变更为6（或5）。 TWRC_FAILURE：
检查状态码以确定失败的原因。会话状态为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——在无效状态下操作。
相关推荐：
loading