IPortableDevice::SendCommand-Methode (portabledeviceapi.h)

Artikel
03/01/2024

Die SendCommand-Methode sendet einen Befehl an das Gerät und ruft die Ergebnisse synchron ab.

Syntax

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

Parameter

[in] dwFlags

Derzeit nicht verwendet; geben Sie null an.

[in] pParameters

Zeiger auf eine IPortableDeviceValues-Schnittstelle , die den Befehl und die Parameter angibt, die auf dem Gerät aufgerufen werden sollen. Diese Schnittstelle muss die folgenden beiden Werte enthalten, um den Befehl anzugeben. Zusätzliche Parameter variieren je nach Befehl. Eine Liste der Parameter, die für jeden Befehl erforderlich sind, finden Sie unter Befehle.

Befehl oder Eigenschaft	BESCHREIBUNG
WPD_PROPERTY_COMMON_COMMAND_CATEGORY	Die Kategorie-GUID des zu sendenden Befehls. Wenn Sie beispielsweise ein Gerät zurücksetzen möchten, senden Sie WPD_COMMAND_COMMON_RESET_DEVICE.fmtid.
WPD_PROPERTY_COMMON_COMMAND_ID	Die PID des zu sendenden Befehls. Wenn Sie beispielsweise ein Gerät zurücksetzen möchten, senden Sie WPD_COMMAND_COMMON_RESET_DEVICE.pid.

[out] ppResults

Adresse einer Variablen, die einen Zeiger auf eine IPortableDeviceValues-Schnittstelle empfängt , die die Ergebnisse der Befehlsergebnisse angibt, einschließlich Erfolg oder Fehler, und alle vom Gerät zurückgegebenen Befehlswerte. Der Aufrufer muss diese Schnittstelle freigeben, wenn sie damit fertig ist. Die abgerufenen Werte variieren je nach Befehl. Sehen Sie sich die entsprechende Befehlsdokumentation unter Befehle an, um zu erfahren, welche Werte von jedem Befehlsaufruf zurückgegeben werden.

Rückgabewert

Der zurückgegebene Wert gibt an, dass ein Befehl erfolgreich oder nicht gesendet wurde und ein Ergebnis vom Treiber zurückgegeben wird. Sie gibt nicht an, ob der Treiber den Befehl unterstützt oder ob bei der Verarbeitung des Befehls ein Fehler aufgetreten ist. (Weitere Informationen finden Sie unter Hinweise.) Diese Fehler werden in den HRESULT-Werten des ppResults-Parameters zurückgegeben. Die möglichen HRESULT-Werte , die von dieser Methode zurückgegeben werden, sind jedoch nicht darauf beschränkt.

Rückgabecode	BESCHREIBUNG
S_OK	Der Befehl wurde vom Treiber erfolgreich empfangen. Dies bedeutet nicht, dass der Befehl selbst erfolgreich war. Sie müssen ppResults überprüfen, um den Erfolg oder Fehler des Befehls zu ermitteln.
E_POINTER	Mindestens eines der Argumente war ein NULL-Zeiger.

Hinweise

Diese Funktion wird verwendet, um einen Befehl direkt an den Treiber zu senden. Ein Befehl ist ein PROPERTYKEY , der an den Treiber gesendet wird, um die erwartete Aktion anzugeben, zusammen mit einer Liste der erforderlichen Parameter. Jeder Befehl verfügt über eine Liste der erforderlichen und optionalen Parameter und Ergebnisse, die mit dem Befehl gepackt werden müssen, damit der Treiber die angeforderte Aktion ausführen kann. Eine Liste von Befehlen, die von Windows Portable Devices definiert werden, mit den erforderlichen Parametern und Rückgabewerten, wird in Befehle angegeben.

Die meisten Windows Portable Devices-Methoden funktionieren tatsächlich, indem sie einen oder mehrere der Windows Portable Devices-Befehle für Sie senden und die Parameter für Sie umschließen. Einige Befehle verfügen über keine entsprechenden Windows Portable Devices-Methoden. Diese Befehle können nur mithilfe von SendCommand aufgerufen werden. Die folgenden Befehle verfügen über keine entsprechende Methode:

Sie müssen auch SendCommand aufrufen, um benutzerdefinierte Treiberbefehle zu senden.

Für einige benutzerdefinierte Befehle ist möglicherweise eine bestimmte IOCTL-Zugriffsebene (Input/Output Control Code) erforderlich. Ihre Anwendung legt diese Zugriffsebene fest, indem sie die IPortableDeviceValues::SetUnsignedIntegerValue-Methode für die Befehlsparameter aufruft, die sie an die SendCommand-Methode übergibt. Wenn ein benutzerdefinierter Befehl beispielsweise schreibgeschützten Zugriff erfordert, würden Sie SetUnsignedIntegerValue aufrufen und WPD_API_OPTION_IOCTL_ACCESS als erstes Argument und FILE_READ_ACCESS als zweites Argument übergeben. Durch das Aktualisieren dieser Befehlsparameter stellt Ihre Anwendung sicher, dass die Windows Portable Devices-API den Befehl mit der schreibgeschützten IOCTL ausgibt.

Fehler, die beim Verarbeiten eines Befehls vom Treiber auftreten, werden vom ppResults-Parameter abgerufen, nicht vom SendCommand-Rückgabewert . Der Rückgabewert dieser Methode ist jeder Fehlercode (oder Erfolgscode), der beim Senden des Befehls an den Treiber auftritt.

Wenn ein Treiber den angegebenen Befehl nicht unterstützt, ist diese Methode erfolgreich, aber das einzige garantierte Element im zurückgegebenen ppResults-Parameter ist WPD_PROPERTY_COMMON_HRESULT, das E_NOTIMPL enthält. Sie können überprüfen, ob ein Treiber einen Befehl unterstützt, indem Sie IPortableDeviceCapabilities::GetSupportedCommands aufrufen, bevor Sie einen Befehl aufrufen.

Wenn ein Befehl Optionen unterstützt (z. B. rekursives Löschen oder nicht wiederholendes Löschen), können Sie unterstützte Optionen abfragen, indem Sie IPortableDeviceCapabilities::GetCommandOptions aufrufen.

Es gibt keine Option zum Festlegen eines Timeouts in einem Aufruf von SendCommand , aber der Entwickler kann versuchen, den Befehl abzubrechen, indem er IPortableDevice::Cancel aus einem separaten Thread aufruft.

Beispiele


// 

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

//

Anforderungen

Anforderung	Wert
Zielplattform	Windows
Kopfzeile	portabledeviceapi.h
Bibliothek	PortableDeviceGUIDs.lib

Weitere Informationen

IPortableDevice-Schnittstelle

Freigeben über