DTwainListener

During image acquisition, DTWAIN can inform your application of the progress of the acquisition by sending a message as well as a notification code.  Without the DTWAIN C++ classes, your application would need to set up a callback function (a call to DTWAIN_SetCallback) or register the main window as the notification window when DTWAIN_StartTwainSession is called.

You can still register a window as the notification window (see the DTwainInterface constructor and DTwainInterface::InitInterfacefunctions), however, callback functionality is done through a special class called a listener.

The DTwainListener class allows your application to "listen" to DTWAIN events when they occur during the acquisition process.  The DTwainListener is attached to the DTwainAcquirer object, allowing the DTwainAcquirer object to communicate between DTWAIN and the DTwainListener during the acquisition process.  An application can attach one or more listeners to the DTwainAcquirer object.

To use a DTwainListener, the programmer must derive a class from DTwainListener, and then override the desired listener function in the derived class to do user-defined processing.  A quick example of defining a DTwainListener is below:

#include <cdtwain.h>

class MyListener : public DTwainListener

{

public:

     // This function is called when a transfer is ready

     LRESULT OnTransferReady( DTwainSource& Source, LONG UserParam )

     {

        // always return 1 except for special cases.

         return 1;

     }

     // called when transfer is done.

     LRESULT OnTransferDone( DTwainSource& Source, LONG UserParam )

     {

         return 1;

     }

};

The OnTransferReady and OnTransferDone are listener event functions that will be called whenever an image is about to be acquired directly from the device, and when the acquisition of the image has been executed, respectively.  Note that most of the listener functions take two parameters, a reference to the DTwainSource that triggered the listener function call, and a user-defined parameter (this is set if you call the DTwainListener::SetUserData( ) function).

To add the listener to the DTwainAcquirer object the DTwainAcquirer::AddListener function is called.  An example is below:

//....

int main( )

{

   DTwainInterface TI(NULL, NULL);  // Initialize DTWAIN

   DTwainSource Source = DTwainSource::Select( );

   if ( !Source.IsValid( ) )

       return 0;

    DTwainAcquirer Acq( Source );

    // Create a listener

    MyListener Listener;

    // Add it to the list of listeners in the DTwainAcquirer object

    Acq.AddListener( &Listener );

    // Go

    Acq.Acquire("DTWAIN.BMP");      

}

//...

The code above adds the listener MyListener to the DTwainAcquirer object.  This allows the DTwainAcquirer object to call the MyListener functions whenever an action is triggered by DTWAIN during the acquisition process.  In the example above, when the "transfer ready" is invoked, the MyListener::OnTransferReady( ) will be called.  Likewise, the MyListener::OnTransferDone( ) is called whenever the image has been acquired successfully.

Note that the DTwainListener object that is added using AddListener( ) must not go out of scope during the acquisition process.  This is required, since the listener must be "alive" during the acquisition process.

You can add as many DTwainListener objects to a DTwainAcquirer object as desired.  When an action occurs during the acquisition process, the listener's are called in the order that they were added to the DTwainListener object.  The return value of the last DTwainListener added is the return value that will be used when communicating with DTWAIN.  Therefore if you are going to use multiple listeners, always place the listener that will return the final value last in the list of listeners.

All of the event functions that are available in the DTwainListener object has analogous DTWAIN notification codes.  For example, OnTransferReady( ) is equivalent to trapping the DTWAIN_TN_TRANSFERREADY notification.