#include "lttwn.h"

L_LTTWN_API L_INT L_TwainAcquire (hSession, pBitmap, uStructSize, pfnCallBack, uFlags, lpszTemplateFile, pUserData)


handle to an existing TWAIN session


pointer to the bitmap handle

L_UINT uStructSize;

size in bytes, of the structure pointed to by pBitmap


callback function

L_UINT uFlags;

optional flags

L_TCHAR * lpszTemplateFile;

template file name

L_VOID * pUserData;

pointer to more parameters for the callback

Acquires one or more images from a TWAIN source.

Parameter Description
hSession Handle to an existing TWAIN session. This handle is obtained by calling the L_TwainInitSession or L_TwainInitSession2 function.
pBitmap Pointer to the bitmap handle that references the last bitmap acquired from the TWAIN source.
uStructSize Size in bytes, of the structure pointed to by pBitmap, for versioning. Use sizeof(BITMAPHANDLE).
pfnCallBack Optional callback function for multipage scanning. Use NULL as the value of this parameter if you are processing only one image. If you provide a callback function, use the function pointer as the value of this parameter.
  L_TwainAcquire calls this callback function as it acquires each page into the bitmap. The callback function must adhere to the following function prototype: LTWAINBITMAPCALLBACK.
uFlags Flag that determines certain actions of the TWAIN source. Possible values are:
  Value Meaning
  0 Do not show the manufacturer's user interface.
  LTWAIN_SHOW_USER_INTERFACE [0x0001] Shows the manufacturer's user interface as modeless.
  LTWAIN_MODAL_USER_INTERFACE [0x0002] Shows the manufacturer's user interface as a modal dialog. Works only if the LTWAIN_SHOW_USER_INTERFACE flag is set.
  LTWAIN_BITMAP_TYPE_DISK [0x0004] Do not use conventional memory. Swap to disk only.
  LTWAIN_KEEPOPEN [0x0020] Keep the TWAIN data source open after scanning. This flag should only be used in conjunction with LTWAIN_SHOW_USER_INTERFACE.
  LTWAIN_MEMORY_CHECK_IMAGEINFO [0x0040] Check image information while scanning multi pages with different dimensions. This flag is used only with memory transfer mode.  It will not affect native and file transfer modes.
  LTWAIN_IMAGESIZE_UNDEFINED [0x0080] Calculate the acquired image size after the image is acquired.  This flag is used only with memory transfer mode.
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.
pUserData Void pointer that you can use to pass one or more additional parameters that the callback function needs.
  To use this feature, assign a value to a variable or create a structure that contains as many fields as you need. Then, in this parameter, pass the address of the variable or structure, casting it to L_VOID *. The callback function, which receives the address in its own pUserData parameter, can cast it to a pointer of the appropriate data type to access your variable or structure.
  If the additional parameters are not needed, you can pass NULL in this parameter.



The function was successful.


An error occurred. Refer to Return Codes.


When acquiring multiple pages, the LTWAINBITMAPCALLBACK callback 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 the L_TwainCancelAcquire from within the LTWAINBITMAPCALLBACK callback function.

To stop acquiring images only from the feeder of the TWAIN source, call the L_TwainStopFeeder function from within the LTWAINBITMAPCALLBACK callback function.

When scanning multi pages or multi areas with memory transfer mode, you may use LTWAIN_MEMORY_CHECK_IMAGEINFO flag to let the function check the image information for each page or area before start pending the image data to application. Some TWAIN drivers do not support image information checking, so passing this flag has no effect on the function.

The usage of the flag does not follow the TWAIN specification, but is included as work around for TWAIN drivers that scan multiple pages with different image dimensions. The usage of this flag should be limited only to these special and unusual cases.

In order to use LTWAIN_IMAGESIZE_UNDEFINED flag, you should set ICAP_XFERMECH capability to TWSX_MEMORY and then set ICAP_UNDEFINEDIMAGESIZE capability to TRUE, before calling this function, otherwise, it will return an error.

The LTWAIN_KEEPOPEN flag works only in the following cases:


Passed with LTWAIN_SHOW_USER_INTERFACE flag to make the TWAIN user-interface appears as a modeless dialog. The TWAIN data source remains open after scanning until the user closes it.


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

Required DLLs and Libraries


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


L_TwainAcquireList, L_TwainInitSession, L_TwainEndSession, L_TwainOpenTemplateFile, L_TwainCloseTemplateFile, L_TwainTemplateDlg, L_TwainAddCapabilityToFile, L_TwainGetNumofCapsInFile, L_TwainGetCapabilityFromFile, L_TwainCancelAcquire, L_TwainStopFeeder


How to Acquire from the TWAIN Source


TWAIN Functionality: Property Functions.


L_VOID     * pUserData) 
   // You can do here any processing to the bitmap 
   return SUCCESS; 
L_INT TwainAcquireExample(pBITMAPHANDLE pBitmap, HTWAINSESSION g_hSession) 
   L_INT nRet; 
   // Show the Twain Select Source UI 
   nRet = L_TwainSelectSource(g_hSession, NULL); 
   if (nRet != SUCCESS) 
      MessageBox (NULL, TEXT("Error occurred while selecting the source."),TEXT( "ERROR"), MB_OK); 
      return nRet; 
   nRet = L_TwainStartCapsNeg(g_hSession); 
   if(nRet != SUCCESS) 
      return nRet; 
   twCap.Cap = ICAP_XFERMECH; 
   twCap.ConType = TWON_ONEVALUE; 
   nRet = L_TwainCreateNumericContainerOneValue(&twCap, TWAINNUMERICTYPE_TW_UINT16, TWSX_NATIVE); 
   if(nRet != SUCCESS) 
      return nRet; 
   nRet = L_TwainSetCapability(g_hSession, &twCap, LTWAIN_CAPABILITY_SET); 
   if(nRet != SUCCESS) 
      return nRet; 
   nRet = L_TwainFreeContainer(&twCap); 
   if(nRet != SUCCESS) 
      return nRet; 
   nRet = L_TwainEndCapsNeg(g_hSession); 
   if(nRet != SUCCESS) 
      return nRet; 
   nRet = L_TwainAcquire(g_hSession, pBitmap, sizeof(BITMAPHANDLE), BmpCB, LTWAIN_SHOW_USER_INTERFACE, NULL, NULL); 
   if (nRet == SUCCESS) 
      MessageBox(NULL, TEXT("The image acquisition process completed."), TEXT("Notice"), MB_OK); 
      MessageBox(NULL, TEXT(" The image acquisition process failed!"), TEXT("Error"), MB_OK); 
      return nRet; 
   return SUCCESS; 

Help Version 19.0.2017.10.27
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.