Funzione PoFxRegisterDevice (wdm.h)
La routine PoFxRegisterDevice registra un dispositivo con il framework di risparmio energia (PoFx).
Sintassi
NTSTATUS PoFxRegisterDevice(
[in] PDEVICE_OBJECT Pdo,
[in] PPO_FX_DEVICE Device,
[out] POHANDLE *Handle
);
Parametri
[in] Pdo
Puntatore a un oggetto dispositivo fisico (PDO). Questo parametro punta a una struttura DEVICE_OBJECT che rappresenta il dispositivo fisico registrato. Il chiamante è il proprietario del criterio di alimentazione per il dispositivo, che è in genere il driver di funzione del dispositivo.
[in] Device
Puntatore a una struttura PO_FX_DEVICE allocata dal chiamante che contiene le informazioni di registrazione per il dispositivo. Questa struttura contiene puntatori a un set di routine di callback implementate dal driver di dispositivo. PoFx chiama queste routine per comunicare con il driver.
[out] Handle
Puntatore a una posizione in cui la routine scrive un handle che rappresenta la registrazione del dispositivo con PoFx. Il driver del dispositivo passa questo handle come parametro di input alle altre routine PoFxXxx chiamate. Il driver deve prima chiamare PoFxRegisterDevice per registrare il dispositivo prima che il driver chiami qualsiasi altra routine PoFxXxx per gestire il dispositivo.
Valore restituito
PoFxRegisterDevice restituisce STATUS_SUCCESS se la routine registra correttamente il dispositivo. I valori restituiti degli errori possibili includono i codici di stato seguenti.
Codice restituito | Descrizione |
---|---|
|
Pdo è NULL; o la struttura PPO_FX_DEVICE ha un numero di versione non valido o un numero di componenti pari a zero; o il numero di stati inattive specificati per un componente è zero; o la descrizione di uno stato inattiva non è valida. |
|
Il dispositivo non è pronto. |
|
Sono disponibili risorse insufficienti per completare la registrazione. |
Commenti
Un driver di dispositivo chiama in genere questa routine dal gestore della richiesta di IRP_MN_START_DEVICE del driver. Il driver non deve chiamare questa routine prima che il dispositivo riceva una richiesta di IRP_MN_START_DEVICE . Il dispositivo riceve la prima richiesta di IRP_MN_START_DEVICE quando il dispositivo viene avviato per la prima volta. Il dispositivo riceve una richiesta di IRP_MN_START_DEVICE aggiuntiva ogni volta che il dispositivo viene riavviato dopo essere stato arrestato per il bilanciamento delle risorse. Una chiamata PoFxRegisterDevice per registrare un dispositivo già registrato è un errore irreversibile e causa un controllo di bug. Si noti che PoFx esegue una copia approfondita delle strutture del dispositivo nella memoria.
Prima che il driver chiami PoFxRegisterDevice, il dispositivo deve soddisfare le condizioni seguenti:
- Il dispositivo (ovvero il PDO) non è già registrato con PoFx.
- Il dispositivo si trova nello stato di alimentazione D0 (completamente attivo).
- Il dispositivo si trova nella condizione di esecuzione.
- Ogni componente del dispositivo si trova nello stato di alimentazione F0 (completamente attivo).
- Ogni componente si trova nella condizione attiva.
Dopo che un driver chiama PoFxRegisterDevice per registrare un dispositivo con PoFx, tutti i componenti del dispositivo sono completamente attivi e nella condizione attiva in modo che il driver possa completare l'inizializzazione dell'hardware. Per avviare il risparmio energia attivo, il driver deve chiamare la routine PoFxStartDevicePowerManagement .
Per impostazione predefinita, PoFxStartDevicePowerManagement passa tutti i componenti alla condizione inattiva. Se il driver richiede che un componente si trova nella condizione attiva immediatamente dopo l'avvio della gestione energia, il driver deve attivare esplicitamente il componente chiamando la routine PoFxActivateComponent e questa chiamata deve verificarsi dopo la chiamata PoFxRegisterDevice , ma prima della chiamata PoFxStartDevicePowerManagement .
In genere, il driver Kernel-Mode Driver Framework (KMDF) per un dispositivo a componente singolo non chiama PoFxRegisterDevice per registrare il dispositivo con PoFx. Invece, questo driver riceve un handle di registrazione PoFx quando kmDF chiama la funzione di callback del driver EvtDeviceWdmPostPoFxRegisterDevice . Per altre informazioni, vedere Supporto di più stati di alimentazione funzionale per i dispositivi Single-Component.
Per informazioni sul modo in cui il driver kmDF per un dispositivo a più componenti viene registrato con PoFx, vedere Supporto di più stati di alimentazione funzionale per i dispositivi Multiple-Component.
Requisiti
Requisito | Valore |
---|---|
Client minimo supportato | Disponibile a partire da Windows 8. |
Piattaforma di destinazione | Universale |
Intestazione | wdm.h |
Libreria | Ntoskrnl.lib |
DLL | Ntoskrnl.exe |
IRQL | PASSIVE_LEVEL |