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

[out] ppResults

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

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

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

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

Комментарии

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

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

• WPD_COMMAND_COMMON_RESET_DEVICE
• WPD_COMMAND_DEVICE_HINTS_GET_CONTENT_LOCATION
• WPD_COMMAND_SMS_SEND
• WPD_COMMAND_STILL_IMAGE_CAPTURE_INITIATE
• WPD_COMMAND_STORAGE_EJECT

Кроме того, необходимо вызвать 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