Metodo IAdapterPowerManagement::QueryDeviceCapabilities (portcls.h)

Articolo
02/07/2025

Il metodo QueryDeviceCapabilities viene chiamato da PortCls in risposta a un plug and play IRP_MN_QUERY_CAPABILITIES IRP.

Sintassi

NTSTATUS QueryDeviceCapabilities(
  [in] PDEVICE_CAPABILITIES PowerDeviceCaps
);

Parametri

[in] PowerDeviceCaps

Puntatore a una struttura DEVICE_CAPABILITIES che specifica le funzionalità del dispositivo

Valore restituito

QueryDeviceCapabilities restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. In caso contrario, il metodo restituisce un codice di errore appropriato.

Osservazioni

Questo metodo viene chiamato all'avvio del driver per ottenere le funzionalità per il dispositivo. Il metodo passa al driver dell'adattatore una struttura di funzionalità che definisce i mapping tra stati di alimentazione del sistema e stati di alimentazione del dispositivo. PortCls scrive i valori predefiniti per questi mapping nella struttura prima di chiamare il metodo . Durante la chiamata, il driver dell'adattatore ha la possibilità di modificare i mapping, se necessario.

In genere, il driver dell'adattatore non deve modificare queste impostazioni. Se il driver dell'adattatore deve eseguire l'override delle impostazioni predefinite, può modificare i mapping a uno stato di alimentazione del dispositivo più profondo (meno alimentato), ma non a uno stato di alimentazione del dispositivo più debole (più alimentato). Ad esempio, i mapping per S1 (PowerSystemSleeping1) possono essere modificati da D1 a D3, ma non in D0.

Per compilare la struttura di PowerDeviceCaps per un dispositivo, il driver della scheda deve chiamare PcRegisterAdapterPowerManagement per registrare l'interfaccia IAdapterPowerManagement in fase di avvio del dispositivo. Il sistema operativo esegue una query sui dispositivi prima di chiamare la routine di avvio del dispositivo del driver dell'adattatore.

Per modificare i mapping tra stati di alimentazione del sistema e stato di alimentazione del dispositivo, il driver dell'adattatore modifica i valori nella matrice DeviceState nella struttura PowerDeviceCaps. Questi mapping devono essere modificati solo se necessario. L'esempio di codice seguente illustra come eseguire il mapping dei mapping D1 a D3:

  for (i=ULONG(PowerSystemWorking); i<=ULONG(PowerSystemShutdown); i++)
      {
          if (PowerDeviceCaps->DeviceState[i] == PowerDeviceD1)
          {
              PowerDeviceCaps->DeviceState[i] = PowerDeviceD3;
          }
      }

Il codice per il metodo QueryDeviceCapabilities deve risiedere nella memoria di paging.