Aggiungere il supporto per gli eventi di polling

Per configurare correttamente il driver WIA per segnalare gli eventi di polling, eseguire le operazioni seguenti:

1. Impostare Capabilities=0x33 nel file INF del dispositivo. Per informazioni dettagliate, vedere File INF per dispositivi WIA .

2. Segnalare STI_GENCAP_NOTIFICATIONS e STI_USD_GENCAP_NATIVE_PUSHSUPPORT nel metodo IStiUSD::GetCapabilities .

3. Segnalare tutti gli eventi supportati nel metodo IWiaMiniDrv::d rvGetCapabilities .

4. Rispondere alle chiamate al metodo IStiUSD::GetStatus . Il servizio WIA chiama questo metodo a un intervallo predefinito configurabile nel file INF. L'impostazione predefinita è un intervallo di 1 secondo.

5. Segnalare la risposta corretta alle informazioni sugli eventi nel metodo IStiUSD::GetNotificationData .

Il servizio WIA chiama il metodo IStiUSD::GetStatus per due operazioni principali:

1. Verifica dello stato online del dispositivo.

2. Polling per gli eventi del dispositivo, ad esempio un evento pulsante di selezione.

Determinare la richiesta di operazione può essere eseguita controllando il membro StatusMask della struttura STI_DEVICE_STATUS . Il membro StatusMask può essere una delle richieste seguenti:

STI_DEVSTATUS_ONLINE_STATE
Questa richiesta di operazione controlla se il dispositivo è online e deve essere compilato impostando il membro dwOnlinesState della struttura STI_DEVICE_STATUS.

STI_DEVSTATUS_EVENTS_STATE
Questa richiesta di operazione verifica la presenza di eventi del dispositivo. Deve essere compilato impostando il membro dwEventHandlingState della struttura STI_DEVICE_STATUS. Il valore che deve essere utilizzato è STI_EVENTHANDLING_PENDING. Il dispositivo ha un evento in sospeso e è in attesa di segnalarlo al servizio WIA.

Quando STI_EVENTHANDLING_PENDING è impostato, il servizio WIA segnala che si è verificato un evento nel driver WIA. Il servizio WIA chiama il metodo IStiUSD::GetNotificationData per ottenere altre informazioni sull'evento.

Il metodo IStiUSD::GetNotificationData viene chiamato per gli eventi di polling e gli eventi di interrupt. Si tratta di questo metodo che è necessario compilare le informazioni sull'evento appropriate per tornare al servizio WIA.

Nota Deselezionare sempre il flag STI_EVENTHANDLING_PENDING nel membro dwEventHandlingState per assicurarsi che venga impostato correttamente quando si verifica un evento del dispositivo. Questo driver WIA deve impostare la variabile membro della classe m_guidLastEvent sul GUID dell'evento appropriato quando viene rilevato un evento. Il m_guidLastEvent viene controllato in un secondo momento quando il servizio WIA chiama il metodo IStiUSD::GetNotificationData . La variabile membro m_guidLastEvent è definita nella classe CWIADevice (nel frammento di codice seguente), usata per memorizzare nella cache l'ultimo evento segnalato. Dopo che questa variabile membro è stata richiesta dal servizio WIA, viene sempre impostata su GUID_NULL.

L'esempio seguente illustra un'implementazione del metodo IStiUSD::GetStatus .

STDMETHODIMP CWIADevice::GetStatus(PSTI_DEVICE_STATUS pDevStatus)
{
  //
  // If the caller did not pass in the correct parameters,
  // then fail the call with E_INVALIDARG.
  //

  if(!pDevStatus)
  {
      return E_INVALIDARG;
  }

  HRESULT hr = S_OK;

  //
  // If we are asked, verify state of an event handler 
  //(front panel buttons, user controlled attachments, etc.).
  //
  // If your device requires polling, then this is where you would
  // specify the event result.
  // However, It is not recommended to have polled events.
  // Interrupt events are better for performance, and reliability.
  // See the SetNotificationsHandle method for how to
  // implement interrupt events.
  //

  //
  // clear the dwEventHandlingState field first to make sure we are really setting
  // a pending event.
  //

  pDevStatus->dwEventHandlingState &= ~STI_EVENTHANDLING_PENDING;
  if (pDevStatus->StatusMask & STI_DEVSTATUS_EVENTS_STATE) {

    //
    // set the polled event result here, for the GetNotificationData()
    // method to read and report.
    // (m_guidLastEvent will be read in GetNotificationData)
    //

    LONG lEventResult = 0;
    PollMyDeviceForEvents(&lEventResult)

    if(lEventResult == DEVICE_SCAN_BUTTON_PRESSED) {

        //
        // polled event result was one we know about
        //

        m_guidLastEvent = WIA_EVENT_SCAN_IMAGE;
    } else {

        //
        // nothing happened, so continue
        //

        m_guidLastEvent = GUID_NULL;
    }

    if (m_guidLastEvent != GUID_NULL) {

        //
        // if the event GUID is NOT GUID_NULL, set the
        // STI_EVENTHANDLING_PENDING flag letting the WIA service
        // know that we have an event ready. This will tell the WIA
        // service to call GetNotificationData() for the event
        // specific information.
        //

        pDevStatus->dwEventHandlingState |= STI_EVENTHANDLING_PENDING;
    }
  }
  return S_OK;
}