IPortableDevice：：SendCommand 方法 (portabledeviceapi.h)

發行項
03/01/2024

SendCommand 方法會將命令傳送至裝置，並同步擷取結果。

語法

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

參數

[in] dwFlags

目前未使用;指定零。

[in] pParameters

IPortableDeviceValues 介面的指標，指定要在裝置上呼叫的命令和參數。這個介面必須包含下列兩個值，才能指出命令。其他參數會根據命令而有所不同。如需每個命令所需的參數清單，請參閱命令。

命令或屬性	Description
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 介面指標的變數位址，指出命令結果的結果，包括成功或失敗，以及裝置所傳回的任何命令值。呼叫端必須在使用此介面完成時釋放這個介面。擷取的值會因命令而異;請參閱命令中的適當命令檔，以瞭解每個命令呼叫所傳回的值。

傳回值

傳回的值表示成功或失敗以傳送命令並從驅動程式傳回結果;它不會指出驅動程式是否支援命令，或是否在處理命令時遇到一些錯誤。 (如需詳細資訊，請參閱。) 這些錯誤會在 ppResults 參數的 HRESULT 值中傳回。這個方法所傳回的可能 HRESULT 值包括但不限於下表中的值。

傳回碼	描述
S_OK	驅動程式已成功收到命令。這並不表示命令本身成功—您必須檢查 ppResults 來判斷命令的成功或失敗。
E_POINTER	至少有一個自變數是 NULL 指標。

備註

此函式用來將命令直接傳送至驅動程式。命令是一個 PROPERTYKEY ，會傳送至驅動程式以指出預期的動作，以及必要參數的清單。每個命令都有必要和選擇性參數的清單，以及必須使用命令封裝的結果，驅動程式才能執行要求的動作。命令中會提供 Windows 可攜式裝置所定義的命令清單，其中包含必要的參數和傳回值。

大部分的 Windows 可攜式裝置方法實際上都是藉由為您傳送一或多個 Windows 可攜式裝置命令，併為您包裝參數來運作。某些命令沒有對應的 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
程式庫	PortableDeviceGUIDs.lib

另請參閱

IPortableDevice 介面

共用方式為

IPortableDevice：：SendCommand 方法 (portabledeviceapi.h)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源