#include "ltwia.h"
L_LTWIA_API L_INT EXT_FUNCTION L_WiaAcquireToFile(hSession, hWndParent, uFlags, pSourceItem, pAcquireOptions, pnFilesCount, pppszFilePaths, pfnCallBack, pUserData)
Acquires one or more images from a WIA source and saves them directly to file(s).
Handle to an existing WIA session. This handle is obtained by calling the L_WiaInitSession function.
Handle to the window or dialog to be the parent for the device's acquiring dialog.
Flag that determines certain actions of the WIA image acquisition selection dialog box. Possible values are:
Value | Meaning |
---|---|
0 | Default behavior for the device image acquisition dialog box. |
L_WIA_DEVICE_DIALOG_SINGLE_IMAGE | [0x00000002] Restrict image selection to a single image in the device image acquisition dialog box. This flag is not available if you are using WIA version 2.0. |
L_WIA_SHOW_USER_INTERFACE | [0x00000003] Show the manufacturer's image acquisition dialog box. |
L_WIA_DEVICE_DIALOG_USE_COMMON_UI | [0x00000004] Use the system user interface (UI), if available, rather than the vendor-supplied UI. If the system UI is not available, the vendor UI is used. |
This parameter only takes place if you are acquiring from scanner device and while 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.
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.
Pointer to a variable of type L_INT to be updated with the number of the saved files.
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 name array.
Pointer to an optional callback the user can use to retrieve the saved file path and the percent completion of the acquisition process.
✎ NOTE
This callback is only available when using WIA version 1.0, since the WIA 2.0 Acquire dialog does not provide a callback.
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.
Value | Meaning |
---|---|
SUCCESS | The function was successful. |
< 1 | An error occurred. Refer to Return Codes. |
This feature is available in version 16 or higher.
This function will acquire single or multiple images from the selected WIA device.
Make sure to call L_WiaInitSession and then call any of the L_WiaSelectDeviceDlg or L_WiaSelectDevice functions before calling this 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, providing a callback pointer 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, provide a pointer to the LWIAACQUIREFILECALLBACK callback and return 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 side.
Required DLLs and Libraries
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).
static L_INT CALLBACK WiaAcquireToFileCB(HWIASESSION hSession,
L_TCHAR * pszFilename,
L_UINT32 uPercent,
L_UINT32 uFlags,
L_VOID * pUserData)
{
UNREFERENCED_PARAMETER(hSession);
UNREFERENCED_PARAMETER(uPercent);
UNREFERENCED_PARAMETER(pUserData);
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 WiaAcquireToFileExample(HWIASESSION hSession, HWND hWnd)
{
L_INT nRet;
LWIAACQUIREOPTIONS AcquireOpts;
nRet = L_WiaSelectDeviceDlg(hSession, hWnd, 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 = L_WiaAcquireToFile(hSession,
hWnd,
L_WIA_SHOW_USER_INTERFACE|L_WIA_DEVICE_DIALOG_USE_COMMON_UI,
NULL,
&AcquireOpts,
NULL,
NULL,
WiaAcquireToFileCB,
NULL);
if(nRet != WIA_SUCCESS)
return nRet;
return SUCCESS;
}