LWia::AcquireSimple

#include "ltwrappr.h"

virtual L_INT LWia::AcquireSimple(uWiaVersion, uDeviceType, uFlags, pSourceItem, pAcquireOptions, pnFilesCount, pppszFilePaths)

L_UINT uWiaVersion;

/* The WIA version to be used */

L_UINT32 uDeviceType;

/* The WIA device type */

L_UINT32 uFlags;

/* optional flags */

L_VOID * pSourceItem;

/* scanner device paper source */

pLWIAACQUIREOPTIONS pAcquireOptions;

/* pointer to an optional acquire options structure */

L_INT * pnFilesCount;

/* optional pointer to a variable */

L_TCHAR *** pppszFilePaths;

/* optional pointer to a string buffer */

Acquires one or more images from a WIA source.

Parameter

Description

uWiaVersion

The WIA version to be used. Possible values are:

 

Value

Meaning

 

WiaVersion1

[1] Use WIA version 1.

 

WiaVersion2

[2] Use WIA version 2.

 

uDeviceType

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

 

Value

Meaning

 

WiaDeviceTypeDefault

Generic WIA device. During device enumerations, this constant is used to enumerate all WIA devices. This is the default value.

 

WiaDeviceTypeScanner

The device is a scanner.

 

WiaDeviceTypeDigitalCamera

The device is a camera. Note that this type of device is not supported by Windows Vista and later.

 

WiaDeviceTypeStreamingVideo

The device contains streaming video. Note that this type of device is not supported by Windows Server 2003, Windows Vista, or later.

 

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:

 

Value

Meaning

 

0

Default behavior for the device image acquisition dialog box and device selection dialog.

 

L_WIA_SELECT_DEVICE_NODEFAULT

[0x00000001] Force displaying the Select Device dialog box even if there is only one device available.

 

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.

pSourceItem

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.

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.

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.

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.

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

Comments

This feature is available in LEADTOOLS 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:

LWia::InitSession

LWia::SelectDeviceDlg

LWia::EndSession

You can specify the parent window for the image acquisition dialog by calling the LScanner::SetWindow function.

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 LWia::SetProperties method.

* Set the transfer mode by calling the low level method LWia::SetPropertyLong 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 override the LWia::AcquireCallBack function in order to receive the acquired page(s) through the pBitmap parameter of this callback. The callback will also provide you with the percent completion of the page transfer progress.

When performing file transfer it is optional to override the LWia::AcquireCallBack function since the callback will only provide you with the saved file path and the percent completion of the file save process.

To cancel the acquire operation you need to override the LWia::AcquireCallBack function 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 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::AcquireToFile, Class Members

Topics:

How to Acquire from the WIA Source

 

WIA Functionality: Property Functions

Example

class CMyWIA : public LWia
{
public:
   L_INT AcquireSimpleCallBack(pBITMAPHANDLE pBitmap, L_TCHAR * pszFilename, L_UINT32 uPercent, L_UINT32 uFlags);
};
L_INT CMyWIA::AcquireSimpleCallBack(pBITMAPHANDLE pBitmap, L_TCHAR * pszFilename, L_UINT32 uPercent, L_UINT32 uFlags)
{
   UNREFERENCED_PARAMETER(pBitmap);
   UNREFERENCED_PARAMETER(pszFilename);
   UNREFERENCED_PARAMETER(uPercent);
   UNREFERENCED_PARAMETER(uFlags);
   // You can do here any processing to the bitmap
   return WIA_SUCCESS;
}
L_LTWIASAM_CLIB L_INT LWIA__AcquireSimpleExample(L_UINT uWiaVersion)
{
   L_INT nRet;
   LWIAACQUIREOPTIONS AcquireOpts;
   L_UINT uFlags;
   CMyWIA MyClass;
   uFlags = L_WIA_SELECT_DEVICE_NODEFAULT | 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 = MyClass.AcquireSimple(uWiaVersion, 
                                WiaDeviceTypeDefault, 
                                uFlags, 
                                &AcquireOpts, 
                                NULL,
                                NULL,
                                NULL);
   if(nRet != WIA_SUCCESS)
      return nRet;
   return SUCCESS;
}