Comandi estesi dal fornitore
Un'applicazione può inviare un comando arbitrario al dispositivo tramite il metodo IWiaItemExtras::Escape, descritto nella documentazione di Microsoft Windows SDK. Chiamando QueryInterface nell'elemento radice, è possibile recuperare un puntatore all'interfaccia IWiaItemExtras . L'applicazione può quindi costruire un comando PTP usando qualsiasi codice opcode e parametri e inviare questo comando al dispositivo. L'applicazione può anche inviare dati a o ricevere dati dal dispositivo.
Il dispositivo informa l'applicazione del risultato dell'operazione quando il metodo IWiaItemExtras::Escape restituisce, inserendo un codice di risposta e i parametri di risposta in una struttura di PTP_VENDOR_DATA_OUT . I membri SessionId e TransactionId della struttura PTP_VENDOR_DATA_IN vengono ignorati. Il driver fornisce valori corretti per questi valori.
Per i comandi definiti dal fornitore diversi da ESCAPE_PTP_CLEAR_STALLS, un flag speciale, ESCAPE_PTP_VENDOR_COMMAND, deve essere combinato (usando un operatore OR) con il comando usato nel metodo IWiaItemExtras::Escape . Se un comando definito dal fornitore crea o elimina un oggetto nel dispositivo usando i flag descritti di seguito, il driver aggiunge o rimuove l'oggetto dalle strutture interne e genera un evento WIA. Tutti gli altri comandi standard devono essere emessi tramite l'interfaccia WIA appropriata.
Il primo parametro di IWiaItemExtras::Escape è la combinazione di uno o più flag seguenti:
| Codice di escape | Significato |
|---|---|
| ESCAPE_PTP_ADD_OBJ_CMD | Un oggetto viene aggiunto e l'handle per l'oggetto è in uno dei parametri di comando. |
| ESCAPE_PTP_REM_OBJ_CMD | Un oggetto viene rimosso e l'handle per l'oggetto si trova in uno dei parametri di comando. |
| ESCAPE_PTP_ADD_OBJ_RESP | Un oggetto viene aggiunto e l'handle per l'oggetto si trova in uno dei parametri di risposta. |
| ESCAPE_PTP_REM_OBJ_RESP | Un oggetto viene rimosso e l'handle per l'oggetto si trova in uno dei parametri di risposta. |
| ESCAPE_PTP_ADDREM_PARM1 | L'handle per l'oggetto aggiunto o rimosso è nel primo parametro del comando o della risposta. |
| ESCAPE_PTP_ADDREM_PARM2 | L'handle per l'oggetto aggiunto o rimosso è nel secondo parametro del comando o della risposta. |
| ESCAPE_PTP_ADDREM_PARM3 | L'handle per l'oggetto aggiunto o rimosso è nel terzo parametro del comando o della risposta. |
| ESCAPE_PTP_ADDREM_PARM4 | L'handle per l'oggetto aggiunto o rimosso è nel quarto parametro del comando o della risposta. |
| ESCAPE_PTP_ADDREM_PARM5 | L'handle per l'oggetto aggiunto o rimosso è nel quinto parametro del comando o della risposta. |
| ESCAPE_PTP_CLEAR_STALLS | Cancellare le condizioni di errore causate da un comando esteso dal fornitore. Questo flag non può essere usato in combinazione con uno qualsiasi degli altri flag. Per altre informazioni su questo flag, vedere la nota che segue questa tabella. |
| ESCAPE_PTP_VENDOR_COMMAND | Il comando è un comando esteso dal fornitore. |
Quando un'applicazione chiama IWiaItemExtras::Escape con il flag ESCAPE_PTP_CLEAR_STALL come primo argomento di questo metodo, il driver genera la richiesta PTP Get Device Status per determinare se gli endpoint sono in una condizione STALL. Se il comando Recupera stato dispositivo ha esito positivo, il driver genera il codice di controllo USB IOCTL_RESET_PIPE per ogni endpoint. Se il comando Recupera stato dispositivo ha esito negativo, il driver genera una richiesta di reimpostazione del dispositivo PTP. Ottenere lo stato del dispositivo e la reimpostazione del dispositivo sono descritti nella definizione del dispositivo PIMA 15740:2000 standard, First Edition e Revisione 1.0 della definizione del dispositivo USB Still Image Capture (USB SICDD).
Il codice di esempio seguente illustra come usare l'interfaccia dei comandi estesa dal fornitore. Assicurarsi che il codice includa l'intestazione ptpusd.h, perché contiene le definizioni dei codici di escape e altre costanti e le PTP_VENDOR_DATA_IN e le strutture PTP_VENDOR_DATA_OUT. L'interfaccia IWiaItemExtras viene ottenuta usando una chiamata a QueryInterface nell'elemento radice. Un puntatore a questo elemento radice, pIWiaRootItem, può essere ottenuto, ad esempio, da una chiamata a IWiaDevMgr::SelectDeviceDlg (descritta nella documentazione di Microsoft Windows SDK).
//
// 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.
//