IWiaDevMgr2::GetImageDlg method

The IWiaDevMgr2::GetImageDlg method displays one or more dialog boxes that enable a user to acquire an image from a Windows Image Acquisition (WIA) 2.0 device and write the image to a specified file. This method extends the functionality of IWiaDevMgr2::SelectDeviceDlg to encapsulate image acquisition within a single API call.

Syntax


HRESULT GetImageDlg(
  [in]       LONG lFlags,
  [in]       BSTR bstrDeviceID,
  [in]       HWND hwndParent,
  [in]       BSTR bstrFolderName,
  [in]       BSTR bstrFilename,
  [in]       LONG *plNumFiles,
  [in]       BSTR **ppbstrFilePaths,
  [in, out]  IWiaItem2 **ppItem
);

Parameters

lFlags [in]

Type: LONG

Specifies dialog box behavior. Can be set to the following values:

FlagMeaning
0Default behavior.
WIA_DEVICE_DIALOG_USE_COMMON_UIUse the system UI instead of the vendor-supplied UI. If the system UI is not available, the vendor UI is used. If neither UI is available, the function returns E_NOTIMPL.

 

bstrDeviceID [in]

Type: BSTR

Specifies the scanner to use.

hwndParent [in]

Type: HWND

A handle of the window that owns the Get Image dialog box.

bstrFolderName [in]

Type: BSTR

Specifies the name of the folder ito store the scanned files in.

bstrFilename [in]

Type: BSTR

Specifies the name of the file to write the image data to.

plNumFiles [in]

Type: LONG*

A pointer to the number of files to scan.

ppbstrFilePaths [in]

Type: BSTR**

The address of a pointer to an array of paths for the scanned files. Initialize the pointer to point to an array of size zero (0) before IWiaDevMgr2::GetImageDlg is called. See Remarks.

ppItem [in, out]

Type: IWiaItem2**

The address of a pointer to the IWiaItem2 that the images were scanned from.

Return value

Type: HRESULT

IWiaDevMgr2::GetImageDlg returns S_OK if the data is transferred successfully, returns S_FALSE if the user cancels the dialog box, or returns a standard COM error.

Note  The ppbstrFilePaths parameter is not necessarily empty, if the function returns S_FALSE. If the user cancels, the pages that have completed scanning are processed and returned in ppbstrFilePaths. Even if they are not used, you must free the array. See Remarks.

Remarks

If the application passes NULL for the value of the bstrDeviceID parameter, IWiaDevMgr2::GetImageDlg displays the Select Device dialog box so that the user can select the WIA 2.0 input device.

Use a menu item named From scanner on the File menu so that device and image selections are available in your application.

Call SysFreeString on each BSTR in the array that ppbstrFilePaths[i] points to, and call CoTaskMemFree on the array itself to free associated memory. If S_FALSE is returned, check to see if the value that plNumFiles points to is not zero. If the value is not zero, free the ppbstrFilePaths[i] resources in the application, because the user might cancel after scanning one or more pages. Initialize plNumFiles to zero before you call IWiaDevMgr2::GetImageDlg. If plNumFiles is not initialized to zero and a failure in the COM infrastructure causes the function to return S_FALSE before IWiaDevMgr2::GetImageDlg is called, then plNumFiles will have a misleading garbage value.

The dialog box must have sufficient rights to bstrFolderName so that it can save the files with unique file names. Protect the folder with an access control list (ACL) because it contains user data.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Wia.h

 

 

Community Additions

ADD
Show:
© 2014 Microsoft