KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

twain_library

★ 101 Open GitHub ↗

Dynarithmic TWAIN Library, Version 5.x

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

### The Dynarithmic TWAIN Library repository ###

* This repository contains the DTWAIN Library, **Version 5.x**, from Dynarithmic Software.  DTWAIN is an open source programmer's library that will allow applications to acquire images from TWAIN-enabled devices using a simple Application Programmer's Interface (API).

* The Dynarithmic TWAIN Library is open source and licensed under the Apache 2.0 License.  Please read the [LICENSE](https://github.com/dynarithmic/twain_library/tree/master/LICENSE) file for more information.
* The DTWAIN Library online help file can be found [here](https://www.dynarithmic.com/onlinehelp/dtwain/newversion/Dynarithmic%20TWAIN%20Library,%20Version%205.x.html), and in .CHM (Windows Help) format [here](https://github.com/dynarithmic/twain_library-helpdocs/tree/main/windows).

The .CHM file and online-help are being updated to version 5.x on a constant basis.  Updates will be made available in the [help repository](https://github.com/dynarithmic/twain_library-helpdocs/tree/main), as it may have information that pertains to the older commercial version of DTWAIN that will have to be updated or removed.
* The current version of DTWAIN is [**5.9.2** (See Version History)](https://github.com/dynarithmic/twain_library/tree/master/updates/updates.txt).

**Please note that the source code and sample programs for the Dynarithmic TWAIN Library has moved to [this repository](https://github.com/dynarithmic/twain_library_source/tree/main)**.

----
----
### Table of Contents

##### [What is the Dynarithmic Twain Library?](#anchor-what-is-dtwain)
##### [Is the Dynarithmic Twain Library open source?](#anchor-is-dtwain_oss)
##### [Preliminaries](#anchor-preliminaries)
##### [Testing without a TWAIN device](#anchor-no-device)
##### [How do I setup DTWAIN (library setup, building the application, and running the application)?](#anchor-dtwain-setup)
##### [Simple code samples](#anchor-code-samples)
##### [DTWAIN usage for C or C++ compilers that are not Microsoft Visual C++ (examples are g++, mingw, clang, etc.)](#alternatecompilers)
##### [Using DTWAIN in C#, Visual Basic and other computer languages](#otherlanguages)
##### [The TWAIN Event Driven programming model](#anchor-event-driven)
##### [Obtaining the DTWAIN Library source code](#anchor-source-code)
##### [DTWAIN and Linux compatibility](#anchor-linux)
##### [Final note for developers](#anchor-final-note)
##### [Reporting Issues](#anchor-issues)
##### [Who authored the DTWAIN library?](#anchor-author)

----
----
<a id="anchor-what-is-dtwain"></a>
### What is the Dynarithmic TWAIN library? ###

* The Dynarithmic TWAIN Library (also known as DTWAIN) is an open source, powerful programmer's library that will allow you to easily integrate TWAIN image acquisition from any TWAIN scanner or digital camera into your applications.

* DTWAIN is implemented as a 32-bit and 64-bit Windows Dynamic Link Library (DLL), and to communicate with the DLL, exported functions are provided.  This allows any Windows-based computer language that can call exported DLL functions (directly or indirectly) to be able to use DTWAIN.  This includes C, C++, C#, Visual Basic, Python, Delphi, Lua, Java, Ruby, Rust, Go, F#, and numerous other languages.

* If you are not familiar with the TWAIN standard and image acquisition from TWAIN-enabled devices, please head to the official TWAIN website at [http://www.twain.org](http://www.twain.org) for more information.  If you've ever bought or used a scanner, and came across the words "TWAIN compliant" or "TWAIN driver", well you're on the right track.  If you're interested in getting these devices to work in your **C, C++, C#, D, Delphi, F#, Lua, Java, Visual Basic, Perl, Python, Ruby, Rust, Go** (and other languages) application, you've come to the right place.

* The DTWAIN library relieves the programmer of having to get into the details of writing low-level code that follows the TWAIN specification to retrieve images from a TWAIN device -- just a few function calls to initialize and acquire images from the TWAIN device is all that's required.

(There is nothing wrong with understanding the TWAIN specification, as this will enhance your knowledge of how the DTWAIN library works internally.  However the high-level of abstraction of the TWAIN protocol makes this library simple for even the novice programmer to use).

----------
----------
<a id="anchor-is-dtwain_oss"></a>
### Is DTWAIN 5.x Open Source Software (OSS)? 
 
* The Dynarithmic® TWAIN Library has been developed over the course of 20 years, so this is a very mature software component. We have offered this library as a closed source, commercial product over those years, however we have decided to make this library open source under the Apache 2.0 license.

* Please note -- since DTWAIN prior to version 5.0 used source code in some modules that could not be released to the general public due to licensing issues, we had to revamp these portions of the codebase so as to allow DTWAIN to become an open source library.  We have made all strives to make sure that these changes to DTWAIN will not cause issues, but as most of you know, bugs can exist.  If bugs are found, we will be addressing them in a short manner.

----------
----------
<a id="anchor-preliminaries"></a>
### Preliminaries

DTWAIN is supported under *Windows 10 / Windows 11 for both 32-bit and 64-bit operating systems. Since the base libraries are built to support the Visual C++ runtime library, version 2015 and above, the minimum version of the Visual C++ runtime that is supported is **Visual C++ 2015**.

*There is no official support for Windows 7 / Windows 8.x, as newer versions of DTWAIN are only tested for Windows versions 10 and 11.  Note that this is not to say that DTWAIN will not work for Windows 7 / 8, but it hasn't been tested with these operating systems for the past few years.  If you require support for Windows 7 or 8, please open an [issue](https://github.com/dynarithmic/twain_library/issues) to see if this can be addressed.

----

----------
<a id="anchor-no-device"></a>
### I don't have a TWAIN device or scanner installed on my system. How do I work with DTWAIN?
There are sample virtual TWAIN devices [found here](https://github.com/dynarithmic/twain_virtual-drivers). Once installed, these devices will be available for selection for acquiring images, similar to an installed scanner.

----------
----
<a id="anchor-dtwain-setup"></a>
### How do I setup DTWAIN (library setup, building the application, and running the application)? ###
----

Basically, all that is required to initially set up DTWAIN is to ensure that the proper DTWAIN DLL's are located where the Windows operating system will find them (usually in a directory specified on the system **PATH**), and that various [mandatory text files](https://github.com/dynarithmic/twain_library/tree/master/text_resources) are also present.

All of this will be discussed in detail below.

----

**Building the DTWAIN application:**

<a name="dtwaindllusage"></a>
For 32-bit applications, use the DTWAIN dynamic link libraries (DLL's) found in [DTWAIN-Release-x86.zip](https://github.com/dynarithmic/twain_library/releases/latest/download/DTWAIN-Release-x86.zip), and within this zip file, one of the following directories:

* **no_vcruntime** 
* **require_vcruntime**

----

For 64-bit applications, use the DTWAIN dynamic link libraries (DLL's) found in [DTWAIN-Release-x64.zip](https://github.com/dynarithmic/twain_library/releases/latest/download/DTWAIN-Release-x64.zip), and within this zip file, one of the following directories:

* **no_vcruntime** 
* **require_vcruntime**

----

The **no_vcruntime** directory contains the DTWAIN DLL's that do not require an installation of the Visual C++ Runtime on the target system when utilizing the DTWAIN API functions.

The **require_vcruntime** directory contains the DLL's that require an installation of the Visual C++ Runtime on the target system.

Since most Windows systems within the past 10 years has the Visual C++ runtime already installed by other applications, using the **require_vcruntime** version of the DTWAIN_DLL's shouldn't be an issue and can be used.

If however you are not sure if the user's of your application using DTWAIN has the Visual C++ runtime installed, you can either:

1) Use the DTWAIN DLL's found in **no_vcruntime**, which require no installation of the Visual C++ runtime or

2) Install the Visual C++ runtime components on the user's system (your installer should do this, or direct the user to install the Visual C++ runtime components below). 
 
If you choose option 2), you can get the Visual C++ runtime libraries <a href="https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#latest-microsoft-visual-c-redistributable-version" target="_blank">here</a>. When downloading, choose **vc_redist.x86.exe** for 32-bit applications, and/or **vc_redist.x64.exe** for 64-bit applications.

In addition, the release version of the Programming Database (.PDB) files are available [here for 32-bit](https://github.com/dynarithmic/twain_library/releases/download/v5.9.0/DTWAIN-ReleasePDB-x86.zip) and [here for 64-bit](https://github.com/dynarithmic/twain_library/releases/download/v5.9.0/DTWAIN-ReleasePDB-x64.zip).  This will aid in debugging any issues involving DTWAIN utilizing the Microsoft Visual Studio debugger and/or the WinDBG Microsoft debugger.

Note: Starting with **DTWAIN 5.9.1**, prebuilt DTWAIN DLLs that had the "no-logging" option, even though a bit smaller than the DLL's that had logging support, are no longer distributed separately.  All standard DTWAIN release DLLs include logging support.  Developers who require no-logging builds may [rebuild DTWAIN from source](https://github.com/dynarithmic/twain_library_source) using the `DTWAIN_ENABLE_LOGCALLSTACK=OFF` in the CMake build options.

----

A breakdown of the main files contained in **DTWAIN-Release-x86.zip** and **DTWAIN-Release-x64.zip** is as follows:

dtwain32.dll   --  32-bit ANSI (MBCS) Dynamic Link Library
    dtwain32u.dll  --  32-bit Unicode Dynamic Link Library
    dtwain32.lib   --  32-bit ANSI (MBCS) Visual C++ import library
    dtwain32u.lib  --  32-bit Unicode Visual C++ import library
    32bit_FullDemo --  Directory containing the 32-bit demo program (DTWDEMO32U)

dtwain64.dll   --  64-bit ANSI (MBCS) Dynamic Link Library
    dtwain64u.dll  --  64-bit Unicode Dynamic Link Library
    dtwain64.lib   --  64-bit ANSI (MBCS) Visual C++ import library
    dtwain64u.lib  --  64-bit Unicode Visual C++ import library
    64bit_FullDemo --  Directory containing the 64-bit demo program (DTWDEMO64U)

Please note that the DLL files that have file names that end with "u" are Unicode-aware, for example `dtwain32u.dll` is Unicode-aware.  If your application requires Unicode-based string processing, it is always best to use the "u" versions of the above files.

For example, if you plan to use the [language text resources](https://github.com/dynarithmic/twain_library/tree/master-staging/additional_language_resources) that use UTF-8 character sequences that have issues displaying properly using the ANSI version of the library (for example, Greek), you should use one of the "u" DLL's listed above.  More info on the language text resources are found later in this README.

The DTWAIN API has available ANSI-aware functions even in the Unicode versions of the library, in the event your Unicode application needs to process ANSI strings.  This is usually done by the API function ends with "A", for example `DTWAIN_GetSourceProductNameA` for the ANSI version of the function `DTWAIN_GetSourceProductName`.  Similarly, there are Unicode or wide-character functions available for the ANSI version of the DLL's in the event your ANSI-based application needs to process wide/Unicode strings (for example `DTWAIN_GetSourceProductNameW` for the wide-character version of the function `DTWAIN_GetSourceProductName`).

**32-bit and 64-bit demo program (DTWDEMO)**

The **32bit_FullDemo** and **64bit_FullDemo** directories contain the full versions of the 32-bit DTWDEMO program (`DTWDEMO32U.exe`) and 64-bit DTWDEMO program (`DTWDEMO64U.EXE`), respectively.

The DTWDEMO programs can be used to test various aspects of the DTWAIN API and your TWAIN devices (capability testing and setting, acquiring images and files, etc.).  Copy all files from either the **32bit_FullDemo** or **64bit_FullDemo** to an empty directory and run either `DTWDEMO32U.exe` or `DTWDEMO64.exe` directly from the directory.

Please note that the DTWDEMO program demonstrates just a subset of what the DTWAIN API is capable of.  When running the DTWDEMO program, remember that *all* aspects you are seeing when running DTWDEMO with respect to handling TWAIN devices is done using DTWAIN API calls.  This includes selecting TWAIN devices for acquisition, capability testing, etc.

The source code to the DTWDEMO program (written in C using the Win32 API) can be found [here](https://github.com/dynarithmic/twain_library/tree/master/demos/C_C%2B%2B/C/FullDemo).

A similar demo program written in Python using the [Python language bindings for DTWAIN ](#otherlanguages) can be found [here](https://github.com/dynarithmic/twain_library-python_demo).

----

###### Information for C and C++ programmers only:

If you are using Visual C++, the Visual C++ compatible import libraries necessary to build your 32-bit or 64-bit application (the files with the *.lib extension) are available. 
If you do not use Visual C++ but instead are using another brand of C++ compiler, see the [section on additional C++ compiler usage](#alternatecompilers) to alleviate the import library issues.

You will also need to include the header files found in the [c_cpp_includes](https://github.com/dynarithmic/twain_library/tree/master/c_cpp_includes) directory when building your application.  Your build **INCLUDE** path should refer to these header files.

Basically, you just need to build your application and link it to one of the import libraries that matches the environment your application is targeted for.  For example, if the application you're developing is a 32-bit, Unicode-based application, you would use the **dtwain32u.lib** file to allow your C/C++ application to link without errors.

----
<a name="runningapplication"></a>
**Running your DTWAIN application**

After building your application, for your application to run successfully, you must make sure the DTWAIN dynamic link library itself is located somewhere on the system path, or in your application directory.

There are other places that DLL's can be placed so as to be recognized by the application, but that is beyond the scope of this introduction -- please refer to the following link for further information:

[https://docs.microsoft.com/en-us/windows/desktop/dlls/dynamic-link-library-search-order](https://docs.microsoft.com/en-us/windows/desktop/dlls/dynamic-link-library-search-order).

In addition to the DLL files, the <a href="https://github.com/dynarithmic/twain_library/tree/master/text_resources/twaininfo.txt" target="_blank">text resource file</a>, the <a href="https://github.com/dynarithmic/twain_library/blob/master/text_resources/dtwain32.ini" target="_blank">dtwain32.ini</a> for 32-bit applications, and <a href="https://github.com/dynarithmic/twain_library/blob/master/text_resources/dtwain64.ini" target="_blank">dtwain64.ini</a> for 64-bit applications </a> must also be available (by default, these files should reside in the same directory as the DLL files above, however as of version **5.2.0.2**, these files can reside in the directory specified by **DTWAIN_SetResourcePath**).

If **twaininfo.txt** or the INI files are not found, corrupted, incorrect version, or some other issue that prevents these files from being loaded, you will receive the following message box displayed, with one or more reasons for the error listed:

![following error when running your application](https://raw.githubusercontent.com/dynarithmic/twain_library/master/images/resource_error.jpg)

The error message will differ depending on the reason for the error.

Note: If your application wants to suppress the above message box, but still receive an error return code, your application should issue a call to the API function **DTWAIN_SysInitializeNoBlocking** instead of **DTWAIN_SysInitialize** (see the examples below -- simply change **DTWAIN_SysInitialize** to **DTWAIN_SysInitializeNoBlocking**).

* Make sure that you are running the latest version of **twaininfo.txt**, as changes to this file can affect how your application will run when using future versions of DTWAIN.  The simplest way to ensure that you are running the latest version is to always get the latest **twaininfo.txt** file whenever you use a newer release of the DTWAIN DLL's.

An internal check for the resource version is done by DTWAIN.  If DTWAIN detects that the resources are corrupted or out-of-date, **DTWAIN_SysInitialize** will return a NULL handle indicating an error.

If **DTWAIN_SysInitialize** or **DTWAIN_SysInitializeNoBlocking** returns a 0 or null handle, you should call **DTWAIN_GetLastError** to get the error value.  In addition, you can call **DTWAIN_GetErrorString** with the error number to get a string description of the error.

----

In addition, there are [optional string resource files available](https://github.com/dynarithmic/twain_library/tree/master-staging/additional_language_resources).  These files allow you to customize the language used when DTWAIN logs or reports errors.  Note that these files are loaded only after **DTWAIN_SysInitialize** or **DTWAIN_SysInitializeNoBlocking** returns without error.

These files should be placed in the same directory as the **twaininfo.txt** file and INI files.

If you want to use a different resource file or even add your own language resource, it is recommended you copy the file in question, rename the file, make the changes required, and then utilize the new file by calling the **DTWAIN_LoadCustomStringResources** API function.

More detailed instructions on adding your own resource file can be found <a href="https://github.com/dynarithmic/twain_library/tree/master/additional_language_resources" target="_blank">here</a>.

----------
----------
<a id="anchor-code-samples"></a>
### Simple code samples

Please note: For ease of use, the simple examples below make usage of the "A" version of the DTWAIN functions (the functions that require ANSI strings). This makes the samples compile successfully "out of the box" for those programmers using C or C++ without having to use wide or Unicode strings directly.

The simplest example is probably one that opens the TWAIN "Select Source" dialog, allows the user to choose the TWAIN device.  Once chosen, the device acquires an image and saves the image as a BMP file named "Test.bmp".  Here is an entire C++ example that demonstrates this:

#include <iostream>
 #include "dtwain.h"

int main()
    {
        // initialize the DTWAIN DLL
        DTWAIN_SysInitialize();
        
        // Show the "Select Source" TWAIN dialog box
        DTWAIN_SOURCE Source = DTWAIN_SelectSource();
        
        if ( Source ) // Will be non-zero if a Source is selected by the user
            // Acquire to a BMP file
            DTWAIN_AcquireFileA(Source, "Test.bmp", DTWAIN_BMP, DTWAIN_USENATIVE | DTWAIN_USENAME,
                                DTWAIN_PT_DEFAULT, DTWAIN_MAXACQUIRE, TRUE, TRUE, NULL);
        DTWAIN_SysDestroy();         
    }

That's it.

The program above displays the default "Select Source" dialog when choosing a Source.  This dialog is the dialog as defined by the TWAIN standard.  This dialog box cannot be "altered" or customized.

However, you can customize the "Select Source" dialog box by utilizing the dialog box resource defined in the DTWAIN DLL, and then utilize the `DTWAIN_SelectSource2()` function:

#include <iostream>
 #include "dtwain.h"

int main()
    {
        // initialize the DTWAIN DLL
        DTWAIN_SysInitialize();
        
        // Show the "Select Source" with a custom title, 
        // centered on the current monitor, sort the names, and always have it at the topmost window
        DTWAIN_SOURCE Source = DTWAIN_SelectSource2A(NULL, "Custom Title", 0, 0,                      
                DTWAIN_DLG_CENTER_CURRENT_MONITOR | DTWAIN_DLG_SORTNAMES | DTWAIN_DLG_TOPMOSTWINDOW);
                
        if ( Source ) // Will be non-zero if a Source is selected by the user
            // Acquire to a BMP file
            DTWAIN_AcquireFileA(Source, "Test.bmp", DTWAIN_BMP, DTWAIN_USENATIVE | DTWAIN_USENAME,
                                DTWAIN_PT_DEFAULT, DTWAIN_MAXACQUIRE, TRUE, TRUE, NULL);
        DTWAIN_SysDestroy();         
    }

In addition to selecting a Source by using the "Select Source" dialog box, you can select a TWAIN Source by using the TWAIN Source's "Product Name", i.e. the name that is used within the dialog box.

This effectively selects the TWAIN Source without the dialog box appearing.  The function to use would be `DTWAIN_SelectSourceByName` instead of `DTWAIN_SelectSource` or `DTWAIN_SelectSource2`

#include <iostream>
 #include "dtwain.h"

int main()
    {
        // initialize the DTWAIN DLL
        DTWAIN_SysInitialize();
        
        // Select a TWAIN Source called "My Scanner".  This assumes that "My Scanner" is the name
        // of one of the TWAIN devices installed on the system
        DTWAIN_SOURCE Source = DTWAIN_SelectSourceByNameA("My Scanner");
                
        if ( Source ) // Will be non-zero if a Source is successfully selected
        {
            //...
        }
        DTWAIN_SysDestroy();         
    }

----

If you desire to acquire to an image in memory instead of an image file, that can be done also.  By default, a Windows-based TWAIN driver always returns a Device Independent Bitmap (DIB) as the memory image.

#include "dtwain.h"
    int main()
    {
        DTWAIN_SysInitialize();
        DTWAIN_SOURCE Source = DTWAIN_SelectSource();
        DTWAIN_ARRAY images;
        if ( Source )
        {
            images = DTWAIN_AcquireNative(Source, DTWAIN_PT_DEFAULT, DTWAIN_MAXACQUIRE, TRUE, TRUE, NULL);
            HANDLE hDib = DTWAIN_GetAcquiredImage(images, 0, 0); // handle to first DIB acquired is returned
            GlobalLock(hDib); // lock image
            /*Now our app has a DIB. We can do any function that needs a DIB
              This time, we'll just delete it.  Your app is responsible for deleting 
              the DIBs, since DTWAIN does not delete any DIBs generated 
              by the Source  */
            GlobalFree( hDib );
        }   
        DTWAIN_SysDestroy();         
    }

The above assumes your application knows how to handle DIBs (they are basically BMP files).  Also note that the DTWAIN_GetAcquiredImage function takes three arguments.  The first is a "2 dimensional" array of images that were acquired, and the last two arguments denote the *acquisition number* and the *image number* in the acquisition (this technique is used to remember multipage acquisitions that occur without the user closing the device's user interface).

----

In addition, you can acquire images without showing a user interface by simply specifying the "show user-interface" parameter to either TRUE (1), or FALSE (0).

DTWAIN_AcquireFileA(Source, "Test.bmp", DTWAIN_BMP, DTWAIN_USENATIVE | DTWAIN_USENAME, 
                        DTWAIN_PT_DEFAULT, DTWAIN_MAXACQUIRE, FALSE, TRUE, NULL);

or if it is the second example:

images = DTWAIN_AcquireNative(Source, DTWAIN_PT_DEFAULT, 
                                  DTWAIN_MAXACQUIRE, FALSE, TRUE, NULL);

----------

### What about setting device capabilities such as resolution, contrast, brightness, paper size, etc.?

Setting and getting device capabilities is an integral part of using a TWAIN-enabled device.  This is easily done by using the generic capability functions such as **DTWAIN_EnumCapabilities**, **DTWAIN_GetCapValues** and **DTWAIN_SetCapValues**, or one of the functions that wrap the setting of a capability such as **DTWAIN_SetResolution**, **DTWAIN_SetBrightness**, etc.

Here is an example of setting the ICAP_PIXELTYPE capability:

#include "dtwain.h"
    int main()
    {
        DTWAIN_SysInitialize();
        DTWAIN_SOURCE Source = DTWAIN_SelectSource();
        if ( Source )
        {
            // set the pixel type to TWPT_RGB
            
            // First, create a DTWAIN_ARRAY to hold the value(s) we will set
            DTWAIN_ARRAY aPixelTypeValue = DTWAIN_ArrayCreateFromCap(Source, ICAP_PIXELTYPE, 0);
            
            // Add the TWPT_RGB value to our array of values
            DTWAIN_ArrayAddLong(aPixelTypeValue, TWPT_RGB);
            
            // Call function to set the ICAP_PIXELTYPE capability
            DTWAIN_BOOL result = DTWAIN_SetCapValues(Source, ICAP_PIXELTYPE, DTWAIN_CAPSET, aPixelTypeValue);
            
            if ( result )
            {
                // Capability was set
            }
            
            // Dispose of the array
            DTWAIN_ArrayDestroy(aPixelTypeValue);
        }   
        DTWAIN_SysDestroy();         
    }

Here is an example of getting all of the available ICAP_PIXELTYPE values:

#include <stdio.h>
 #include "dtwain.h"
 int main()
 {
 DTWAIN_SysInitialize();
 DTWAIN_SOURCE Source = DTWAIN_SelectSource();
 if ( Source )
 {
 // Get the pixel type values
 
 // First, declare a DTWAIN_ARRAY that will hold all the value(s) retrieved from the device
 DTWAIN_ARRAY aPixelTypeValues;
 
 // Call function to get all the ICAP_PIXELTYPE capabilities
 DTWAIN_BOOL result = DTWAIN_GetCapValues(Source, ICAP_PIXELTYPE, DTWAIN_CAPGET, &aPixelTypeValues);
 
 if ( result )
 {
 // Now array has all of the values. Print each one:
 LONG numItems = DTWAIN_ArrayGetCount(aPixelTypeValues);
 LONG pixValue;
 for (int i = 0; i < numItems; ++i)
 {
 DTWAIN_ArrayGetAtLong(aPixelTypeValues, i, &pixValue); 
 printf("Pixel Type value %d is %d\n", i+1, pixValue);
 }
 DTWAIN_ArrayDestroy(aPixelTypeValues);
 } 
 } 
 DTWAIN_SysDestroy(); 
 }

Here is an example that calls the high-level function DTWAIN_SetResolution that sets the resolution to 300 DPI.  Note that DTWAIN_SetResolution() is just a "shortcut" way of setting the `ICAP_XRESOLUTION` and `ICAP_YRESOLUTION` capabilities:

#include "dtwain.h"
    int main()
    {
        DTWAIN_SysInitialize();
        DTWAIN_SOURCE Source = DTWAIN_SelectSource();
        if ( Source )
        {
            // set the resolution level to 300 dots-per-inch
            DTWAIN_SetResolution(Source, 300.0); 
            //...
        }   
        DTWAIN_SysDestroy();         
    }         
 
Of course, if the capability does not exist on the device, or if the values given to the capability are not supported (for example, if the device only supports 200 DPI and the function attempts to set the DPI to 300), the function returns FALSE and the error can be determined by calling **DTWAIN_GetLastError**.

In general, DTWAIN can set or get any capability, including custom capabilities that some manufacturers may support, and any future capabilities that may be added to the TWAIN specification.

There are [other demo C and C++ programs](https://github.com/dynarithmic/twain_library/tree/master/demos/C_C++) that you can use to more advanced features of DTWAIN.

----------
----------

<a name="alternatecompilers"></a>
### DTWAIN usage for C or C++ compilers that are not Microsoft Visual C++ (examples are g++, mingw, clang, etc.)

For C/C++ compilers that are not in the Microsoft Visual C++ family such as g++, mingw, clang, and others, and thus cannot use the provided Visual C++ import library files directly (or easily) when building your application, you can do one of two things:

1. Attempt to convert the .lib files mentioned above to your compiler's version of an import library, or
2. Use dynamic library loading using the Windows API LoadLibrary, GetProcAddress, and FreeLibrary calls.  Usage of this method requires no import libraries to be used (which makes this a better choice).

For the first item, some compilers have external tools that allow you to use Visual Studio generated library files.  However, there still may be some quirks in those tools that do not create correct import libraries.

For the second item, the [C/C++ dynamic bindings](https://github.com/dynarithmic/twain_library/blob/master/programming_language_bindings/C_CPP_DynamicLoad) should be used that easily facilitate usage of LoadLibrary, GetProcAddress, etc. without your application having to do the tedious and error-prone setup of function pointers, parameter types, return types, etc.

----------
----------

<a name="otherlanguages"></a>
### Using DTWAIN in C#, Visual Basic and other computer languages ###

DTWAIN will work with any computer language that can make calls to an external Windows DLL function.  The DTWAIN DLL's export all the API functions with a "C" interface and with the `__stdcall` calling convention (don't worry if you don't know about calling conventions -- basically all the Windows DLL's in your Windows installation have these properties, so DTWAIN is really no different than those other DLL's in terms of how you would call the exported functions).

To utilize other computer languages, it still requires that one of the [DTWAIN dynamic link libraries (DLL)](#dtwaindllusage) is available at runtime that matches the environment (32-bit or 64-bit), and character set (ANSI, Unicode).  In addition the section on [running your application](#runningapplication) also applies.

DTWAIN includes computer language bindings and demo programs for the following computer languages found in the [programming language bindings](https://github.com/dynarithmic/twain_library/tree/master/programming_language_bindings) folder:

- [C and C++](https://github.com/dynarithmic/twain_library/tree/master/demos/C_C++) -- linking using Visual C++ compatible import libraries 
 - [C and C++](https://github.com/dynarithmic/twain_library/tree/master/programming_language_bindings/C_CPP_DynamicLoad) -- using no import libraries.
 - [C#](https://github.com/dynarithmic/twain_library/tree/master/demos/C%23)
 - [D](https://github.com/dynarithmic/twain_library/tree/master/demos/D)
 - [Delphi](https://github.com/dynarithmic/twain_library/tree/master/demos/Delphi)
 - [F#](https://github.com/dynarithmic/twain_library/tree/master/demos/F%23)
 - [Go](https://github.com/dynarithmic/twain_library/tree/master/demos/Go)
 - [Java*](https://github.com/dynarithmic/twain_library-java)
 - [Lua (using LuaJit)](https://github.com/dynarithmic/twain_library/tree/master/demos/Lua)
 - [Perl](https://github.com/dynarithmic/twain_library/tree/master/demos/Perl)
 - [Python](https://github.com/dynarithmic/twain_library/tree/master/demos/Python)
 - [Ruby](https://github.com/dynarithmic/twain_library/tree/master/demos/Ruby)
 - [Rust](https://github.com/dynarithmic/twain_library/tree/master/demos/Rust)
 - [Visual Basic .NET](https://github.com/dynarithmic/twain_library/tree/master/demos/VisualBasic)
 - [XBase++ (Alaska Software)](https://github.com/dynarithmic/twain_library/tree/master/demos/XBase%2B%2B)

* Note: The Java interface is a full-featured implementation using DTWAIN, and has a dedicated repository found in [twain_library-java](https://github.com/dynarithmic/twain_library-java).

Other languages can be supported, as long as the language is capable of calling exported DLL functions.  The ones listed above have had proper interfaces to the exported functions already set up.

A full C# demo can be found <a href="https://github.com/dynarithmic/twain_library-csharp_demo" target="_blank">here</a>.

A full Visual Basic .NET demo can be found <a href="https://github.com/dynarithmic/twain_library-visualbasic_demo" target="_blank">here</a>.

A full Python demo can be found [here](https://github.com/dynarithmic/twain_library-python_demo).

For Java, it is recommended to look through the numerous demo programs in the [Java interface to DTWAIN repository](https://github.com/dynarithmic/twain_library-java).

----------
----------
<a name="anchor-event-driven"></a>
### Programming issues with an event driven system such as TWAIN.

Since TWAIN is an event-driven system, it is advantageous for whatever language you use to be able to support "callback" functions, i.e. functions that can be called during the TWAIN acquisition / scanning process.  There are a lot of events that occur during the acquisition process that you may want to take advantage of (for example, page about to be scanned, page scanned successfully, immediate access to the acquired image, etc.), and having the ability to capture these events will give your application the most flexibility.

For example, please see the DTWDEMO.exe example program when acquiring to a PDF file, as a page number is added to the page for each page that is acquired by the device.  This is only possible (using DTWAIN) by using callbacks.
  
The **DTWAIN_SetCallback** and **DTWAIN_SetCallback64** sets up your callback function to intercept these events and act accordingly.

Here is an example C++ program that puts a page number on the acquired image files, saved as a PDF document.

#include "dtwain.h"
 #include <iostream>
 #include <cstring>

DTWAIN_SOURCE current_source;

// Demonstrate callback mechanism 
    LRESULT CALLBACK TwainCallbackProc(WPARAM wParam, LPARAM lParam, LONG_PTR UserData)
    {
       // Page count  
       static int pdf_page_count = 1;

// detect if the notification is due to the page about to be saved
       if ( wParam == DTWAIN_TN_FILEPAGESAVING )
       {
            // write text to the bottom left of the PDF page 
            char text[50]; // create the text string
            sprintf(text, "Page %d", pdf_page_count); 
            ++pdf_page_count;

// add the text to the page 
            DTWAIN_AddPDFTextA(current_source, 
                               text,     // text to write on the page 
                               100, 100, // (x, y) postion 
                              "Helvetica", // font to use 
                               14, // font height, in PDF points
                               DTWAIN_MakeRGB(255, 0, 0), // Red text 
                               0, 100.0, 0, 0.0, 0, // scaling, lead, etc. 
                               DTWAIN_PDFTEXT_CURRENTPAGE); // flags denoting when to write this text
       }
       return 1;
    }
    
    int main()
    {
        // initialize and acquire image and save to BMP file 
        if ( !DTWAIN_SysInitialize() )
           return 0;  // TWAIN could not be initialized

current_source = DTWAIN_SelectSource();
        if ( current_source )
        {
            // Enable the callback notification/mechanism 
            DTWAIN_EnableMsgNotify(TRUE);
            DTWAIN_SetCallback(TwainCallbackProc, 0);

// Acquire to a multipage PDF file 
            DTWAIN_AcquireFileA(current_source, "test.pdf", DTWAIN_PDFMULTI, DTWAIN_USENATIVE | DTWAIN_USENAME,
                                DTWAIN_PT_DEFAULT, DTWAIN_MAXACQUIRE, TRUE, TRUE, NULL);
        } 
        DTWAIN_SysDestroy();         
    }

Languages such as C, C++, C#, can use callbacks (sometimes referred to as *delegates* in the .NET world) to allow such functionality.  Other languages also have the capability to set callbacks.  Please refer to the documentation for the language you use to see if callback functionality exists (if you can get the **DTWAIN_SetCallback** or **DTWAIN_SetCallback64** to work for you, then you're not going to have any issues).

----------
----------
<a name="anchor-source-code"></a>
### Obtaining the DTWAIN Library source code ###

The source code and instructions for building DTWAIN are found [here](https://github.com/dynarithmic/twain_library_source/tree/main).

----------
----------
<a name="anchor-linux"></a>
### Is DTWAIN compatible with Linux? ###
Currently, there is no official support for Linux, but things are changing rapidly.

As some may be aware, the TWAIN standard itself is implemented for Linux, but my opinion is that the support is poor.  There is little in terms of actual TWAIN sources to run tests against, and only certain Linux distributions are "supported" (I put this in quotes, since it is still difficult to find TWAIN drivers to run tests against).

The Linux distribution must have the Data Source Manager (DSM) installed (**usr/local/lib/libtwaindsm.so**) before proceeding.  The current distributions that we are aware of that have a working TWAIN Data Source Manager (DSM) is Ubuntu.  We were able to rebuild the DSM (**/usr/local/lib/libtwaindsm.so**) for Fedora 29 (but Fedora is not officially supported, according to the build scripts available for the building of the DSM).

Since there are no pre-built DSM binaries, you can find the DSM source code [here on Github](https://github.com/twain/twain-dsm) and attempt to build the binaries yourself.  However, you may need to change the build scripts, since some of them are hard-coded for certain Ubuntu versions.

Once the DSM is built and installed, the build of DTWAIN can be done using the files in the source directory.  We used the CodeBlocks IDE (using g++ 6.x or higher) to organize the project (we don't currently have a CMake for DTWAIN, but one is in the works).  We also used a custom FreeImage script to do the FreeImage build.  Once done, we found no issues communicating with the Linux DSM with a small test program:

#include "dtwain.h"
    int main()
    {
        DTWAIN_SysInitialize();     /* basic setup */
        DTWAIN_StartTwainSession(); /* communicate with libtwaindsm.so */
        DTWAIN_SysDestroy();         
    }         
  
This is more or less a proof-of-concept.  We will keep you posted on any further progress.

----------
----------
### Is there a .NET wrapper for DTWAIN? ###

We have language bindings (pinvoke's) for C# and Visual Basic.  However we currently lack a true .NET component (just did not have the time to create one).  If anyone out there is willing to create such a .NET component, we are willing to add the component to this repository once vetted and well-tested (and of course, give full credit to the author(s)).

----------
----------
### Is there a C++ class wrapper for DTWAIN? ###

If you're a C++ programmer, and want a wrapper around the DTWAIN libarary, we do have a C++ wrapper for DTWAIN located in the <a href="https://github.com/dynarithmic/twain_library/tree/master/demos/C_C%2B%2B/cpp_wrapper_lib" target="_blank">demos\cpp_wrapper_lib</a> directory. For more information, see the <a href="https://github.com/dynarithmic/twain_library/blob/master/demos/README.md" target="_blank">README.md</a> in the demos directory.

----------
----------
### Final note for developers
<a name="anchor-final-note"></a>
We expect DTWAIN to work flawlessly with almost every TWAIN-enabled device. However, there can be issues that may happen with devices that either do not behave properly, or exercise DTWAIN in a way that's unexpected (for example, we came across a SamSung TWAIN driver for their phone that didn't follow TWAIN compliance, and thus caused issue with DTWAIN).

Given this, the secondary goal of making DTWAIN open source is for you to contribute your fixes to the current DTWAIN code if you come across a device that doesn't work properly with DTWAIN.  There are literally thousands of TWAIN enabled devices out there, old and new, some manufacturers may have discontinued the device model, or maybe even the device manufacturer has gone out-of-business.

Thus, the nature of "fixing" DTWAIN to work with a device that has issues is not possible to be done from a distance without having the device on-hand.  Since there are thousands of devices out there, and more than just a few have TWAIN compliance issues, we rely on our contributors who have the faulty TWAIN device ready and on-hand to debug the issue.

It is highly recommended that you or a developer take advantage of getting the DTWAIN source code and have local builds of the DTWAIN DLL's in the event that the device you are using has issues, and the developer(s) wish to debug the code to see exactly the reason for the issues.

To start, you should download the source code [here](https://github.com/dynarithmic/twain_library_source/tree/main), and follow the directions on the build process for the DLLs.  Note that if you wish to debug the source code (or just trace to see how things actually work), you should be familiar with C and C++, as the base library is written in this language.

The building of the DTWAIN DLLs, given you have the CMake program and Visual Studio 2019, 2022, or 2026 installed, is automated by running a batch file, thus making the build process painless, even for those who are not familiar with the CMake build process and Visual Studio in general.

----------
----------
<a name="anchor-issues"></a>
### Who do I talk to if I have further questions? What if I have issues with the DTWAIN Library?

All questions concerning usage, possible bugs, etc. of the Dynarithmic TWAIN Library must have an issue created on the [Issue page](https://github.com/dynarithmic/twain_library/issues) so as to allow further investigation.

Note that issues will **not** be addressed at **dynarithmic.com** (website or email domain), and instead all issues must be directed to the Github issues page noted above.

--------
--------
<a name="anchor-author"></a>
### Who authored the Dynarithmic TWAIN Library?

The Dynarithmic TWAIN Library's principal developer is Paul McKenzie, and can be reached at [paulm@dynarithmic.com](mailto::paulm@dynarithmic.com).

In addition to 30+ years in the industry, I have made extensive contributions to the [CodeGuru](http://www.codeguru.com) C++ and Visual C++ forums, being one of the top contributors for over 15 years starting in 1999, and since 2014, moved on to  [StackOverflow](https://stackoverflow.com/users/3133316/paulmckenzie?tab=profile), where hopefully I am making an impact with other passionate programmers.  Also, I have had the distinction of being a Microsoft MVP for 10 years running in the Visual C++ category.

twain_library

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README