Example: Native / Buffered Acquisition  (DTWAIN_MODAL)

The example below shows an example of a 'C' function that acquires images using the Native transfer mode. In the example, the DIBs are retrieved and then deleted (in a real world application, the DIBs would be used for display purposes).  The number of acquisitions attempted by the user, as well as the number of images acquired by each acquisition is computed and outputted using the Windows API MessageBox function.

The DTWAIN_MODAL method is the method to use if you desire the easiest TWAIN acquisition code and/or the language that you are using does not support altering the main application loop processing.

The same example can be used for the Buffered transfer mode.  The only difference would be a call to DTWAIN_AcquireBuffered instead of DTWAIN_AcquireNative. Also, if compression is used for the Buffered transfer mode, the returned handles will not be DIBs, but uncompressed image data.

The Source is selected by using the traditional TWAIN 'Select Source' dialog, and the TWAIN message loop is controlled by DTWAIN.

Please note the #include of <tchar.h> and usage of the _T( ) macros for string literals.  This allows the sample code to be used in either a Unicode or ANSI builds.  Please see ANSI and Unicode Application Development for more information.

#include <dtwain.h>

#include <tchar.h>

DTWAIN_SOURCE SelectedSource;

DTWAIN_ARRAY  AcquireArray;

LONG  ErrStatus;

HANDLE  hDib;

LONG numAcquisitions;

LONG Count, Count2, DibCount;

TCHAR szBuf[255];

void AcquireUsingNative( );

void RetrieveAllDibs( );

void AcquireUsingNative( )  

{

   /* See if TWAIN exists on the system */

   /* Quit if TWAIN is not there! */

   /* This call is added so that we can return immediately

   if no TWAIN is found */

   if ( !DTWAIN_IsTwainAvailable( ) ) return;

   /* Initialize the DTWAIN DLL.  Quit if error! */

   if ( !DTWAIN_SysInitialize( )) return;

   /* Select the Source using TWAIN dialog */

   SelectedSource = DTWAIN_SelectSource( );

   /* Only do this if a source is selected */

   if ( SelectedSource )

   {

       AcquireArray = DTWAIN_AcquireNative(

                       SelectedSource, /* TWAIN Source */

                       DTWAIN_PT_DEFAULT, /* Use default */

                       DTWAIN_ACQUIREALL, /* Get all pages */

                       TRUE,  /* Show the UI */

                       TRUE, /* Close Source when UI is closed */

                       &ErrStatus /* Error Status */

                                         );

       /* Check if acquisition worked */

       if ( AcquireArray == NULL )

       /* Didn't work */

              MessageBox(NULL,

                        _T( "TWAIN Acquisition failed!"),

                         _T("TWAIN Error"),

                          MB_ICONSTOP);

        /* End 'if AcquireArray */

       /* Call a function that retrieves all of the DIBs  */

       else

           RetrieveAllDibs( );

        /*                That's it!  The few lines above have just

               cleared up hours (if not days)

               of work getting TWAIN implemented!  */                

       /* Close up shop.  Close all sources,

              TWAIN Sessions, the TWAIN Source Manager, */                

   }  /* End 'if SourceSelected... */

  DTWAIN_SysDestroy( );

/* End the function */

}

/* This function demonstrates the DTWAIN Image Retrieval functions */

void RetrieveAllDibs( )

{                

   DTWAIN_ARRAY aDibs;

   /* Get the number of total acquisitions attempted */

   numAcquisitions = DTWAIN_ArrayGetCount(AcquireArray);

   /* Display a message box as to the number of

       acquisitions attempted */

  wsprintf(szBuf, _T("Number of Acquisitions is %d"), numAcquisitions);

  MessageBox(NULL,szBuf, _T("TWAIN Info"), MB_OK);

   /* Get the number of DIBs (pages) that were

       scanned for each acquisition */

   /* Loop for each acquisition attempted */                

   /* Alternately, the DTWAIN_GetAcquiredImageArray function

   could have been used also to get the array of DIBs */

   for ( Count = 0; Count < numAcquisitions; ++Count )

   {

       DibCount = DTWAIN_GetNumAcquiredImages( AcquireArray, Count);

       /* Loop for each DIB in the acquisition */

       for (Count2 = 0; Count2 < DibCount; ++Count2 )

       {

           /* Retrieve the DIB */

           hDib = DTWAIN_GetAcquiredImage(AcquireArray, Count, Count2);

           if ( hDib )

               /* 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 );

           }/* End for Count2 */

   }        /* End for Count */

} /* End RetrieveAllDibs */

Note that the DIBs are deleted by  the application using the GlobalFree Windows API function.  Your application is responsible for deleting any DIB or image data generated by the Source.  The only exception to this rule is when DTWAIN is doing File Acquisitions.  In this mode, there are no generated DIBs or image data, since these are always saved to a file.