Метод 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	Идентификатор идентификатора отправляемой команды. Например, чтобы сбросить устройство, необходимо отправить WPD_COMMAND_COMMON_RESET_DEVICE.pid.

[out] ppResults

Адрес переменной, получающей указатель на интерфейс IPortableDeviceValues , указывающий результаты выполнения команд, включая успешное или неудачное выполнение, а также все значения команд, возвращаемые устройством. Вызывающий объект должен освободить этот интерфейс после завершения работы с ним. Полученные значения зависят от команды; Сведения о значениях, возвращаемых каждым вызовом команды, см. в документации по соответствующим командам в разделе Команды .

Возвращаемое значение

Возвращаемое значение указывает на успешность или неудачу отправки команды и возврата результата от драйвера; Он не указывает, поддерживает ли драйвер команду или возникла ли ошибка при обработке команды. (Дополнительные сведения см. в разделе Примечания.) Эти ошибки возвращаются в значениях HRESULT параметра ppResults . Возможные значения HRESULT , возвращаемые этим методом, включают, но не ограничиваются ими, приведенные в следующей таблице.

Код возврата	Описание
S_OK	Команда успешно получена драйвером. Это не означает, что сама команда выполнена успешно. Необходимо проверка ppResults, чтобы определить успешность или сбой команды.
E_POINTER	По крайней мере один из аргументов был пустым указателем.

Эта функция используется для отправки команды непосредственно драйверу. Команда — это PROPERTYKEY , отправляемый драйверу для указания ожидаемого действия, а также список обязательных параметров. Каждая команда содержит список обязательных и необязательных параметров и результатов, которые необходимо упаковать с помощью команды, чтобы драйвер выполнил запрошенное действие. Список команд, определенных переносными устройствами Windows, с необходимыми параметрами и возвращаемыми значениями приведен в разделе Команды.

Большинство методов переносимых устройств Windows фактически работают путем отправки одной или нескольких команд переносимых устройств Windows и упаковки параметров. Некоторые команды не имеют соответствующих методов переносных устройств Windows. Единственный способ вызвать эти команды — с помощью SendCommand. Следующие команды не имеют соответствующего метода:

Кроме того, необходимо вызвать SendCommand для отправки любых пользовательских команд драйвера драйвера.

Для некоторых пользовательских команд может потребоваться определенный уровень доступа IOCTL. Приложение задает этот уровень доступа, вызывая метод IPortableDeviceValues::SetUnsignedIntegerValue для параметров команды, передаваемых методу SendCommand . Например, если настраиваемой команде требуется доступ только для чтения, необходимо вызвать SetUnsignedIntegerValue и передать WPD_API_OPTION_IOCTL_ACCESS в качестве первого аргумента и FILE_READ_ACCESS в качестве второго аргумента. Обновляя эти параметры команды, приложение гарантирует, что API переносимых устройств Windows выдает команду с 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
Header	portabledeviceapi.h
Библиотека	PortableDeviceGUIDs.lib

См. также раздел

Интерфейс IPortableDevice

Поделиться через