L_WiaAcquireSimple

Summary

Acquires one or more images from a WIA source.

Syntax

L_LTWIA_API L_INT EXT_FUNCTION L_WiaAcquireSimple(uWiaVersion, hWndParent, uDeviceType, uFlags, pSourceItem, pAcquireOptions, pnFilesCount, pppszFilePaths, pfnCallBack, pUserData)

Parameters

L_UINT uWiaVersion

The WIA version to be used. Possible values are:

HWND hWndParent

Handle to the window or dialog to be the parent for the device's acquiring dialog.

L_UINT32 uDeviceType

Specifies which type of WIA device to use. Possible values are:

L_UINT32 uFlags

Flag that determines certain actions of the WIA image acquisition selection dialog box and device selection dialog. You can combine values when appropriate by using a bitwise OR ( | ). Possible values are:

L_VOID * pSourceItem

This parameter is used only if you are acquiring from scanner device and the L_WIA_SHOW_USER_INTERFACE flag is NOT set. Through this parameter you can specify the scanners paper source (Feeder or Flatbed).

This flag is optional, since if you are using WIA 1.0 then you can change the paper source by changing the WIA_DPS_DOCUMENT_HANDLING_SELECT property for the root item or by enumerating the available scanner items and pass the item you wish to scan from.

If you are using WIA 2.0 then you have to enumerate the available scanner items and pass the item you wish to scan from or you can pass NULL and in this case the enumeration will be done internally and the first enumerated item will be used as the source item.

pLWIAACQUIREOPTIONS pAcquireOptions

Pointer to an optional acquires options structure that contains information the user can use to control the acquisition behavior from the WIA device.

If the user passed NULL for this parameter, internal default values will be used.

L_INT * pnFilesCount

Pointer to a variable of type L_INT to be updated with the number of the files to be saved when acquiring using File mode.

L_TCHAR *** pppszFilePaths

Pointer to string buffer to hold an array of the saved file paths. Used when the transfer mode is file.

You can 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 names array.

LWIAACQUIRECALLBACK pfnCallBack

Pointer to an optional callback the user can use to retrieve a bitmap handle that contains, in concatenated form, each transferred chunk of data. Used when the transfer mode is memory transfer.

Also this callback will provide the user with the percent completion of the acquisition process. Use this to update the progress bar.

✎ NOTE

This callback is only available when using WIA version 1.0, since the WIA 2.0 Acquire dialog does not provide a callback.

L_VOID * 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.

Returns

Comments

This feature is available in version 16 or higher.

This is a high level acquire function that you can call directly. When using this function, the following functions are called internally:

L_WiaInitSession

L_WiaSelectDeviceDlg

L_WiaEndSession

You can let this method do either memory transfer or file transfer by doing one of the following:

• Set the transfer mode you wish to use through the LWIAPROPERTIES structure and pass it to the L_WiaSetProperties method.

• Set the transfer mode by calling the low level method L_WiaSetPropertyLong passing WIA_IPA_TYMED for the uID member of this method and transfe mode you wish to use (TYMED_CALLBACK or TYMED_FILE) for the lValue member.

When performing memory transfer you need to provide a callback pointer to receive the acquired page(s). Use the pBitmap parameter of the callback. The callback will also provide you with the percent completion of the page transfer progress.

When performing file transfers it is optional to provide a callback pointer, since the callback will only provide the saved file path and the percent completion of the file save process.

To cancel the acquire operation provide a pointer to the LWIAACQUIRECALLBACK callback and return the ERROR_USER_ABORT error code.

✎ NOTE

If the user set the L_WIA_SHOW_USER_INTERFACE flag, then he should be aware of the following point:

Some of the previously set/changed user properties using any of the L_WiaSetPropertyXXX or L_WiaSetProperties functions will be overwritten by the Microsoft 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. This is a known limitation of Microsoft's WIA toolkit.

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.

Platforms

LEADTOOLS WIA supports both 32-bit and 64-bit image acquisition for both WIA 1.0 (XP and earlier) and WIA 2.0 (VISTA and later).

See Also

Functions

• L_WiaAcquire
• L_WiaAcquireToFile.

Topics

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

Example

static L_INT CALLBACK WiaAcquireSimpleCB(HWIASESSION hSession, 
                                         pBITMAPHANDLE pBitmap, 
                                         L_TCHAR * pszFilename, 
                                         L_UINT32 uPercent, 
                                         L_UINT32 uFlags, 
                                         L_VOID * pUserData) 
{ 
   UNREFERENCED_PARAMETER(hSession); 
   UNREFERENCED_PARAMETER(pBitmap); 
   UNREFERENCED_PARAMETER(pszFilename); 
   UNREFERENCED_PARAMETER(uPercent); 
   UNREFERENCED_PARAMETER(uFlags); 
   UNREFERENCED_PARAMETER(pUserData); 
 
   // You can do here any processing to the bitmap. 
 
   return WIA_SUCCESS; 
} 
 
L_INT WiaAcquireSimpleExample(L_UINT uWiaVersion, HWND hWnd) 
{ 
   L_INT nRet; 
   LWIAACQUIREOPTIONS AcquireOpts; 
   L_UINT uFlags; 
 
   uFlags = L_WIA_SELECT_DEVICE_NODEFAULT | L_WIA_SHOW_USER_INTERFACE | L_WIA_DEVICE_DIALOG_USE_COMMON_UI; 
 
   /* Initialize and fill the required fields from the LWIAACQUIREOPTIONS structure */ 
   memset(&AcquireOpts, 0, sizeof(LWIAACQUIREOPTIONS)); 
   AcquireOpts.uStructSize = sizeof(LWIAACQUIREOPTIONS); 
   AcquireOpts.bDoubleBuffer = TRUE; 
   AcquireOpts.uMemBufSize = 64 * 1024; 
 
   nRet = L_WiaAcquireSimple(uWiaVersion,  
                             hWnd,  
                             WiaDeviceTypeDefault,  
                             uFlags,  
                             NULL,  
                             &AcquireOpts, 
                             NULL, 
                             NULL, 
                             WiaAcquireSimpleCB,  
                             NULL); 
   if(nRet != WIA_SUCCESS) 
      return nRet; 
 
   return SUCCESS; 
}