DTWAIN_AcquireFile
|
The DTWAIN_AcquireFile starts the image acquisition from a Source and saves the image(s) to file or multiple files
DTWAIN_BOOL DTWAIN_AcquireFile (
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
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:
To control which image transfer mode the Source will use, the FileControlFlag must consist of only one of the following:
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:
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:
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 If DTWAIN_CREATE_DIRECTORY is used, a file directory is created that matches the parent path of the file name that is given. By default, a non-existing directory will fail to create the image file. For example: DTWAIN_AcquireFile( Source, "c:\\abc\\123\\image.tif", DTWAIN_TIFFG3MULTI, DTWAIN_USENATIVE + DTWAIN_USENAME + DTWAIN_CREATE_DIRECTORY, DTWAIN_PT_BW, DTWAIN_ACQUIREALL, TRUE, TRUE, NULL);
will create the directory "c:\abc\123" if it does not exist. 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:
* 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. **** 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.
Internally, DTWAIN will 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, the DIB will be converted to a 1-bit-per-pixel DIB if the image file format is TIFF Group 3 Fax format.
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:
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.
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.
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 4 (if Source is closed after acquisitions)
Prerequisite Function Call(s) DTWAIN Source Selection Function
See Also
|