Vom Anbieter erweiterte Befehle

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 empfangen.

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

Bei anderen vom Anbieter definierten Befehlen als ESCAPE_PTP_CLEAR_STALLS muss ein spezielles Flag, ESCAPE_PTP_VENDOR_COMMAND, mit dem Befehl kombiniert werden, der in der IWiaItemExtras::Escape-Methode verwendet wird. Wenn ein vom Hersteller definierter Befehl ein Objekt auf dem Gerät mithilfe der folgenden beschriebenen Flags erstellt oder löscht, fügt der Treiber das Objekt aus seinen internen Strukturen hinzu oder entfernt es aus 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 einer oder mehreren der folgenden Flags:

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 Get Device Status-Anforderung aus, um zu bestimmen, ob sich Endpunkte in einer STALL-Bedingung befinden. Wenn der Befehl "Gerätestatus abrufen " erfolgreich ist, gibt der Treiber den IOCTL_RESET_PIPE USB-Steuercode für jeden solchen Endpunkt aus. Wenn der Befehl "Gerätestatus abrufen" fehlschlägt, gibt der Treiber eine PTP-Gerätezurücksetzungsanforderung aus. Gerätestatus und Gerätezurücksetzung sind im PIMA 15740:2000-Standard, Erste Ausgabe, sowie in der Revision 1.0 der USB Still Image Capture Device Definition (USB SICDD) beschrieben.

Der folgende Beispielcode veranschaulicht die Verwendung der vom Anbieter erweiterten Befehlsschnittstelle. Achten Sie darauf, 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 z. B. durch einen Aufruf von IWiaDevMgr::SelectDeviceDlg (in der Microsoft Windows SDK-Dokumentation beschrieben) abgerufen werden.

//
// 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.
//