IPortableDevice：：SendCommand 方法 (portabledeviceapi.h)

项目
08/25/2023

SendCommand 方法将命令发送到设备，并同步检索结果。

语法

HRESULT SendCommand(
  [in]  const DWORD           dwFlags,
  [in]  IPortableDeviceValues *pParameters,
  [out] IPortableDeviceValues **ppResults
);

参数

[in] dwFlags

当前未使用;指定零。

[in] pParameters

指向 IPortableDeviceValues 接口的指针，该接口指定要在设备上调用的命令和参数。此接口必须包含以下两个值以指示命令。其他参数因命令而异。有关每个命令所需的参数列表，请参阅命令。

命令或属性	说明
WPD_PROPERTY_COMMON_COMMAND_CATEGORY	要发送的命令的类别 GUID 。例如，若要重置设备，需要发送 WPD_COMMAND_COMMON_RESET_DEVICE.fmtid。
WPD_PROPERTY_COMMON_COMMAND_ID	要发送的命令的 PID。例如，若要重置设备，需要发送 WPD_COMMAND_COMMON_RESET_DEVICE.pid。

[out] ppResults

一个变量的地址，该变量接收指向 IPortableDeviceValues 接口的指针，该接口指示命令结果（包括成功或失败）以及设备返回的任何命令值。调用方在使用完此接口后必须释放此接口。检索的值因命令而异;请参阅命令中的相应命令文档，了解每个命令调用返回的值。

返回值

返回的值指示发送命令并从驱动程序返回结果是成功还是失败;它并不指示驱动程序是否支持命令，也不指示它在处理命令时是否遇到一些错误。 (有关详细信息，请参阅 Remarks.) 这些错误在 ppResults 参数的 HRESULT 值中返回。此方法返回的可能 HRESULT 值包括但不限于下表中的值。

返回代码	说明
S_OK	驱动程序已成功接收命令。这并不表示命令本身成功，必须检查 ppResults 来确定命令的成功或失败。
E_POINTER	至少有一个参数是 NULL 指针。

注解

此函数用于将命令直接发送到驱动程序。命令是发送到驱动程序以指示预期操作的 PROPERTYKEY ，以及所需参数的列表。每个命令都有一个必需参数和可选参数和结果的列表，这些参数和结果必须与命令一起打包，驱动程序才能执行请求的操作。命令中提供了由 Windows 可移植设备定义的命令列表，其中包含所需的参数和返回值。

大多数 Windows 可移植设备方法实际上都通过为你发送一个或多个 Windows Portable Devices 命令并包装参数来工作。某些命令没有相应的 Windows 可移植设备方法。调用这些命令的唯一方法是使用 SendCommand。以下命令没有相应的方法：

还必须调用 SendCommand 以发送任何自定义驱动程序命令驱动程序。

某些自定义命令可能需要特定的输入/输出控制代码 (IOCTL) 访问级别。应用程序通过在传递给 SendCommand 方法的命令参数上调用 IPortableDeviceValues：：SetUnsignedIntegerValue 方法来设置此访问级别。例如，如果自定义命令需要只读访问权限，则调用 SetUnsignedIntegerValue 并将WPD_API_OPTION_IOCTL_ACCESS作为第一个参数传递，FILE_READ_ACCESS作为第二个参数传递。通过更新这些命令参数，应用程序可确保 Windows 可移植设备 API 使用只读 IOCTL 发出命令。

驱动程序在处理命令时遇到的错误由 ppResults 参数而不是 SendCommand 返回值检索。此方法的返回值是向驱动程序发送命令时遇到的任何错误 (或成功) 代码。

如果驱动程序不支持指定的命令，则此方法将成功，但返回的 ppResults 参数中唯一有保证的元素将WPD_PROPERTY_COMMON_HRESULT，其中包含E_NOTIMPL。可以通过在调用命令之前调用 IPortableDeviceCapabilities：：GetSupportedCommands 来验证驱动程序是否支持命令。

如果命令支持 (选项（如递归删除或) 删除非递归删除），可以通过调用 IPortableDeviceCapabilities：：GetCommandOptions 来查询支持的选项。

在调用 SendCommand 时没有设置超时的选项，但开发人员可以通过从单独的线程调用 IPortableDevice：：Cancel 来尝试取消该命令。

示例


// 

void ResetDevice(IPortableDevice* pDevice)
{
    HRESULT  hr = S_OK;
    CComPtr<IPortableDeviceValues>  pDevValues;

    hr = CoCreateInstance(CLSID_PortableDeviceValues,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IPortableDeviceValues,
        (VOID**) &pDevValues);
    if (SUCCEEDED(hr))
    {
        if (pDevValues != NULL)
        {
            hr = pDevValues->SetGuidValue(WPD_PROPERTY_COMMON_COMMAND_CATEGORY, 
                WPD_COMMAND_COMMON_RESET_DEVICE.fmtid);
            if (FAILED(hr))
            {
                printf("! IPortableDeviceValues::SetGuidValue failed, hr= 0x%lx\n", hr);
            }
            hr = pDevValues->SetUnsignedIntegerValue(WPD_PROPERTY_COMMON_COMMAND_ID,
                WPD_COMMAND_COMMON_RESET_DEVICE.pid);
            if (FAILED(hr))
            {
                printf("! IPortableDeviceValues::SetGuidValue failed, hr= 0x%lx\n", hr);
            }
        }
    }
    hr = pDevice->SendCommand(0, pDevValues, &pDevValues);
    if (FAILED(hr))
    {
        printf("! Failed to reset the device, hr = 0x%lx\n",hr);
    }
    else
        printf("Device successfully reset\n");
    return;
}

//

要求

要求	值
目标平台	Windows
标头	portabledeviceapi.h
Library	PortableDeviceGUIDs.lib

另请参阅

IPortableDevice 接口

IPortableDevice：：SendCommand 方法 (portabledeviceapi.h)

语法

参数

返回值

注解

示例

要求

另请参阅

反馈

反馈

其他资源