DTwainBufferedTransfer

Top  Previous  Next

Note:  You must be familiar with the buffered image transfer mode before reading this section.  Buffered transfers are discussed fully in the main help manual.

 

The DTwainBufferedTransfer class is derived from DTwainCompressedTransfer. Therefore public functions available to DTwainCompressedTransfer are available to DTwainBufferedTransfer.

 

A buffered image transfer is one where the image that is acquired from the Twain device is done in multiple passes.  Each pass produces a "strip" of image data, where the size of the strip to acquire can be set programatically.  The advantages of acquiring images using the buffered transfer are too numerous to mention in this manual, however, these details are covered in the main DTWAIN help manual DTWAIN32.HLP.

 

There are two ways to start a buffered image transfer using the DTWAIN C++ classes.  The easiest way is to call the DTwainAcquirer::SetAcquireType( ) using the TWAIN_ACQUIREBUFFERED flag, and then calling DTwainAcquirer::Acquire( ) to start the acquisition:

 

#include "cdtwain.h"

#include <iostream>

 

using namespace DTWAIN;

using namespace std;

 

int main( )

{

  // Initialize DTWAIN - return if initialization does not work

  DTwainInterface TI;

 

  // Declare a Source and assign the default TWAIN source to it

  DTwainSource Source = DTwainSource::Select( );

 

  // Declare an acquisition object, and attach the source to it

  DTwainAcquirer Acq(Source);

 

  // Set the acquire type to Native

  Acq.SetAcquireType(TWAIN_ACQUIREBUFFERED);

 

  // Start the acquisition

  Acq.Acquire( );

 // handle acquired dibs...

 //...

}

 

The example program above starts an image acquisition using the buffered image transfer.  The size of the strips used when acquiring the data from the device is always the preferred size.

 

However, one unique aspect of buffered image transfers (as opposed to native transfers) is that

 

1) You can specify the size of the strips of data when acquiring the image

2) You can specify a certain compression type to use for the acquired data (if the Twain Source has support for compressed data).

 

The method described above does not allow you to specify the strip size or compression type.  To do this, a specialized form of the DTwainAcquirer::Acquire function is required to fit this purpose.  This specialized version has as a parameter a DTwainBufferedTransfer object that has all of this information.  In addition, a special listener object called a DTwainBufferedListener that collects the data while the image is being acquired needs to be created.

 

The following code illustrates this:

 

#include "cdtwain.h"  // CDTwain

 

using namespace DTWAIN;

using namespace std; // for <iostream>

 

int main( )

{

  // Initialize DTWAIN - return if initialization does not work

  DTwainInterface TI;

 

  // Declare a Source and assign the default TWAIN source to it

  DTwainSource Source = DTwainSource::Select( );

 

  // Create an acquire object, attach the source

  DTwainAcquirer Acq( Source );

 

  // Set the acquire type to buffered mode

  Acq.SetAcquireType( TWAIN_ACQUIREBUFFERED );

 

  // Create a buffered transfer helper object, and attach Source to the object,

  DTwainBufferedTransfer BT(Source);

 

  // Now set the strip size.  Preferred strip size is illustrated here.

  BT.SetStripSize( BT.GetPreferredStripSize( ) );

 

  // Attach to a special buffered transfer listener that writes images to files and increments the

  // file name to the "next" file.

  std::string fName = "FILE000";

  DTwainBufferedListener Listener( fName, &BT );

  Acq.AddListener( &Listener );

 

  // Start the acquisition

  Acq.Acquire( BT );  

} // If acquisition completed, raw data files FILE000, FILE001, FILE002, etc. should be available

 

If we look at the above example in depth, basically everything is the same as the first example until we get to the line that declares a DTwainBufferedTransfer object called BT.  Note that the parameter used to construct this object is the DTwainSource Source.  The next line sets the strip size to the preferred size by calling the member function SetStripSize.  By default, the preferred size is always used, however the call to SetStripSize is used here for illustrative purposes.

 

Then the listener object DTwainBufferedListener is created with the name of the file to save the buffered data (however, you do not need to save the acquired data to the file), and a pointer to the DTwainBufferedTransfer object defined earlier.  This listener is then added to the DTwainAcquirer object using the AddListener function.  The last step is to call the DTwainAcquirer::Acquire function using the DTwainBufferedTransfer object as the parameter.

 

What does this all do?  This does the following:

 

Acquires buffered data and saves it to the file named FILE000.  If there are more pages to acquire, the file name is incremented by 1. For example, FILE000 will be the name of the first file, FILE001 is the second page, FILE002 is the third page, etc.

 

Note that this is not the same as the DTWAIN file acquisition mode.  This is still a buffered memory transfer, but using the magic of the DTwainBufferedTransfer and the DTwainBufferedListener, files are created that store the data acquired.

 

The DTwainBufferedTransfer object contains functions that set the strip size, set the compression type, check if a compression type is supported, etc.  The DTwainBufferedListener object handles the saving of the data to a buffer, and then at the end of the acquisition, saves the data to a file.

 

Now what if you don't want to save the data to a file?  For example, what if you want to take the saved strips and create your own file, or do something with the image data that has nothing to do with file saving?  All that is possible by just deriving from DTwainBufferedTwainListener and overriding the following functions:

 

DTwainBufferedTransfer::OnEndProcessingStrips( )

 

This function is responsible for saving the acquired data to a file.  By overiding this function, you can stop the saving to a file and handle the data any way your application sees fit.  The acquired data is retrieved by calling the DTwainBufferedListener::GetData( ) or DTwainBufferedListener::GetDataBuffer( ) functions.