IWiaMiniDrv::drvDeviceCommand method (wiamindr_lh.h)

The IWiaMiniDrv::drvDeviceCommand method issues a command to a WIA device.

Syntax

HRESULT drvDeviceCommand(
  BYTE        *__MIDL__IWiaMiniDrv0043,
  LONG        __MIDL__IWiaMiniDrv0044,
  const GUID  *__MIDL__IWiaMiniDrv0045,
  IWiaDrvItem **__MIDL__IWiaMiniDrv0046,
  LONG        *__MIDL__IWiaMiniDrv0047
);

Parameters

__MIDL__IWiaMiniDrv0043

lFlags [in]

Reserved.

__MIDL__IWiaMiniDrv0044

pWiasContext [in]

Pointer to a WIA item context.

__MIDL__IWiaMiniDrv0045

plCommand [in]

Points to a WIA command GUID.

__MIDL__IWiaMiniDrv0046

plDevErrVal [out]

Points to a memory ___location that will receive a status code for this method. If this method returns S_OK, the value stored will be zero. Otherwise, a minidriver-specific error code will be stored at the ___location pointed to by this parameter.

__MIDL__IWiaMiniDrv0047

ppWiaDrvItem [out, optional]

Points to a memory ___location that can receive a pointer to an IWiaDrvItem Interface. See remarks below.

Return value

On success, the method should return S_OK and clear the device error value pointed to by plDevErrVal. If the method fails, it should return a standard COM error code and place a minidriver-specific error code value in the memory pointed to by plDevErrVal.

The value pointed to by plDevErrVal can be converted to a string by calling IWiaMiniDrv::drvGetDeviceErrorStr.

Remarks

The method IWiaMiniDrv::drvDeviceCommand is called by the WIA service to issue a WIA service or application generated command to the device. The WIA service only calls the IWiaMiniDrv::drvDeviceCommand method for a command that the device can support in the method IWiaMiniDrv::drvGetCapabilities.

The ppWiaDrvItem parameter should be considered to be optional, since the minidriver does not normally set the memory ___location it points to. For certain commands, however, the minidriver places the address of a newly created item in the ___location pointed to by this parameter. For example, if the command to take a picture is issued (plCommand is set to WIA_CMD_TAKE_PICTURE), the device produces a new image, causing the minidriver to create a new item in the driver item tree, and sets *ppWiaDrvItem to the address of the new item. This informs the WIA service that a new item was created.

The minidriver may include a list of custom commands the device can support in the method IWiaMiniDrv::drvGetCapabilities.

The WIA service does not write any properties before calling this method. If the command relies on property settings, the minidriver should call IWiaMiniDrv::drvWriteItemProperties before issuing the command. For example, the command to take a picture, WIA_CMD_TAKE_PICTURE, might rely on shutter speed and aperture settings, which need to be written to the device before the command is issued.

Requirements

See also

IWiaMiniDrv

IWiaMiniDrv::drvGetCapabilities

IWiaMiniDrv::drvWriteItemProperties