IWiaDevMgr2::SelectDeviceDlg method

Article
04/27/2021

Displays a dialog box that enables the user to select a hardware device for image acquisition.

Syntax

HRESULT SelectDeviceDlg(
  [in]          HWND      hwndParent,
  [in]          LONG      lDeviceType,
  [in]          LONG      lFlags,
  [in, out]     BSTR      *pbstrDeviceID,
  [out, retval] IWiaItem2 **ppItemRoot
);

Parameters

hwndParent [in]

Type: HWND

Specifies the parent window of the Select Device dialog box.

lDeviceType [in]

Type: LONG

Specifies which type of WIA 2.0 device to use. See WIA Device Type Specifiers for a list of possible values.

lFlags [in]

Type: LONG

Specifies the behavior of the dialog box. The value can be one of the following.

0

Use the default behavior.

WIA_SELECT_DEVICE_NODEFAULT

Display the dialog box even though there is only one matching device.

pbstrDeviceID [in, out]

Type: BSTR*

On output, receives a string which contains the device's identifier string. On input, pass the address of a pointer if this information is needed, or NULL if it is not needed.

ppItemRoot [out, retval]

Type: IWiaItem2**

Receives the address of a pointer to the IWiaItem2 interface of the root item of the hierarchical tree that represents the selected WIA 2.0 device. If no device is found, it receives NULL.

Return value

Type: HRESULT

This method can return one of these values.

Return code	Description
S_OK	Device was successfully selected.
S_FALSE	User canceled the dialog box.
WIA_S_NO_DEVICE_AVAILABLE	No WIA 2.0 hardware devices match the specifications given in the lDeviceType parameter.

Remarks

This method creates and displays the Select Device dialog box so the user can select a WIA 2.0 device for image acquisition. If a device is successfully selected, the IWiaDevMgr2::SelectDeviceDlg method creates a hierarchical tree of IWiaItem2 objects for the device. It stores a pointer to the IWiaItem2 interface of the root item in the parameter ppItemRoot.

The application can restrict the devices displayed to the user to particular types by specifying the device types through the lDeviceType parameter. If only one device meets the specification, IWiaDevMgr2::SelectDeviceDlg does not display the Select Device dialog box. Instead it creates the IWiaItem2 tree for the device and store a pointer to the IWiaItem2 interface of the root item in the parameter ppItemRoot. You can override this behavior and force IWiaDevMgr2::SelectDeviceDlg to display the dialog box by specifying WIA_SELECT_DEVICE_NODEFAULT as the value for the lFlags parameter. If more than one WIA 2.0 device matches the specification, all matching devices are displayed in the Select Device dialog box so the user may choose one.

Applications must call the IUnknown::Release method on the interface pointers they receive through the ppItemRoot parameter.

Note

It is recommended that applications make device and image selection available through a menu item named From scanner on the File menu.

Requirements

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