Erweiterte Befehle des Anbieters

Eine Anwendung kann einen beliebigen Befehl über die IWiaItemExtras::Escape-Methode an das Gerät senden, die in der Microsoft Windows SDK-Dokumentation beschrieben wird. Durch Aufrufen von QueryInterface für das Stammelement können Sie einen Zeiger auf die IWiaItemExtras-Schnittstelle abrufen. Die Anwendung kann dann einen PTP-Befehl mit beliebigen Opcode und Parametern erstellen und diesen Befehl an das Gerät senden. Die Anwendung kann auch Daten an das Gerät senden oder von diesem empfangen.

Das Gerät informiert die Anwendung über das Ergebnis des Vorgangs, wenn die IWiaItemExtras::Escape-Methode zurückgegeben wird, und füllt einen Antwortcode und Antwortparameter in einer PTP_VENDOR_DATA_OUT-Struktur ein. Die Member SessionId und TransactionId der PTP_VENDOR_DATA_IN-Struktur werden ignoriert. Der Treiber stellt die richtigen Werte für diese bereit.

Bei anderen vom Anbieter definierten Befehlen als ESCAPE_PTP_CLEAR_STALLS muss ein spezielles Flag ESCAPE_PTP_VENDOR_COMMAND (mit einem OR-Operator) mit dem Befehl kombiniert werden, der in der IWiaItemExtras::Escape-Methode verwendet wird. Wenn ein vom Anbieter definierter Befehl ein Objekt auf dem Gerät mit den folgenden beschriebenen Flags erstellt oder löscht, fügt der Treiber das Objekt hinzu oder entfernt es aus seinen internen Strukturen und generiert ein WIA-Ereignis. Alle anderen Standardbefehle sollten über die entsprechende WIA-Schnittstelle ausgegeben werden.

Der erste Parameter für IWiaItemExtras::Escape ist die Kombination aus mindestens einem der folgenden Flags:

Escapecode	Bedeutung
ESCAPE_PTP_ADD_OBJ_CMD	Ein Objekt wird hinzugefügt, und das Handle für das Objekt befindet sich in einem der Befehlsparameter.
ESCAPE_PTP_REM_OBJ_CMD	Ein Objekt wird entfernt, und das Handle für das Objekt befindet sich in einem der Befehlsparameter.
ESCAPE_PTP_ADD_OBJ_RESP	Ein Objekt wird hinzugefügt, und das Handle für das Objekt befindet sich in einem der Antwortparameter.
ESCAPE_PTP_REM_OBJ_RESP	Ein Objekt wird entfernt, und das Handle für das Objekt befindet sich in einem der Antwortparameter.
ESCAPE_PTP_ADDREM_PARM1	Das Handle für das hinzugefügte oder entfernte Objekt befindet sich im ersten Parameter des Befehls oder der Antwort.
ESCAPE_PTP_ADDREM_PARM2	Das Handle für das hinzugefügte oder entfernte Objekt befindet sich im zweiten Parameter des Befehls oder der Antwort.
ESCAPE_PTP_ADDREM_PARM3	Das Handle für das hinzugefügte oder entfernte Objekt befindet sich im dritten Parameter des Befehls oder der Antwort.
ESCAPE_PTP_ADDREM_PARM4	Das Handle für das hinzugefügte oder entfernte Objekt befindet sich im vierten Parameter des Befehls oder der Antwort.
ESCAPE_PTP_ADDREM_PARM5	Das Handle für das hinzugefügte oder entfernte Objekt befindet sich im fünften Parameter des Befehls oder der Antwort.
ESCAPE_PTP_CLEAR_STALLS	Löschen Sie alle Fehlerbedingungen, die durch einen vom Anbieter erweiterten Befehl verursacht werden. Dieses Flag kann nicht in Kombination mit einem der anderen Flags verwendet werden. Weitere Informationen zu diesem Flag finden Sie im Hinweis in dieser Tabelle.
ESCAPE_PTP_VENDOR_COMMAND	Der Befehl ist ein vom Anbieter erweiterter Befehl.

Wenn eine Anwendung IWiaItemExtras::Escape mit dem ESCAPE_PTP_CLEAR_STALL-Flag als erstes Argument für diese Methode aufruft, gibt der Treiber die PTP-Anforderung Zum Abrufen des Gerätestatus aus, um zu bestimmen, ob Endpunkte eine STALL-Bedingung aufweisen. Wenn der Befehl Gerätestatus abrufen erfolgreich ist, gibt der Treiber den IOCTL_RESET_PIPE USB-Steuerungscode für jeden solchen Endpunkt aus. Wenn der Befehl Gerätestatus abrufen fehlschlägt, gibt der Treiber eine PTP-Anforderung zur Gerätezurücksetzung aus . Gerätestatus abrufen und Gerätezurücksetzung werden in der PIMA 15740:2000 Standard, First Edition und Revision 1.0 der USB-SICDD-Gerätedefinition (Still Image Capture Device Definition) beschrieben.

Der folgende Beispielcode veranschaulicht die Verwendung der vom Anbieter erweiterten Befehlsschnittstelle. Stellen Sie sicher, dass Ihr Code den ptpusd.h-Header enthält, da er die Definitionen der Escapecodes und anderer Konstanten sowie die PTP_VENDOR_DATA_IN - und PTP_VENDOR_DATA_OUT-Strukturen enthält. Die IWiaItemExtras-Schnittstelle wird mithilfe eines Aufrufs von QueryInterface für das Stammelement abgerufen. Ein Zeiger auf dieses Stammelement, pIWiaRootItem, kann beispielsweise durch einen Aufruf von IWiaDevMgr::SelectDeviceDlg abgerufen werden (in der Microsoft Windows SDK-Dokumentation beschrieben).

//
// Test IWiaItemExtras::Escape method
//
HRESULT hr = S_OK;
IWiaItemExtras *pIWiaItemExtras = NULL;

hr = pIWiaRootItem->QueryInterface(IID_IWiaItemExtras,
                                   (VOID **) &pIWiaItemExtras);
if (FAILED(hr)) {
    MessageBox("QueryInterface for IWiaItemExtras failed");
    return;
}

PTP_VENDOR_DATA_IN *pDataIn = NULL;
PTP_VENDOR_DATA_OUT *pDataOut = NULL;
DWORD dwDataInSize = SIZEOF_REQUIRED_VENDOR_DATA_IN;
DWORD dwDataOutSize = SIZEOF_REQUIRED_VENDOR_DATA_OUT + 0x1000;
DWORD dwActualDataOutSize = 0;

pDataIn = (PTP_VENDOR_DATA_IN *) CoTaskMemAlloc(dwDataInSize);
if (!pDataIn) {
    MessageBox("CoTaskMemAlloc failed");
    return;
}

pDataOut = (PTP_VENDOR_DATA_OUT *) CoTaskMemAlloc(dwDataOutSize);
if (!pDataOut) {
 CoTaskMemFree(pDataIn);
    MessageBox("CoTaskMemAlloc failed");
    return;
}
ZeroMemory(pDataIn, dwDataInSize);
ZeroMemory(pDataOut, dwDataOutSize);

pDataIn->OpCode = 0x1001;
pDataIn->SessionId = 0;     // The driver will fill this in.
pDataIn->TransactionId = 0; // The driver will fill this in.
pDataIn->NumParams = 0;

//
// pDataIn->NextPhase informs the PTP driver whether to 
// read data from the device (as shown), or
// write data to the device (use PTP_NEXTPHASE_WRITE_DATA),
// to neither read nor write data (use PTP_NEXTPHASE_NO_DATA).
//
pDataIn->NextPhase = PTP_NEXTPHASE_READ_DATA;

hr = pIWiaItemExtras->Escape(ESCAPE_PTP_VENDOR_COMMAND,
                             (BYTE *) pDataIn, dwDataInSize,
                             (BYTE *) pDataOut, dwDataOutSize,
                             &dwActualDataOutSize);

if (FAILED(hr)) {
    MessageBox("Escape failed");
    return;
}

//
// Data returned from device is located at pDataOut->VendorReadData.
//