Metodo IPortableDevice::SendCommand (portabledeviceapi.h)

  • Articolo

Il metodo SendCommand invia un comando al dispositivo e recupera i risultati in modo sincrono.

Sintassi

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

Parametri

[in] dwFlags

Attualmente non usato; specificare zero.

[in] pParameters

Puntatore a un'interfaccia IPortableDeviceValues che specifica il comando e i parametri da chiamare nel dispositivo. Questa interfaccia deve includere i due valori seguenti per indicare il comando. I parametri aggiuntivi variano a seconda del comando. Per un elenco dei parametri necessari per ogni comando, vedere Comandi.

Comando o proprietà Descrizione
WPD_PROPERTY_COMMON_COMMAND_CATEGORY GUID categoria del comando da inviare. Ad esempio, per reimpostare un dispositivo, si invia WPD_COMMAND_COMMON_RESET_DEVICE.fmtid.
WPD_PROPERTY_COMMON_COMMAND_ID PID del comando da inviare. Ad esempio, per reimpostare un dispositivo, si invierà WPD_COMMAND_COMMON_RESET_DEVICE.pid.

[out] ppResults

Indirizzo di una variabile che riceve un puntatore a un'interfaccia IPortableDeviceValues che indica i risultati dei risultati dei comandi, tra cui esito positivo o negativo e i valori dei comandi restituiti dal dispositivo. Il chiamante deve rilasciare questa interfaccia al termine dell'operazione. I valori recuperati variano in base al comando; vedere la documentazione del comando appropriata in Comandi per informazioni sui valori restituiti da ogni chiamata di comando.

Valore restituito

Il valore restituito indica l'esito positivo o l'errore di inviare un comando e restituire un risultato dal driver; non indica se il driver supporta il comando o se ha rilevato un errore nell'elaborazione del comando. Per altre informazioni, vedere Osservazioni. Questi errori vengono restituiti nei valori HRESULT del parametro ppResults . I possibili valori HRESULT restituiti da questo metodo includono, ma non sono limitati a quelli della tabella seguente.

Codice restituito Descrizione
S_OK
 Il comando è stato ricevuto correttamente dal driver. Ciò non indica che il comando stesso ha avuto esito positivo: è necessario controllare ppResults per determinare l'esito positivo o negativo del comando.
E_POINTER
 Almeno uno degli argomenti è un puntatore NULL.

Commenti

Questa funzione viene usata per inviare un comando direttamente al driver. Un comando è una PROPRIETÀKEY inviata al driver per indicare l'azione prevista, insieme a un elenco di parametri obbligatori. Ogni comando include un elenco di parametri obbligatori e facoltativi e risultati che devono essere inseriti nel pacchetto con il comando per il driver per eseguire l'azione richiesta. Un elenco di comandi definiti dai dispositivi portatili Windows, con i parametri obbligatori e i valori restituiti, viene specificato in Comandi.

La maggior parte dei metodi di Dispositivi portatili Windows funziona in realtà inviando uno o più comandi di Dispositivi portatili Windows per l'utente e eseguendo il wrapping dei parametri. Alcuni comandi non dispongono di metodi di Dispositivi portabili Windows corrispondenti. L'unico modo per chiamare questi comandi consiste nell'usare SendCommand. I comandi seguenti non hanno alcun metodo corrispondente:

È anche necessario chiamare SendCommand per inviare qualsiasi driver driver personalizzato.

Alcuni comandi personalizzati possono richiedere un livello di accesso specifico del codice di controllo input/output (IOCTL). L'applicazione imposta questo livello di accesso chiamando il metodo IPortableDeviceValues::SetUnsignedIntegerValue sui parametri dei comandi che passa al metodo SendCommand . Ad esempio, se un comando personalizzato richiede l'accesso in sola lettura, chiamare SetUnsignedIntegerValue e passare WPD_API_OPTION_IOCTL_ACCESS come primo argomento e FILE_READ_ACCESS come secondo argomento. Aggiornando questi parametri di comando, l'applicazione garantisce che l'API Dispositivi portatili Windows genera il comando con IOCTL di sola lettura.

Errori rilevati dal driver durante l'elaborazione di un comando vengono recuperati dal parametro ppResults , non dal valore restituito SendCommand . Il valore restituito di questo metodo è qualsiasi codice di errore (o esito positivo) rilevato durante l'invio del comando al driver.

Se un driver non supporta il comando specificato, questo metodo avrà esito positivo, ma l'unico elemento garantito nel parametro ppResults restituito sarà WPD_PROPERTY_COMMON_HRESULT, che conterrà E_NOTIMPL. È possibile verificare se un driver supporta un comando chiamando IPortableDeviceCapabilities::GetSupportedCommands prima di chiamare un comando.

Se un comando supporta le opzioni , ad esempio l'eliminazione ricorsiva o l'eliminazione non ricorsiva, è possibile eseguire una query per le opzioni supportate chiamando IPortableDeviceCapabilities::GetCommandOptions.

Non è possibile impostare un timeout in una chiamata a SendCommand , ma lo sviluppatore può tentare di annullare il comando chiamando IPortableDevice::Cancel da un thread separato.

Esempio


// 

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

//

Requisiti

Requisito Valore
Piattaforma di destinazione Windows
Intestazione portabledeviceapi.h
Libreria PortableDeviceGUIDs.lib

Vedi anche

Interfaccia IPortableDevice