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

  • Artículo

El método SendCommand envía un comando al dispositivo y recupera los resultados de forma sincrónica.

Sintaxis

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

Parámetros

[in] dwFlags

Actualmente no se usa; especifique cero.

[in] pParameters

Puntero a una interfaz IPortableDeviceValues que especifica el comando y los parámetros que se van a llamar en el dispositivo. Esta interfaz debe incluir los dos valores siguientes para indicar el comando . Los parámetros adicionales varían según el comando. Para obtener una lista de los parámetros necesarios para cada comando, vea Comandos.

Comando o propiedad Descripción
WPD_PROPERTY_COMMON_COMMAND_CATEGORY GUID de categoría del comando que se va a enviar. Por ejemplo, para restablecer un dispositivo, enviaría WPD_COMMAND_COMMON_RESET_DEVICE.fmtid.
WPD_PROPERTY_COMMON_COMMAND_ID PID del comando que se va a enviar. Por ejemplo, para restablecer un dispositivo, enviaría WPD_COMMAND_COMMON_RESET_DEVICE.pid.

[out] ppResults

Dirección de una variable que recibe un puntero a una interfaz IPortableDeviceValues que indica los resultados del comando, incluidos los resultados correctos o erróneos, y los valores de comando devueltos por el dispositivo. El autor de la llamada debe liberar esta interfaz cuando haya terminado con ella. Los valores recuperados varían según el comando; consulte la documentación de comandos adecuada en Comandos para obtener información sobre los valores devueltos por cada llamada de comando.

Valor devuelto

El valor devuelto indica éxito o error al enviar un comando y devolver un resultado del controlador; no indica si el controlador admite el comando o si encontró algún error al procesar el comando. (Para obtener más información, vea Comentarios). Estos errores se devuelven en los valores HRESULT del parámetro ppResults . Los posibles valores HRESULT devueltos por este método incluyen, entre otros, los de la tabla siguiente.

Código devuelto Descripción
S_OK
 El controlador recibió correctamente el comando. Esto no indica que el propio comando se ha realizado correctamente; debe comprobar ppResults para determinar el éxito o el error del comando.
E_POINTER
 Al menos uno de los argumentos era un puntero NULL.

Comentarios

Esta función se usa para enviar un comando directamente al controlador. Un comando es una PROPERTYKEY que se envía al controlador para indicar la acción esperada, junto con una lista de parámetros necesarios. Cada comando tiene una lista de parámetros y resultados obligatorios y opcionales que se deben empaquetar con el comando para que el controlador realice la acción solicitada. En Comandos se ofrece una lista de comandos definidos por dispositivos portátiles de Windows, con los parámetros necesarios y los valores devueltos.

La mayoría de los métodos de dispositivos portátiles de Windows funcionan realmente enviando uno o varios de los comandos de dispositivos portátiles de Windows para usted y ajustando los parámetros automáticamente. Algunos comandos no tienen métodos correspondientes de dispositivos portátiles de Windows. La única manera de llamar a estos comandos es mediante SendCommand. Los siguientes comandos no tienen ningún método correspondiente:

También debe llamar a SendCommand para enviar cualquier controlador de comandos de controlador personalizado.

Algunos comandos personalizados pueden requerir un nivel de acceso específico de código de control de entrada y salida (IOCTL). La aplicación establece este nivel de acceso llamando al método IPortableDeviceValues::SetUnsignedIntegerValue en los parámetros de comando que pasa al método SendCommand . Por ejemplo, si un comando personalizado requiere acceso de solo lectura, llamaría a SetUnsignedIntegerValue y pasaría WPD_API_OPTION_IOCTL_ACCESS como primer argumento y FILE_READ_ACCESS como segundo argumento. Al actualizar estos parámetros de comando, la aplicación garantiza que la API de dispositivos portátiles de Windows emite el comando con el IOCTL de solo lectura.

Los errores detectados por el controlador durante el procesamiento de un comando se recuperan mediante el parámetro ppResults , no por el valor devuelto SendCommand . El valor devuelto de este método es cualquier código de error (o correcto) que se encuentra al enviar el comando al controlador.

Si un controlador no admite el comando especificado, este método se realizará correctamente, pero el único elemento garantizado del parámetro ppResults devuelto será WPD_PROPERTY_COMMON_HRESULT, que contendrá E_NOTIMPL. Puede comprobar si un controlador admite un comando llamando a IPortableDeviceCapabilities::GetSupportedCommands antes de llamar a un comando.

Si un comando admite opciones (como eliminar de forma recursiva o eliminar de forma no recursiva), puede consultar las opciones admitidas llamando a IPortableDeviceCapabilities::GetCommandOptions.

No hay ninguna opción para establecer un tiempo de espera en una llamada a SendCommand , pero el desarrollador puede intentar cancelar el comando llamando a IPortableDevice::Cancel desde un subproceso independiente.

Ejemplos


// 

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 Value
Plataforma de destino Windows
Encabezado portabledeviceapi.h
Library PortableDeviceGUIDs.lib

Consulte también

IPortableDevice (Interfaz)