Método IPortableDevice::SendCommand (portabledeviceapi.h)

  • Artigo

O método SendCommand envia um comando para o dispositivo e recupera os resultados de forma síncrona.

Sintaxe

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

Parâmetros

[in] dwFlags

Atualmente não usado; especifique zero.

[in] pParameters

Ponteiro para uma interface IPortableDeviceValues que especifica o comando e os parâmetros a serem chamados no dispositivo. Essa interface deve incluir os dois valores a seguir para indicar o comando . Parâmetros adicionais variam dependendo do comando . Para obter uma lista dos parâmetros necessários para cada comando, consulte Comandos.

Comando ou propriedade Descrição
WPD_PROPERTY_COMMON_COMMAND_CATEGORY O GUID da categoria do comando a ser enviado. Por exemplo, para redefinir um dispositivo, você enviaria WPD_COMMAND_COMMON_RESET_DEVICE.fmtid.
WPD_PROPERTY_COMMON_COMMAND_ID O PID do comando a ser enviado. Por exemplo, para redefinir um dispositivo, você enviaria WPD_COMMAND_COMMON_RESET_DEVICE.pid.

[out] ppResults

Endereço de uma variável que recebe um ponteiro para uma interface IPortableDeviceValues que indica os resultados dos resultados do comando, incluindo êxito ou falha, e quaisquer valores de comando retornados pelo dispositivo. O chamador deve liberar essa interface quando terminar de usá-la. Os valores recuperados variam de acordo com o comando; consulte a documentação de comando apropriada em Comandos para saber quais valores são retornados por cada chamada de comando.

Retornar valor

O valor retornado indica êxito ou falha ao enviar um comando e retorna um resultado do driver; ele não indica se o driver dá suporte ao comando ou se encontrou algum erro ao processar o comando. (Para obter mais informações, consulte Comentários.) Esses erros são retornados nos valores HRESULT do parâmetro ppResults . Os possíveis valores HRESULT retornados por esse método incluem, mas não se limitam a, aqueles na tabela a seguir.

Código de retorno Descrição
S_OK
 O comando foi recebido com êxito pelo driver. Isso não indica que o comando em si foi bem-sucedido. Você deve marcar ppResults para determinar o êxito ou a falha do comando.
E_POINTER
 Pelo menos um dos argumentos era um ponteiro NULL.

Comentários

Essa função é usada para enviar um comando diretamente para o driver. Um comando é um PROPERTYKEY que é enviado ao driver para indicar a ação esperada, juntamente com uma lista de parâmetros necessários. Cada comando tem uma lista de parâmetros e resultados obrigatórios e opcionais que devem ser empacotados com o comando para que o driver execute a ação solicitada. Uma lista de comandos definidos por Dispositivos Portáteis do Windows, com os parâmetros necessários e valores retornados, é fornecida em Comandos.

A maioria dos métodos de Dispositivos Portáteis do Windows realmente funciona enviando um ou mais dos comandos dispositivos portáteis do Windows para você e encapsulando os parâmetros para você. Alguns comandos não têm métodos de Dispositivos Portáteis do Windows correspondentes. A única maneira de chamar esses comandos é usando SendCommand. Os comandos a seguir não têm nenhum método correspondente:

Você também deve chamar SendCommand para enviar qualquer driver de comandos de driver personalizado.

Alguns comandos personalizados podem exigir um nível de acesso IOCTL (Código de Controle de Entrada/Saída) específico. Seu aplicativo define esse nível de acesso chamando o método IPortableDeviceValues::SetUnsignedIntegerValue nos parâmetros de comando que ele passa para o método SendCommand . Por exemplo, se um comando personalizado exigir acesso somente leitura, você chamará SetUnsignedIntegerValue e passará WPD_API_OPTION_IOCTL_ACCESS como o primeiro argumento e FILE_READ_ACCESS como o segundo argumento. Ao atualizar esses parâmetros de comando, seu aplicativo garante que a API de Dispositivos Portáteis do Windows emita o comando com o IOCTL somente leitura.

Os erros encontrados pelo driver durante o processamento de um comando são recuperados pelo parâmetro ppResults , não pelo valor retornado SendCommand . O valor retornado desse método é qualquer código de erro (ou êxito) encontrado ao enviar o comando para o driver.

Se um driver não der suporte ao comando especificado, esse método terá êxito, mas o único elemento garantido no parâmetro ppResults retornado será WPD_PROPERTY_COMMON_HRESULT, que conterá E_NOTIMPL. Você pode verificar se um driver dá suporte a um comando chamando IPortableDeviceCapabilities::GetSupportedCommands antes de chamar um comando.

Se um comando der suporte a opções (como excluir recursivamente ou excluir não recursivamente), você poderá consultar opções com suporte chamando IPortableDeviceCapabilities::GetCommandOptions.

Não há nenhuma opção para definir um tempo limite em uma chamada para SendCommand , mas o desenvolvedor pode tentar cancelar o comando chamando IPortableDevice::Cancel de um thread separado.

Exemplos


// 

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;
}

//

Requisitos

Requisito Valor
Plataforma de Destino Windows
Cabeçalho portabledeviceapi.h
Biblioteca PortableDeviceGUIDs.lib

Confira também

IPortableDevice Interface