DTWAIN_AcquireFile

Top  Previous  Next

The DTWAIN_AcquireFile starts the image acquisition from a Source and saves the image(s) to file or multiple files

 

DTWAIN_BOOL  DTWAIN_AcquireFile (

DTWAIN SOURCE

Source,

LPCTSTR

FileNames,

LONG

FileType,

LONG

FileControlFlag,

LONG

PixelType,

LONG

NumPages,

DTWAIN_BOOL

bShowUI,

DTWAIN_BOOL

bCloseSource,

LPLONG

pStatus );

 

Parameters

Source

Specifies a selected TWAIN Source.

 

FileNames

Points to a null terminated string denoting the file name(s) or NULL.

 

FileType

Specifies the file format to save the acquired images.

 

FileControlFlag

Specifies user interaction and which transfer mode to use.

 

PixelType

Specifies the pixel type of the image

 

NumPages

Specifies the number of pages to acquire.

 

bShowUI

Specifies whether the Source displays the default User Interface.

 

bCloseSource

Specifies whether the Source should be automatically closed when the User Interface is closed.

 

pStatus

NULL, or is the address of a variable that will be filled in with an error status value.

 

Return Values

If the function succeeds, TRUE is returned.  If the function fails FALSE is returned and pStatus is set to the error that occurred.

 

Character specific version

ANSI version:

DTWAIN_AcquireFileA

Unicode version:

DTWAIN_AcquireFileW

 

Comments

Starts the image acquisition from a TWAIN device and saves the acquired image(s) to a file or multiple files.  The arguments PixelType, Source, NumPages, bShowUI, bCloseSource, and pStatus all have the same definitions as DTWAIN_AcquireNative.

 

If you are attempting to store images with file names that have embedded spaces (for example "C:\Program     Files.BMP"), use DTWAIN_AcquireFileEx instead of DTWAIN_AcquireFile.  If you specify a full path name for the file to save, the directory specified must already exist.  If not, a DTWAIN_TN_FILEPAGESAVEERROR will be generated and sent as a notification to your application.

 

DTWAIN supports the "Acquire To File" mode that some Sources have implemented, as well as a DTWAIN mode that can be used for any Source, even if the Source does not have internal file transfer support.  See the end of this topic for more information on using the DTWAIN internal file support and how to set the FileType argument.

 

 


Here are some examples using DTWAIN_AcquireFile:

 

Acquire all pages to individual BMP files using DTWAIN mode, prompting for a file name:  Native transfer is used:

DTWAIN_AcquireFile( Source, NULL, DTWAIN_BMP,

                                       DTWAIN_USENATIVE + DTWAIN_USEPROMPT,

                                       DTWAIN_PT_DEFAULT, DTWAIN_ACQUIREALL, TRUE, TRUE, NULL);

 

Acquire all pages to a multi-page Group 3 TIFF file using DTWAIN mode, the file name is provided.

DTWAIN_AcquireFile( Source, "image.tif", DTWAIN_TIFFG3MULTI,

                 DTWAIN_USENATIVE + DTWAIN_USENAME,

                                       DTWAIN_PT_BW, DTWAIN_ACQUIREALL, TRUE, TRUE, NULL);

 

Acquire 1 page to an XBM file.  The XBM file is transferred using the Source's internal file transfer support (assume the Source supports XBM transfers).  The name is provided:

DTWAIN_AcquireFile( Source, "image.tif", DTWAIN_FF_XBM,

                 DTWAIN_USESOURCEMODE + DTWAIN_USENAME,

                                       DTWAIN_PT_DEFAULT, 1, TRUE, TRUE, NULL);

 

Acquire 3 pages to a BMP file using DTWAIN mode.  The file names are provided for each file (image1.bmp, image2.bmp, image3.bmp)

DTWAIN_AcquireFile( Source, "image1.bmp image2.bmp image3.bmp", DTWAIN_BMP,

                                       DTWAIN_USENATIVE + DTWAIN_USENAME,

                                       DTWAIN_PT_DEFAULT, 3, TRUE, TRUE, NULL);

 

Acquire 3 pages to a BMP file using DTWAIN mode.  The file names are auto-generated by DTWAIN, given only the first name.

DTWAIN_AcquireFile( Source, "image.bmp", DTWAIN_BMP,

                                       DTWAIN_USENATIVE + DTWAIN_USENAME,

                                       DTWAIN_PT_DEFAULT, 3, TRUE, TRUE, NULL);

 

The last example will create image.bmp, image2.bmp, image3.bmp.

 

The next section describes the parameters and other aspects of using DTWAIN_AcquireFile correctly:


Parameters

 

The File Control flag

The FileControlFlag determines how the image retrieval and file saving mechanism will work. The values for the FileControlFlag are bitwise ORed.  If your language does not have a bitwise OR, the values can be added together to get the same results.

 

The FileControlFlag controls the following:

Whether to use the DTWAIN file transfer support, or use the Source's internal file transfer support
Whether the native or buffered mode will be used to acquire the image(s) if using DTWAIN file transfer support.
The method in which the acquired image files will be named.

 

To control which image transfer mode the Source will use, the FileControlFlag must consist of only one of the following:

 

Transfer Mode

Value        

Defintion

DTWAIN_USENATIVE

1

Use the Native Transfer Mode.

DTWAIN_USEBUFFERED

2

Use the Buffered Transfer Mode                                                                        (uncompressed mode only).

DTWAIN_USESOURCEMODE

32

Use the Source's internal file support.

 

The DTWAIN_USESOURCEMODE flag uses the Source's internal "Acquire To File" support.  There are many Sources that do not have internal support for file acquisitions. Before using this method, see Internal Source File Transfer Issues below.

 

If neither DTWAIN_USENATIVE, DTWAIN_USEBUFFERED nor DTWAIN_USESOURCEMODE is specified in the FileControlFlag, the transfer method is assumed to be DTWAIN_USENATIVE.  If both DTWAIN_USENATIVE and DTWAIN_USEBUFFERED are specified, DTWAIN_USENATIVE is used.

 

To control the way the file names are generated, the FileControlFlag must consist of only one of the following:

 

How to create name

Value

Definition

DTWAIN_USENAME

4        

Use name(s) in FileNames argument.

DTWAIN_USEPROMPT

8

Prompt for the filename(s).  Before using this option, please read Compatibility Issues with DTWAIN_USEPROMPT below.

DTWAIN_USELONGNAME        

16

Same as DTWAIN_USENAME, but generate long file names

 

If DTWAIN_USENAME or DTWAIN_USELONGNAME is specified, the list of names provided by the FileNames argument specifies the names of the files that each acquired page will be saved to.   This argument is a null terminated string denoting a list of filenames separated by either white space (tabs or spaces) commas (,), semicolons (;) or pipes (|).   Here are examples:

"File1.bmp"        

(A single file named File1.bmp)

"File1.bmp File2.bmp File3.bmp"        

(3 files; File1.bmp, File2.bmp, File3.bmp)

"File1.bmp | File2.bmp | File3.bmp"        

(Same as above)

"File1.bmp, File2.bmp, File3.bmp"        

(Same as above)

"File1.bmp; File2.bmp"                

(2 files; File1.bmp, File2.bmp)

 

The DTWAIN_USELONGNAME works exactly the same as DTWAIN_USENAME except that the names specified by FileNames can consist of long file names (names that are longer than the old 8 character name, 3 character extension DOS names).

 

Note: If your file names contain spaces, you should not use DTWAIN_AcquireFile, and instead use DTWAIN_AcquireFileEx.  DTWAIN_AcquireFileEx is equivalent to DTWAIN_AcquireFile, with the exception being that the file names can have embedded spaces (for example "C:\Files  To  Acquire" will not work with DTWAIN_AcquireFile, but will work with DTWAIN_AcquireFileEx).  DTWAIN_AcquireFile recognizes the space as a delimiter between file names, therefore DTWAIN_AcquireFile will not work correctly with file names that have embedded spaces.

 

If DTWAIN_USEPROMPT is specified, the usual Windows "Save As" dialog is displayed for each acquired page (see DTWAIN_SetFileSavePos and DTWAIN_SetCustomFileSave for customization of the "Save As" dialog).  The dialog is displayed only when the image data has been acquired from the Source without error. If DTWAIN_USEPROMPT is combined with any of the other file saving methods, DTWAIN_USEPROMPT is always assumed.  For languages that do not have a Boolean OR available (the '|' operator in C or C++), the language can merely add the values to get the final FileControlFlag value.  For example,

 

DTWAIN_USEPROMPT + DTWAIN_USENATIVE is equivalent to

DTWAIN_USEPROMPT | DTWAIN_USENATIVE

 

 

The FileType value

 

If the application desires to use the DTWAIN mode for file transfers, the FileType argument determines what file format the image will be saved in.  This value can be equal to one of the DTWAIN File Transfer Constants.

 

Note that if you are calling DTWAIN_AcquireFile or DTWAIN_AcquireFileEx and are not using the Source's internal file transfer support (DTWAIN_USESOURCEMODE is not set in FileControlFlag), DTWAIN internally uses Native or Buffered transfer types to retrieve the Device Independent Bitmap(s) (DIB), and subsequentally saves the DIBs to the file type specified below.  This means that the DIB must have the proper bit-depth, or bits-per-pixel before it can be saved to the proper format.

 

Note:

If acquiring images with no user interface, it is highly recommended that your application calls DTWAIN_SetPixelType( ) and/or DTWAIN_SetBitDepth( ) to ensure that the Source will be creating images with the proper pixel type and bit depth.

 

Below is a table describing the valid bit-depths for each file type:

File Type

Bit Depth (Bits-Per-Pixel)



BMP        

Any bit depth

JPEG                        

8, 16, or 24

JPEG-2000

8, 16, or 24

*PCX        

1, 8 or 24

TGA                        

8 or 24

*TIFF No compression        

1, 4, 8, 16, or 24

*TIFF Group 3 Fax

1

*TIFF Group 4 Fax

1

*TIFF PackBits

1, 4, 8, 16, or 24

*TIFF Deflate        

1, 4, 8, 16, or 24

*TIFF LZW Compression

1, 4, 8, 16, or 24

*TIFF JPEG Compression

8, 16, 24

Windows Metafile (WMF)

24

Enhanced Metafile (EMF)

24

GIF

1, 8

PNG                        

1, 8, 16, 24

Adobe PSD                

24

*Adobe PDF

1, 8, 16, 24

*Adobe PostScript

1, 8, 16, 24

**Windows Icon (ICO )

1, 8, 16, 24

***Wireless Bitmap (WBMP)

1

****Text

Not Applicable

 

* Value apply to single page and multi-page varieties of these file types.

 

** Non-Vista Windows ICON files cannot have a bitmap width or height greater than 255 pixels.
 
*** Wireless Bitmaps must be 1 bit-per-pixel, and cannot have width or height greater than 255 pixels.
 

**** The Text format is only available if one of the supported OCR engines is installed.  In addition, the Text format is available as a multi-page type only if the OCR engine supports multi-page text files.

 

The Adobe PDF and PostScript formats are available only with the DTWAIN / PDF support code, which is available separately from the base DTWAIN DLL.

 

Special Note:  The saving of Adobe PDF and PostScript files requires a writeable and accessible temporary directory.  If you are attempting to acquire PDF / PostScript files, and have errors in creating the file, make sure that your temporary directory (usually C:\TEMP, please check your System settings) is writeable and accessible from the computer running the application.

 

Also, PDF / PostScript creation requires that your acquired images are 1, 8, 16, or 24 bit images.  If they are any other bit-depth, the PDF / PostScript creation will fail, or the PDF file will not be created correctly.

 

Currently, DTWAIN does not convert the DIBs to the proper bits-per-pixel if the DIB has the incorrect bit depth for a certain file type.  For example, if the Source acquires to a 24-bit DIB, there is currently no way for DTWAIN to save the DIB to a TIFF Group 3 Fax format.  For situations where the bit depth has to be reduced (or increased), it is recommended to use third-party imaging code that can increase or reduce bit depth to the desired level and instead call DTWAIN_AcquireNative or DTWAIN_AcquireBuffered to handle the DIBs.  In a future version of DTWAIN, this problem will most likely be remedied by doing bit-depth reduction or increasing the bit-depth of the acquired image to match the valid bit-per-pixel value.

 

If there is a problem creating the file, call DTWAIN_GetLastError to get the error code.

 


Internal Source File Transfer Issues

Before an application attempts to use this method (when the FileControlFlag has DTWAIN_USESOURCEMODE set), the application should call DTWAIN_IsFileXferSupported to determine whether the Source can support file transfers.  The application should also call DTWAIN_EnumFileXferFormats to determine the file types supported.  If the application desires to use the internal file transfer support of the Source, the FileType argument denotes one of the following values found in the DTWAIN File Transfer Contents (Source Internal File Support) Any value that is retrieved from DTWAIN_EnumFileXferFormats can be used for FileType.

 

When calling DTWAIN_AcquireFile or DTWAIN_AcquireFileEx and specifying the DTWAIN_USESOURCEMODE flag, the Source is responsible for the file transfer, and DTWAIN provides no other support except to initiate the transfer.  Problems with improper files being generated, incorrect bitmaps, etc. are not the responsibility of DTWAIN when specifying DTWAIN_USESOURCEMODE.

 


Job Control

If job control is used, where each acquisition job (a set of pages) is separated by a patch code (or job separator sheet), DTWAIN has the ability to save each job as a single multipage image file.  To turn on job control, a) the device must support job control, b) the DTWAIN_SetJobControl( ) function must be called with a value other than DTWAIN_JC_NONE, and c) DTWAIN_EnableJobFileHandling must be called with a TRUE argument.

 

Since pages and jobs are interchangeable in describing the file naming conventions (see below), the description will contain phrases such as "page/job" or "pages/jobs".


 

Multiple Page Image Retrieval

If your device can acquire more than one page per acquisition (for example, a scanner equipped with a document feeder), DTWAIN supports saving all the pages acquired to a multi-page TIFF, DCX, PDF, or PostScript file.  However, if a single page file type is used (for example, BMP, PNG, PSD, JPEG, single page TIFF files, etc.), there can be multiple pages being acquired where each page will be saved to a separate file.

 

When acquiring more than one page/job when DTWAIN_AcquireFile is called, DTWAIN has special rules as to what the filenames should be for each page/job.  If you are acquiring images using an automatic document feeder, the file names for the FileControlFlag parameter are handled with the following rules:

 

If the DTWAIN_USEPROMPT option is used, the Windows File Save dialog box will appear after every new page (or job if job control is used) is retrieved.  This technique allows you to name your pages/jobs "on the fly".  The drawback is that the retrieval is paused when the file dialog window is displayed, and the retrieval won't continue until the user enters a name.  This means that if you are scanning 50 pages/jobs, you will have to sit through 50 File Save dialog boxes.

 

If the DTWAIN_USENAME option is used, the names found in the FileNames parameter will be used for each page/job.  When writing to a file using DTWAIN_USENAME or DTWAIN_USELONGNAME, DTWAIN will not check if the file already exists, and will overwrite any existing file.  If the existing file is read-only or it cannot be deleted, DTWAIN will skip over this file (since there was a creation error) and continue with the next page/job.

 


 

File Naming when images acquired exceeds the number of file names specified

There are two methods of file naming done for DTWAIN_AcquireFile if the number of images (or jobs) acquired exceeds the number of names defined in the FileNames argument.

 

File naming using DTWAIN_SetFileAutoIncrement

The DTWAIN_SetFileAutoIncrement function sets the "auto-incrementing" feature of DTWAIN file naming.  This is discussed in depth in the DTWAIN_SetFileAutoIncrement topic.

 

File naming without using DTWAIN_SetFileAutoIncrement

This option allows you to set up all of the names for each page or job prior to actually retrieving the data.  When the retrieval starts, the first name found in FileNames is used as the file name for the first page/job, the second name found in FileNames is used for the second page/job, etc.  If the number of names found in FileNames are less than the number of acquired pages/jobs, the files are named using the page number (job number) as the suffix for the file name.  For example if there are 2 names in FileNames named SCAN.BMP and SCANTWO.BMP respectively, and there are three pages that are acquired, the names of the files are SCAN.BMP, SCANTWO.BMP, and SCANTWO3.BMP.

 

If the DTWAIN_USELONGNAME is used along with one of the above options, DTWAIN will generate a long file name if the new name exceeds the DOS 8.3 filename naming convention.  If this option is not used, DTWAIN always tries to fit the page number within the 8.3 limit.   For example, if DTWAIN has to create a file based on the second page acquired, and the base file name 'DTWAINSCAN.BMP' is used, the DTWAIN_USELONGNAME option will create the name 'DTWAINSCAN2.BMP'.  If the option is not used, the name 'DTWAINS2.BMP' is created.

 


Changing the file name during acquisition

There may be situations where you want to control the naming of each image file after the image has been acquired, but has not yet been saved.  To do this, your application must trap the DTWAIN notification DTWAIN_TN_FILENAMECHANGING.  During this notification, the application can call DTWAIN_GetSaveFileName to retrieve the name of the file that will be saved, and DTWAIN_SetSaveFileName to set the file name to a different name.

 


Error Processing

Most file related errors are sent as notifications to your application.  DTWAIN_AcquireFile will always return TRUE if the TWAIN device acquires the image successfully, even if the file has not been saved for some reason.  If you want to see if any errors occurred during the file saving process, you must process notifications and check if the following notifications are sent:

 

DTWAIN_TN_FILEPAGESAVEERROR

DTWAIN_TN_FILEPAGESAVEOK

DTWAIN_TN_FILESAVEOK

 

These codes are discussed in the notification code section.


Compatibility Issues with DTWAIN_USEPROMPT

When specifying DTWAIN_USEPROMPT for some Sources, The Windows "Save As" dialog box may hang.  This is because some Source's are intercepting messages that the dialog box needs to operate correctly.  For these Sources, the only workaround is to either not use DTWAIN_USEPROMPT and specify the filenames, or your application can display the "Save As" dialog before calling DTWAIN_AcquireFile or DTWAIN_AcquireFileEx to get the name to be used.

 

Depending on the language, there are various ways to display your own "Save As" dialog.  For general purposes, the Windows API function GetSaveFileName is used to display the dialog.  Please consult your programmer's reference for more information.


 

TWAIN State Transitions

State 4 (if Source is not opened)

State 5, 6, 7

State 4 (if Source is closed after acquisitions)

 

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN Source Selection Function

 

See Also

Acquiring Images