Lettura delle proprietà dell'elemento WIA da un'applicazione

Quando un'applicazione effettua una richiesta di lettura delle proprietà dell'elemento WIA, il servizio WIA chiama il metodo IWiaMiniDrv::d rvReadItemProperties .

Il metodo IWiaMiniDrv::d rvReadItemProperties deve eseguire le attività seguenti:

1. Determinare se le proprietà in lettura richiedono aggiornamenti in fase di esecuzione. Per determinare quali proprietà WIA sono in corso di lettura, il minidriver WIA può usare la matrice PROPSPEC (definita nella documentazione di Microsoft Windows SDK). È consigliabile che il minidriver WIA determini il tipo di elemento prima di elaborare la matrice PROPSPEC. Ciò riduce la necessità di attraversare la matrice in ogni chiamata IWiaMiniDrv::d rvReadItemProperties . Se non sono presenti proprietà di runtime negli elementi figlio di questo dispositivo, verranno elaborate solo le richieste di lettura delle proprietà dell'elemento radice.

2. Aggiornare il valore corrente chiamando le funzioni del servizio wiasWriteMultiple o wiasWritePropXxx usando l'ID della proprietà WIA. Questo aggiorna il set di proprietà WIA archiviato nell'elemento del driver e il servizio WIA restituisce il nuovo valore all'applicazione.

Se il minidriver WIA non esegue alcuna regolazione di runtime per le proprietà WIA in questa funzione, il servizio WIA restituisce automaticamente solo il valore della proprietà WIA corrente all'applicazione. Questa funzione deve essere usata solo per le proprietà, ad esempio gli orologi del dispositivo o le proprietà WIA che richiedono controlli specifici dell'hardware, ad esempio lo stato del feeder di documenti.

Implementazione di IWiaMiniDrv::d rvReadItemProperties

Il metodo IWiaMiniDrv::d rvReadItemProperties viene chiamato quando un'applicazione tenta di leggere le proprietà di un elemento WIA. Il servizio WIA invia prima una notifica al driver chiamando questo metodo. Il driver WIA deve verificare che la proprietà da leggere sia corretta. Questo è un buon posto per accedere all'hardware per le proprietà che richiedono lo stato del dispositivo (ad esempio WIA_DPS_DOCUMENT_HANDLING_STATUS o WIA_DPA_DEVICE_TIME se il dispositivo supporta un orologio).

È importante notare che un driver WIA deve comunicare con l'hardware solo in rare occasioni. I driver WIA che comunicano con l'hardware troppo in questa chiamata appariranno lente e lente.

Nell'esempio seguente viene illustrata un'implementazione del metodo IWiaMiniDrv::d rvReadItemProperties :

HRESULT _stdcall CWIADevice::drvReadItemProperties(
  BYTE           *pWiasContext,
  LONG           lFlags,
  ULONG          nPropSpec,
  const PROPSPEC *pPropSpec,
  LONG           *plDevErrVal)
{

  //
  // If the caller did not pass in the correct parameters,
  // then fail the call with E_INVALIDARG.
  //

  if (!pWiasContext) {
      return E_INVALIDARG;
  }

  if (!plDevErrVal) {
      return E_INVALIDARG;
  }

  if (!pPropSpec) {
      return E_INVALIDARG;
  }

  *plDevErrVal = 0;

  LONG lWIAItemType = 0;
  HRESULT hr = wiasGetItemType(pWiasContext,&lWIAItemType);
  if(S_OK == hr) {
    //
    // perform custom operations depending on the type of
    // WIA item that was passed to drvReadItemProperties
    //

      if(lWIAItemType & WiaItemTypeRoot) {
      //
      // If the WIA_DPA_CONNECT_STATUS property ID is in the PROPSPEC
      // array, then read the latest "Connect Status".
      // If it is NOT then do nothing. (skip access to the hardware)
      //
      // NOTE: only read properties contained in the PROPSPEC array
      //     from the hardware that need device updates.
      //     If the property in PROPSPEC does not need to be read
      //     from the hardware, or updated, do nothing. The WIA service
      //     will supply the caller with the current value in the
      //     the WIA property set.
      //

          BOOL bReadLatestConnectStatus = FALSE;

      //
      // traverse the WIA PROPSPEC array, looking for known WIA
      // properties that require run-time updates, or needs to be
      // updated with hardware access.
      //

          for(ULONG ulIndex = 0; ulIndex < nPropSpec; ulIndex++) {

        //
        // look for WIA property IDs that really need hardware
        // access, or run-time adjusting.
        //

              if(pPropSpec[ulIndex].propid == WIA_DPA_CONNECT_STATUS) {
                  bReadLatestConnectStatus = TRUE;
              }
          }

        //
        // The item passed in is a ROOT item
        //

         if(bReadLatestConnectStatus) {

            //
            // WIA_DPA_CONNECT_STATUS should be updated from the
            // hardware
            //

 LONG lConnectStatus = HARDWARE_READ_ConnectStatus();

            //
            // update WIA_DPA_CONNECT_STATUS property value using
            // wiasWritePropLong ().  The pWiasContext passed in
            // already represents the current item to be written to.
            //

              hr = wiasWritePropLong(pWiasContext,WIA_DPA_CONNECT_STATUS,lConnectStatus);
              if(S_OK == hr) {

                //
                // The WIA_DPA_CONNECT_STATUS property was successfully updated
                //

              } else {

                //
                //  wiasWritePropLong() failed to write the WIA 
                //  property.  The WIA_DPA_CONNECT_STATUS
                //  property was NOT updated
                //

              }
          }

      } else {

        //
        // The item passed in is any other child item
        //

      }
  } else {

    //
    // wiasGetItemType() failed to get the current item type
    //
  }

  return hr;
}