DTWAIN_SetMultipageScanMode
|
The DTWAIN_SetMultipageScanMode function allows saving to a single multipage image file from multiple acquisitions, and control when acquired pages are written to a multipage file.
DTWAIN_BOOL DTWAIN_SetMultipageScanMode (
Parameters Source A DTWAIN_SOURCE denoting a TWAIN Source.
FileMode Sets when the images acquired will be saved to a file.
Return Values The return value is TRUE if successful. Otherwise FALSE is returned.
Comments The DTWAIN_SetMultipageScanMode function allows an application to save acquired pages to a single image file when either the TWAIN Source is closed or the user interface of the device is closed. This function is only applicable when calling DTWAIN_AcquireFile or DTWAIN_AcquireFileEx, and the image format of the file to save is a multipage TIFF, DCX, PDF, or PostScript file. In addition, DTWAIN_SetMultipageScanMode allows saving image file if the acquisition has been canceled (either by the user, application, or TWAIN driver) or has failed.
By default, acquiring multiple pages from the TWAIN device immediately saves the acquired pages to a multipage image file. However, this can be overridden, and the application can save the acquired images to a multipage file at any time that the Source is opened, or when the user interface is displayed. This allows devices that can only acquire one page at a time (for example, a flatbed scanner) to save multiple pages to a single file. For example, the user may scan 10 pages using the flatbed portion of a scanner, and all 10 pages will be saved to a single multipage file.
Also by default, DTWAIN will not save image files if the acquisition has been canceled by the user, application, or TWAIN driver. This can also be overridden by DTWAIN_SetMultipageScanMode.
The Source is the DTWAIN_SOURCE that will be used when setting the mode. The FileMode must be only one of the following:
DTWAIN_FILESAVE_DEFAULT DTWAIN_FILESAVE_UICLOSE DTWAIN_FILESAVE_SOURCECLOSE DTWAIN_FILESAVE_MANUALSAVE
In addition to the constants above, the following value can be added (boolean-ORed) to the constants above:
DTWAIN_FILESAVE_SAVEINCOMPLETE
The DTWAIN_FILESAVE_DEFAULT option simply sets the mode of operation to the default, i.e. for a single acquisition, a set of pages will be automatically saved to an image file once those pages have been acquired. DTWAIN_FILESAVE_DEFAULT is the default setting.
The DTWAIN_FILESAVE_UICLOSE option saves the images when the user interface to the TWAIN device has been closed, or when the DTWAIN_FlushAcquiredPages function has been called, whichever occurs first. This option allows an application to continuously acquire images and only save when the user (or application) closes the user interface.
The DTWAIN_FILESAVE_SOURCECLOSE option saves the images when the TWAIN Source has been closed. This option allows an application to continuously acquire images and only save to a multipage file when the Source has closed, or when the DTWAIN_FlushAcquiredPages function is called, whichever occurs first. Note that even though the user interface may be closed, the TWAIN Source can still remain opened.
The DTWAIN_FILESAVE_MANUALSAVE option saves the images only if the application calls DTWAIN_FlushAcquiredPages. This allows the program to control exactly when the file save will occur, and even if a file save will be attempted. If the TWAIN Source is closed before DTWAIN_FlushAcquiredPages is called, all temporary files are removed from the disk, and no file save will occur.
For DTWAIN_FILESAVE_UICLOSE, DTWAIN_FILESAVE_SOURCECLOSE, and DTWAIN_FILESAVE_MANUALSAVE, an application at anytime the images have not been saved, can issue a call to DTWAIN_FlushAcquiredPages. The DTWAIN_FlushAcquiredPages function saves the previously acquired pages to the multipage file. Once this is done, the multipage image file cannot be appended to, and any attempts to save to the image file will overwrite the current contents of the file.
Note: When acquiring using the DTWAIN_FILESAVE_UICLOSE, DTWAIN_FILESAVE_SOURCECLOSE, and DTWAIN_FILESAVE_MANUALSAVE modes, temporary files are generated and kept until the final multipage image file has been created. The temporary files are saved to the directory specified by your Windows TEMP directory, or the directory specified in the call to DTWAIN_SetTempFileDirectory. Once the multipage file has been saved, the temporary image files are deleted. If you are planning on acquiring many pages, make sure that you have the necessary disk space for storing the temporary files.
The DTWAIN_FILESAVE_SAVEINCOMPLETE option allows saving of multipage image files if the acquisition is canceled or fails. By default, DTWAIN does not save multipage image files if the acquisition has been canceled or fails. The DTWAIN_FILESAVE_SAVEINCOMPLETE option can be used with any of the other options by combining (adding) the DTWAIN_FILESAVE_SAVEINCOMPLETE. For example:
DTWAIN_SetMultipageScanMode( Source, DTWAIN_FILESAVE_DEFAULT + DTWAIN_FILESAVE_SAVEINCOMPLETE);
The DTWAIN_FILESAVE_SAVEINCOMPLETE is the only option that can be combined with other file saving options.
The file format specified in the last executed call to DTWAIN_AcquireFile or DTWAIN_AcquireFileEx that used Source as the TWAIN Source will be the format used when the pages are saved to a multipage image file.
If images are pending to be saved, and DTWAIN_SetMultipageScanMode is called with FileMode equal to DTWAIN_FILESAVE_DEFAULT, the pending images are saved to the file specified by the previous call to DTWAIN_AcquireFile or DTWAIN_AcquireFileEx.
TWAIN State Transitions None
Prerequisite Function Call(s) DTWAIN Source Selection Function
See Also |