IPortableDevice::SendCommand 메서드(portabledeviceapi.h)

  • 아티클

SendCommand 메서드는 디바이스에 명령을 보내고 결과를 동기적으로 검색합니다.

구문

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

매개 변수

[in] dwFlags

현재 사용되지 않습니다. 0을 지정합니다.

[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 값에는 다음 표에 있는 값이 포함되지만 이에 국한되지는 않습니다.

반환 코드 Description
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로 명령을 실행하도록 합니다.

명령을 처리하는 동안 드라이버에서 발생하는 오류는 SendCommand 반환 값이 아닌 ppResults 매개 변수에 의해 검색됩니다. 이 메서드의 반환 값은 드라이버에 명령을 보내는 동안 발생하는 오류(또는 성공) 코드입니다.

드라이버가 지정된 명령을 지원하지 않는 경우 이 메서드는 성공하지만 반환된 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 인터페이스