通过

IPortableDevice：：SendCommand 方法 (portabledeviceapi.h)

  • 项目

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 接口