Utilizzo del metodo di escape IStiUSD
Il metodo IStiUSD::Escape viene chiamato per passare le informazioni direttamente all'hardware. Questo metodo è supportato solo nei sistemi operativi Windows XP e versioni successive.
Tutte le comunicazioni tra un'applicazione compatibile con TWAIN e il driver WIA passano prima al gestore dell'origine dati (twain_32.dll), che a sua volta chiama nel livello di compatibilità TWAIN (wiadss.dll). Il livello di compatibilità TWAIN chiama quindi il metodo IStiUSD::Escape del driver WIA e passa uno dei due codici di escape seguenti al metodo :
ESC_TWAIN_CAPABILITY codice di escape
ESC_TWAIN_PRIVATE_SUPPORTED_CAPS codice di escape
Quando l'applicazione TWAIN richiede l'elenco delle funzionalità private del driver WIA, il livello di compatibilità TWAIN chiama il metodo IStiUSD::Escape del driver, passando ESC_TWAIN_PRIVATE_SUPPORTED_CAPS nella chiamata. Se il driver non supporta la funzionalità pass-through, restituisce l'elenco di funzionalità statiche (predefinite) del livello di compatibilità TWAIN. In caso contrario, il driver restituisce un elenco di funzionalità private supportate al livello di compatibilità TWAIN.
Quando l'applicazione TWAIN invia un'operazione di funzionalità non già presente nell'elenco predefinito del livello di compatibilità TWAIN, il livello di compatibilità TWAIN chiama il metodo IStiUSD::Escape del driver, questo tempo passa ESC_TWAIN_CAPABILITY nella chiamata.
Tuttavia, la spiegazione precedente è un po ' sovrasmplificata. Quando l'applicazione TWAIN richiede l'elenco delle funzionalità private del driver, il livello di compatibilità TWAIN effettua effettivamente due chiamate al metodo IStiUSD::Escape del driver. Nella prima chiamata, il livello di compatibilità TWAIN chiede al driver WIA la quantità di memoria necessaria per archiviare l'elenco delle funzionalità. Il livello di compatibilità TWAIN alloca quindi tale quantità di memoria per il driver WIA da usare. Nella seconda chiamata, il livello di compatibilità TWAIN chiede al driver WIA l'elenco delle funzionalità, copiato dal driver WIA nella memoria menzionata in precedenza. Il livello di compatibilità TWAIN è responsabile dell'allocazione e della liberazione di tutta la memoria usata nelle transazioni TWAIN-WIA. Questa disposizione impedisce al driver WIA di liberare memoria il livello di compatibilità TWAIN.
Il livello di compatibilità TWAIN chiama anche il metodo IStiUSD::Escape del driver due volte quando viene passato ESC_TWAIN_CAPABILITY e per cui la finalità consiste nel ottenere una funzionalità. La prima chiamata chiede al driver WIA la quantità di memoria necessaria per archiviare la funzionalità e la seconda chiamata restituisce la funzionalità. Si noti che le operazioni di funzionalità SET richiedono solo una singola chiamata a IStiUSD::Escape, perché non è necessario allocare memoria.
Tutte le chiamate al metodo IStiUSD::Escape devono essere convalidate in questo ordine:
Convalidare il codice della funzione EscapeFunction . Se non è valido, eseguire immediatamente l'errore. Ciò impedisce l'elaborazione di codici non corretti nel driver.
Convalidare il buffer in ingresso , lpInData. Se non è valido, eseguire immediatamente l'errore. I buffer in ingresso non validi possono causare l'arresto anomalo del driver WIA.
Convalidare il buffer in uscita , pOutData. Se non è valido, eseguire immediatamente l'errore. Se il driver non riesce a completare la richiesta scrivendo i dati necessari, non è necessario elaborare tali dati.
Convalidare le dimensioni del buffer in uscita. Se il driver non riesce a scrivere la quantità corretta di dati nel buffer in uscita, il chiamante non può elaborare correttamente tali dati.
Gli esempi di codice nelle sezioni seguenti illustrano l'uso di funzionalità pass-through, che supportano le applicazioni TWAIN con funzionalità private. Gli esempi di codice usano due codici di escape definiti nel file di intestazione wiatwcmp.h, ESC_TWAIN_PRIVATE_SUPPORTED_CAPS e ESC_TWAIN_CAPABILITY.