LTwain::Acquire

Summary

Acquires one or more images from a TWAIN source.

Syntax

virtual L_INT LTwain::Acquire (pBitmap, uStructSize, uFlags, lpszTemplateFile)

virtual L_INT LTwain::Acquire (Bitmap, uStructSize, uFlags, lpszTemplateFile)

Parameters

pBITMAPHANDLE pBitmap

Pointer to the bitmap handle that references the last bitmap acquired from the TWAIN source.

LBitmap * Bitmap

Pointer to an LBitmap object that references the last bitmap acquired from the TWAIN source.

L_UINT uStructSize

Size of the BITMAPHANDLE structure pointed to by pBitmap, in bytes, for versioning. Use sizeof(BITMAPHANDLE).

L_UINT uFlags

Flag that indicates whether to display the manufacturer's user interface. Possible values are:

L_TCHAR * lpszTemplateFile

Character string that contains the name of the template file in which the TWAIN source capability settings will be saved. If this parameter is NULL, the TWAIN capability settings used will not be saved to a template file. For more information on determining/setting the capabilities for a TWAIN source, refer to Getting and Setting Capabilities.

Returns

Comments

When acquiring multiple pages, the LTwain::BitmapCallBack function receives the scanned images through the pBitmap parameter. The user can then process these images as desired within the callback function.

When acquiring a single page, pass NULL for the pfnCallBack parameter. The pBitmap is updated with the single scanned image.

The number of pages to acquire can be determined by getting the TWAIN source's capabilities. To change the number of pages to acquire, set the appropriate capability to the desired number.

To cancel the acquire operation, call LTwain::CancelAcquire from within the LTwain::BitmapCallBack function when it is fired.

To stop acquiring images only from the feeder of the TWAIN source, call LTwain::StopFeede from within the LTwain::BitmapCallBack function when it is fired.

When scanning multiple pages or multiple areas in memory transfer mode, use the LTWAIN_MEMORY_CHECK_IMAGEINFO flag to let the function check the image information for each page or area before beginning to pend the image data to the application. Some TWAIN drivers do not support image information checking: passing this flag has no effect on the function. The usage of the flag does not follow the TWAIN specification, but is included as a work-around for TWAIN drivers that scan multiple pages having different image dimensions. Use this flag only to such special and unusual cases.

In order to use LTWAIN_IMAGESIZE_UNDEFINED flag, before calling LTwain::Acquire be sure to set the ICAP_XFERMECH capability to TWSX_MEMORY and then set ICAP_UNDEFINEDIMAGESIZE capability to TRUE. LTwain::Acquire returns an error if these have not been set correctly.

The LTWAIN_KEEPOPEN flag works only in the following cases:

1. Passed with the LTWAIN_SHOW_USER_INTERFACE flag to make TWAIN user-interface appear as a modeless dialog. The TWAIN data source remains open after scanning until the user closes it.
2. Passed with the LTWAIN_SHOW_USER_INTERFACE and LTWAIN_MODAL_USER_INTERFACE flags to make the TWAIN user-interface appear as a modal dialog. The TWAIN data source remains open after scanning until the user closes it.

Required DLLs and Libraries

• LTTWN
• For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

See Also

Functions

• LTwain::BitmapCallBack
• LTwain::AcquireList
• LTwain::InitSession
• LTwain::EndSession
• LTwain::OpenTemplateFile
• LTwain::CloseTemplateFile
• LTwain::TemplateDlg
• LTwain::AddCapabilityToFile
• LTwain::GetNumofCapsInFile
• LTwain::GetCapabilityFromFile
• LTwain::StopFeeder.

Topics

• How to Acquire from the TWAIN Source
• TWAIN Functionality: Property Functions

Example

class CMyTwainA : public LTwain 
{ 
public: 
   L_INT BitmapCallBack(pBITMAPHANDLE pBitmap); 
   HTWAINTEMPLATEFILE m_hFile; 
}; 
 
L_INT CMyTwainA::BitmapCallBack(pBITMAPHANDLE pBitmap) 
{ 
   UNREFERENCED_PARAMETER(pBitmap); 
 
   // You can do here any processing to the bitmap 
   return SUCCESS; 
} 
 
// initialize session and call this function  
L_INT LTwain__AcquireExample(pBITMAPHANDLE pBitmap, HWND hWnd)  
 
{ 
   UNREFERENCED_PARAMETER(hWnd); 
 
   L_INT          nRet;  
   TW_CAPABILITY  twCap; 
   CMyTwainA       MyClass; 
   APPLICATIONDATA   AppData; 
 
   AppData.hWnd = hWnd;  
   AppData.uStructSize = sizeof(APPLICATIONDATA); 
   lstrcpy (AppData.szManufacturerName, TEXT("LEAD Technologies, Inc."));  
   lstrcpy (AppData.szAppProductFamily, TEXT("LEAD Test Applications")); 
   lstrcpy (AppData.szVersionInfo, TEXT("Version 1.0")); 
   lstrcpy (AppData.szAppName, TEXT("TWAIN Test Application")); 
   AppData.uLanguage = TWLG_ENGLISH_USA; 
   AppData.uCountry = TWCY_USA; 
 
   nRet=MyClass.InitSession(&AppData);  
   if(nRet != SUCCESS) 
      return nRet; 
       
   // Show the Twain Select Source UI 
      
   nRet = MyClass.SelectSource(NULL); 
 
   if (nRet != SUCCESS)  
   { 
 
      MessageBox (NULL, TEXT("Error occurred while selecting the source."), TEXT("ERROR"), MB_OK);  
 
      return nRet; 
 
   } 
 
 
   twCap.Cap = ICAP_XFERMECH;  
 
   twCap.ConType = TWON_ONEVALUE; 
 
 
   nRet = MyClass.CreateNumericContainerOneValue(&twCap, TWAINNUMERICTYPE_TW_UINT16, TWSX_NATIVE); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   nRet = MyClass.SetCapability( &twCap, LTWAIN_CAPABILITY_SET); 
   if(nRet != SUCCESS) 
      return nRet; 
 
   nRet = MyClass.FreeContainer(&twCap); 
   if(nRet != SUCCESS) 
      return nRet; 
 
  MyClass.EnableCallBack (TRUE); 
 
   nRet = MyClass.Acquire( pBitmap, sizeof(BITMAPHANDLE), LTWAIN_SHOW_USER_INTERFACE, NULL);  
 
   if (nRet == SUCCESS) 
 
      MessageBox(NULL, TEXT("The image acquisition process completed."), TEXT("Notice"), MB_OK); 
 
   else 
 
      MessageBox(NULL, TEXT(" The image acquisition process failed!"), TEXT("Error"), MB_OK); 
 
   nRet=MyClass.EndSession();  
   if(nRet != SUCCESS) 
      return nRet; 
 
   return nRet; 
}