Edit

IWiaDevMgr2::GetImageDlg method

  • Article

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:

Flag Meaning
0 Default behavior.
WIA_DEVICE_DIALOG_USE_COMMON_UI Use 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

Requirement Value
Minimum supported client
 Windows Vista [desktop apps only]
Minimum supported server
 Windows Server 2008 [desktop apps only]
Header
Wia.h