DOCSEARCHbyAlgolia
Submit Docs

NTwain TWAIN Application-Side Library

repository·v3·Indexed 41 days ago

https://github.com/soukoku/ntwain

A .NET wrapper for the TWAIN interface supporting TWAIN version 2.3. It provides the TwainSession class for managing TWAIN operations, handling transfer events like TransferReady and DataTransferred, and interacting with DataSources. The library includes support for the TWAIN Data Source Manager (DSM) and provides documentation for Kodak-specific TWAIN driver custom features such as dual-stream scanning and advanced metadata.

Tokens
1.5K
Snippets
5
Records
7
Agent score
1%

What's inside NTwain

  1. Handle TWAIN transfer events

    v3

    The TwainSession provides several key events for managing the scanning lifecycle:

    • TransferReady: Fired before a transfer occurs. You can cancel the current or subsequent transfers using the event object.
    • DataTransferred: Fired after a transfer. If using native image transfer, the event arguments provide a GetNativeImageStream() method to convert the data pointer into a System.IO.Stream.
    • TransferError: Fired when exceptions occur during the transfer phase.
    • SourceDisabled: Fired when the data source has finished its operation.

  3. Select and use a DataSource

    v3

    Once a TwainSession is open, you can discover and open available data sources (scanners).

    1. Iterate through TwainSession (which implements IEnumerable<DataSource>) to find a source.
    2. Call Open() on the selected DataSource.
    3. Use the Capabilities property to negotiate settings or use the triplet API (DGControl, DGImage, etc.) for low-level operations.
    4. Call Enable() on the DataSource to enter transfer mode.
    5. After completion, call Close() on the DataSource and then Close() on the TwainSession to clean up.
    // 1. Choose and open the first source found
DataSource myDS = session.FirstOrDefault();
myDS.Open();

// 2. Configure capabilities (e.g., setting pixel type)
PixelType myValue = PixelType.BlackWhite; 
if (myDS.Capabilities.ICapPixelType.CanSet && 
    myDS.Capabilities.ICapPixelType.GetValues().Contains(myValue))
{
    myDS.Capabilities.ICapPixelType.SetValue(myValue);
}

// 3. Start transfer
myDS.Enable();

// 4. Cleanup after SourceDisabled event
myDS.Close();
session.Close();

  4. Configure SynchronizationContext for UI threads

    v3

    By default, if you call session.Open() without providing a message loop hook, NTwain starts an internal message loop on a background thread. This means events will be raised from that background thread.

    To marshal events to your application's UI thread, set the SynchronizationContext property of the TwainSession to the current UI context.

    Warning: Some scanner drivers use modal dialogs which may cause the application to hang when using this synchronization method.

    // Set this while in a UI thread (e.g., WinForms or WPF)
session.SynchronizationContext = SynchronizationContext.Current;

  5. Overview of Kodak TWAIN Driver Custom Features

    v3

    The Kodak TWAIN driver includes several custom capabilities and features that extend standard TWAIN functionality. This directory contains documentation for developers looking to implement advanced features such as dual-stream scanning, extended image metadata, and programmatic control of scanner functions.

    Key areas of interest for developers include:

    • Custom Capabilities: Defined in kdscust.h.
    • Advanced Metadata: Using DAT_EXTIMAGEINFO for complex image data.
    • Dual-Stream Scanning: Handling simultaneous bitonal/color or bitonal/grayscale scanning.
    • Simulation Mode: Testing scanner models without physical hardware.
    • Diagnostic Tools: Using the driver's logging system to analyze application and scanner behavior.

  6. Configure the TWAIN Data Source Manager (DSM) preference

    v3

    NTwain defaults to using the newer twaindsm.dll if available. If you encounter older sources that are incompatible with the new DSM, you can force the library to use the older twain_32.dll by setting the PreferNewDSM flag on PlatformInfo.Current.

    Note: This flag has no effect in 64-bit processes; 64-bit applications will always require twaindsm to be installed.

    // Force the use of the older twain_32.dll
// Do this once at application startup.
NTwain.PlatformInfo.Current.PreferNewDSM = false;

  7. Initialize and open a TwainSession

    v3

    The TwainSession is the primary class for managing TWAIN operations. An application should only have one active (opened) TwainSession at any time.

    To use it:

    1. Create a TWIdentity (using TWIdentity.CreateFromAssembly is recommended).
    2. Instantiate TwainSession with the identity.
    3. Subscribe to necessary events.
    4. Call Open() to start the session.

    Important: Do not close the session or the source inside the TransferReady, DataTransferred, or TransferError event handlers, as this can cause unpredictable behavior. Use the flag in TransferReady to cancel scans instead.

    // Create an appId using the utility method
var appId = TWIdentity.CreateFromAssembly(DataGroups.Image, Assembly.GetExecutingAssembly());

// Initialize the session
var session = new TwainSession(appId);

// Subscribe to events
session.TransferReady += ...
session.DataTransferred += ...

// Open the session
session.Open();