LWia::AcquireToFile

Summary

Acquires one or more images from a WIA source and saves them directly to file(s).

Syntax

virtual L_INT LWia::AcquireToFile(uFlags, pSourceItem, pAcquireOptions, pnFilesCount, pppszFilePaths)

Parameters

L_UINT32 uFlags

Flag that determines certain actions of the WIA image acquisition selection dialog box. Possible values are:

L_VOID * pSourceItem

Pointer to the scanner's paper source (either Feeder or Flatbed).

This parameter is only used if both of the following conditions are true:

• A scanner device is being used for image acquisition
• The L_WIA_SHOW_USER_INTERFACE flag is NOT set

WIA 1.0

If WIA 1.0 is being used, pSourceItem is optional. Three different methods can be used to specify the scanner's paper source:

• Use [LWia:AcquireToFile and set the pSourceItem parameter (this method). The device must be a scanner, and the L_WIA_SHOW_USER_INTERFACE flag must NOT be set.
• Change the WIA_DPS_DOCUMENT_HANDLING_SELECT property for the root item.
• Enumerate the available scanner items, and pass the item to be used for scanning.

WIA 2.0

If WIA 2.0 is being used, there are two different methods that can be used:

• Enumerate the available scanner items, and pass the item to be used for scanning.
• Pass NULL. The enumeration will be performed internally and the first enumerated item will be used as the source item.

pLWIAACQUIREOPTIONS pAcquireOptions

Pointer to an optional pLWIAACQUIREOPTIONS structure that specifies how acquisition will behave. Pass NULL to use the internal default values.

L_INT * pnFilesCount

Pointer to a variable of type L_INT to be updated with the number of files saved.

L_TCHAR *** pppszFilePaths

Pointer to string buffer to hold an array of the saved file paths. Used when the transfer mode is file. To use the pppszFilePaths parameter, define a variable of type L_TCHAR** of size zero and pass the address of that variable to the acquire function.

It is the user's responsibility to free the received file name array.

Returns

Comments

This feature is available in LEADTOOLS version 16 or higher.

Use [LWia:AcquireToFile to acquire single or multiple images from the selected WIA device.

Make sure to call LWia::InitSession and then call any of the LWia::SelectDeviceDlg or LWia::SelectDevice functions before calling this function.

Specify the parent window for the image acquisition dialog by calling the LScanner::SetWindow function.

This function will use the file transfer mode to acquire page(s) and save them directly to the hard disk using file name specified in the szFileName member of the LWIAACQUIREOPTIONS structure. If you are acquiring more than one page with the bSaveToOneFile member of the LWIAACQUIREOPTIONS structure set to FALSE, the WIA toolkit will automatically rename the saved files by adding (N) (where N is an incremented number generated to ensure that a file with the same name exists in the same path).

Since the file transfer mode is being used, overriding the LWia::AcquireFileCallback is optional (the callback will only be providing the saved file path and the percent completion of the file save process).

To cancel the acquire operation you need to override the LWia::AcquireFileCallBack function and return ERROR_USER_ABORT error code.

Note When using the L_WIA_SHOW_USER_INTERFACE flag, be aware of the following points:

Microsoft's Image Acquisition dialog box sets its own initialization properties like the current intent (image type), selected area (left, top, width and height), paper source and duplex mode, etc.

Some of the previously set/changed user properties using any of the LWia::SetPropertyXXX or LWia::SetProperties functions will be overwritten by the Microsofts image acquisition dialog box, since this dialog sets its own initialization properties like the current intent (image type), selected area (left, top, width and height), paper source and duplex mode, etc.

So if the user wants to keep his changed properties then he should not set this flag to suppress the manufacturer's image acquisition dialog and acquire directly from the specified source item.

Note: While running a Win32 version application that calls this function while specifying the pnFilesCount and pppszFilePaths parameters on Windows VISTA 64-Bit we have noticed that these two members will not be filled back with the required information and this is a known limitation from Microsofts WIA toolkit side.

Required DLLs and Libraries

• LTWIA
• 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

• LWia::Acquire
• LWia::AcquireSimple
• LWia::InitSession
• LWia::EndSession
• Class Members

Topics

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

Example

class CMyWIA : public LWia 
{ 
public: 
   L_INT AcquireFileCallBack(L_TCHAR * pszFilename, L_UINT32 uPercent, L_UINT32 uFlags); 
}; 
 
L_INT CMyWIA::AcquireFileCallBack(L_TCHAR * pszFilename, L_UINT32 uPercent, L_UINT32 uFlags) 
{ 
   UNREFERENCED_PARAMETER(uPercent); 
 
   L_TCHAR szMsg[MAX_PATH] = TEXT(""); 
 
   if(uFlags & L_WIA_ACQUIRE_END_OF_PAGE && pszFilename != NULL) // at this point the file should be saved to disk. 
   { 
      wsprintf(szMsg,  
               TEXT("Acquired file saved to the following path:\n\n%s"), 
               pszFilename); 
 
      MessageBox(NULL, szMsg, TEXT("Acquire To File"), MB_OK | MB_ICONINFORMATION); 
   } 
 
   return WIA_SUCCESS; 
} 
 
L_INT LWIA__AcquireToFileExample() 
{ 
   L_INT nRet; 
   LWIAACQUIREOPTIONS AcquireOpts; 
   CMyWIA MyClass; 
 
   nRet = MyClass.InitSession(WiaVersion1); 
   if(nRet != WIA_SUCCESS) 
      return nRet; 
 
   nRet = MyClass.SelectDeviceDlg(WiaDeviceTypeDefault, 0); 
   if(nRet != WIA_SUCCESS) 
      return nRet; 
 
   /* Initialize and fill the required fields from the LWIAACQUIREOPTIONS structure */ 
   memset(&AcquireOpts, 0, sizeof(LWIAACQUIREOPTIONS)); 
   AcquireOpts.uStructSize = sizeof(LWIAACQUIREOPTIONS); 
   AcquireOpts.bAppend = FALSE; 
   AcquireOpts.bOverwriteExisting = FALSE; 
   AcquireOpts.bSaveToOneFile = FALSE; 
   lstrcpy(AcquireOpts.szFileName, MAKE_IMAGE_PATH(TEXT("Test.bmp"))); 
 
   nRet = MyClass.AcquireToFile(L_WIA_DEVICE_DIALOG_USE_COMMON_UI, 
                                &AcquireOpts,  
                                NULL, 
                                NULL, 
                                NULL); 
 
   nRet = MyClass.EndSession(); 
 
   if(nRet != WIA_SUCCESS) 
      return nRet; 
 
   return SUCCESS; 
}