TWAIN Specification
Version 2.3
This document was ratified
by the TWAIN Working Group
on November 21, 2013
Acknowledgments
The TWAIN Working Group acknowledges the following individuals and their respective
companies for their contributions to this document. Their hard work in defining, designing,
editing, proofreading, and discussing the evolution of the document have been invaluable.
We would also like to thank the TWAIN Working Group Technical Committee for their opinions
and contributions..
Adobe Systems Incorporated
Scott Foshee
Atalasoft
Glenn Chittenden Jr.
Adam Scarborough
Spike McLarty
Avision inc.
Leo Liao
Jun Huang
Dynamsoft Corporation
Catherine Sea
Kodak Alaris, Inc.
Mark McLaughlin
Epson
Tak Shiozaki
Fujitsu Computer Products of America
Pamela Doyle
Hewlett-Packard
Sarah Schwartz
JFL Peripheral Solutions Inc.
Jon Harju
Rebecca Holz
Mihail Mikov
Pete Patterson
PFU Limited, a Fujitsu Company
Daisuke Kutsuwada
The TWAIN Working Group
Hilary Minugh
TWAIN 2.3 Specification i
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-1
Need for Consistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Elements of TWAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Benefits of Using TWAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Creation of TWAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
2. Technical Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1
TWAIN Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
TWAIN User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Communication Between the Elements of TWAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Using Operation Triplets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
The State-Based Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14
Modes Available for Data Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19
3. Application Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1
Levels of TWAIN Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
Installation of the Source Manager Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Changes Needed to Prepare for a TWAIN Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Controlling a TWAIN Session from Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26
Best Practices for TWAIN Compliant Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28
Legacy Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40
Table of Contents
ii TWAIN 2.3 Specification
4. Advanced Application Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1
Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Options for Transferring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
The ImageData and Its Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23
Transfer of Multiple Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26
Transfer of Compressed Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32
Alternative User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35
Grayscale and Color Information for an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38
5. Source Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-1
The Structure of a Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
Operation Triplets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Sources and the Event Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
User Interface Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Capability Negotiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Data Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Requirements for a Source to be TWAIN-Compliant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Other Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21
6. Entry Points and Triplet Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-1
Entry Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Data Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
Data Argument Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Custom Components of Triplets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Table of Contents
TWAIN 2.3 Specification iii
7. Operation Triplets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-1
Triplet Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Format of the Operation Triplet Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Operation Triplets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
8. Data Types and Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-1
Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1
Platform Dependent Definitions and Typedefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
Definitions of Common Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
Data Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
Data Argument Types that Don’t Have Associated TW_Structures . . . . . . . . . . . . . . . . . . . 8-63
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-65
Deprecated Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-98
9. Extended Image Information Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-1
TWAIN 1.7 Extended Image Attribute Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1
TWAIN 1.9 Extended Image Attribute Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
TWAIN 1.91 Extended Image Attribute Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14
TWAIN 2.0 Extended Image Attribute Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16
TWAIN 2.1 Extended Image Attribute Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16
TWAIN 2.2 Extended Image Attribute Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17
TWAIN 2.3 Extended Image Attribute Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17
10.Capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Required Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
Capabilities in Categories of Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
