DTwainAcquirer::Acquire

Syntax:

bool    Acquire( );

bool    Acquire(const std::string& sFileName, DTwainFileType AcquireType=FILETYPE_BMP);

bool    Acquire(const DTwainStringArray& sFileNames, DTwainFileType AcquireType=FILETYPE_BMP);

bool    Acquire(DTwainBufferedTransfer& BT);

bool    Acquire(DTwainSourceFileTransfer& FT, const std::string& sFileName);

bool    Acquire(DTwainSourceFileTransfer& FT, const DTwainStringArray& sFileNames);

Return Value

Returns true if successful, false otherwise.

Comments

The DTwainAcquirer::Acquire function starts the acquisition process.

There are six ways to call the DTwainAcquirer::Acquire function.  Below are descriptions of each of these ways that the function is called:

Acquire( );

This acquires a file using native, buffered, or clipboard mode, or if the Source supports "UI-Only mode".  The DTwainAcquirer::SetAcquireType( ) function determines whether native, buffered, clipboard or UI-Only mode is chosen.  This version of DTwainAcquire::Acquire( ) will not create image files, it will only transfer the image data to memory, and later can be  retrieved by the application using DTwainAcquirer::GetAllAcquisitions( ) (see Example 4).  To create image files, use the other versions of Acquire( ) described below.

Acquire( const std::string& sFileName, DTwainFileType FileTypeType );

Acquires to a file using DTWAIN file mode.  The first parameter, sFileName, is the name of the file to save the image(s).  The FileType argument is the file format to use when saving the image(s).  By default, FileType is FILETYPE_BMP (Windows BMP).

FileType can be one of the following:

For multi-page TIFF, PCX (DCX), and PDF/Postscript types, the DTwainAcquirer::SetMultiPageFileMode( ) determines whether multiple pages will be acquired to a single image file.

By default, acquiring to a file will internally use native mode transfer to acquire image(s) from the device before saving them to a file.  If you desire to change this to buffered transfer, the DTwainAcquirer::SetAcquireType( ) should be called with TWAIN_ACQUIREBUFFEREDFILE as the acquire type.

The rules when acquiring more than one page for single page formats are the same as DTWAIN_AcquireFile. See the main help manual and DTWAIN_AcquireFile for these rules.

Acquire(const DTwainStringArray& sFileNames, DTwainFileType FileType Type=FILETYPE_BMP);

This version is the same as Acquire(const std::string& sFileName, DTwainFileType FileTypeType), except that the file names are stored in a DTwainStringArray.  The names in the DTwainStringArray will correspond with each image that is acquired.  For more information, see DTWAIN_AcquireFileEx in the main DTWAIN help manual.

Acquire(DTwainBufferedTransfer& BT);

This version is specialized to acquire using the buffered mode, but with more control over compression types, buffer strip sizes, and many other aspects that are contained in the DTwainBufferedTransfer class denoted by BT.  If you require full control over buffered transfers, use this version of Acquire instead of the 0-argument version of Acquire( ) (see Example 7).  This version of Acquire( ) will also by default save the raw image data to a file (see Example 13 - High speed scanning).

Acquire(DTwainSourceFileTransfer& FT, const std::string& sFileName);

This version acquires using the Twain driver's file mode (as opposed to DTWAIN's file support).  The DTwainSourceFileTransfer type is used to denote the file type to use.  The sFileName argument is the name of the file to acquire.  Again, rules of multiple pages and file names are the same as described in the main help manual's DTWAIN_AcquireFile function.

Acquire(DTwainSourceFileTransfer& FT, const DTwainStringArray& sFileNames);

This version is identical to the other version of Acquire that takes a DTwainSourceFileTransfer argument..  The sFileNames argument is a DTwainStringArray of the file names to use for each page acquired.