DTWAIN_AcquireFile

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

DTWAIN SOURCE	Source,
LPCTSTR	FileNames,
LONG	FileType,
LONG	FileControlFlag,
LONG	PixelType,
LONG	NumPages,
DTWAIN_BOOL	bShowUI,
DTWAIN_BOOL	bCloseSource,
LPLONG	pStatus );

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

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

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

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.

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

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

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:

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

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

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

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.

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,

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.

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.

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

** 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.

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.

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".

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:

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.

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

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.

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.

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:

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.