Funzione ExRegisterCallback (wdm.h)

La routine ExRegisterCallback registra una determinata routine di callback con un determinato oggetto callback.

Sintassi

PVOID ExRegisterCallback(
  [in, out]      PCALLBACK_OBJECT   CallbackObject,
  [in]           PCALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID              CallbackContext
);

Parametri

[in, out] CallbackObject

Puntatore a un oggetto callback ottenuto dalla routine ExCreateCallback .

[in] CallbackFunction

Puntatore a una routine di callback implementata dal driver, che deve essere non modificabile. La routine di callback deve essere conforme al prototipo seguente:

VOID
(*PCALLBACK_FUNCTION ) (
    IN PVOID CallbackContext,
    IN PVOID Argument1,
    IN PVOID Argument2
    );

I parametri di routine di callback sono i seguenti:

CallbackContext

Puntatore a un'area di contesto fornita dal driver come specificato nel parametro CallbackContext di ExRegisterCallback.

Argomento1

Puntatore a un parametro definito dall'oggetto callback.

Argomento2

Puntatore a un parametro definito dall'oggetto callback.

[in, optional] CallbackContext

Puntatore a una struttura definita dal chiamante di elementi di dati da passare come parametro di contesto della routine di callback ogni volta che viene chiamata. In genere il contesto fa parte dell'estensione dell'oggetto dispositivo del chiamante.

Valore restituito

ExRegisterCallback restituisce un puntatore a un handle di registrazione di callback che deve essere considerato opaco e riservato per l'uso del sistema. Questo puntatore è NULL se ExRegisterCallback viene completato con un errore.

Commenti

Un driver chiama ExRegisterCallback per registrare una routine di callback con un oggetto callback specificato.

Se l'oggetto consente una sola routine di callback registrata e tale routine è già registrata, ExRegisterCallback restituisce NULL.

I chiamanti di ExRegisterCallback devono salvare il puntatore restituito da usare in un secondo momento in una chiamata a ExUnregisterCallback. Il puntatore è necessario quando si rimuove la routine di callback dall'elenco di routine di callback registrate per l'oggetto callback.

I significati di Argument1 e Argument2 della routine di callback registrata dipendono dall'oggetto callback e vengono definiti dal componente che lo ha creato. Di seguito sono riportati i parametri per gli oggetti di callback definiti dal sistema:

\Callback\SetSystemTime

Argument1 (SetSystemTime)

  • Non usato.

Argument2 (SetSystemTime)

  • Non usato.

\Callback\PowerState**

Argument1 (PowerState)

  • Valore costante PO_CB_XXX di cui viene eseguito il cast al tipo PVOID.

  • PO_CB_AC_STATUS : indica che il sistema è cambiato da A/C a batteria o viceversa.

  • PO_CB_LID_SWITCH_STATE : indica che l'interruttore del coperchio è stato modificato.

  • PO_CB_PROCESSOR_POWER_POLICY : indica che i criteri di alimentazione del processore di sistema sono stati modificati.

  • PO_CB_SYSTEM_POWER_POLICY : indica che i criteri di risparmio energia del sistema sono stati modificati.

  • PO_CB_SYSTEM_STATE_LOCK : indica che una modifica dello stato di alimentazione del sistema è imminente. I driver nel percorso di paging possono registrarsi per questo callback per ricevere un avviso anticipato di tale modifica, consentendo loro di bloccare il codice in memoria prima che lo stato di alimentazione cambi.

Argument2 (PowerState)

Valore TRUE o FALSE di cui viene eseguito il cast al tipo PVOID.

  • Se Argument1 è PO_CB_AC_STATUS, Argument2 è TRUE se il computer utilizza attualmente un alimentatore A/C ed è FALSE se il computer è in esecuzione con alimentazione a batteria.

  • Se Argument1 è PO_CB_LID_SWITCH_STATE, Argument2 è TRUE se il coperchio è attualmente aperto ed è FALSE se il coperchio è chiuso.

  • Se Argument1 è PO_CB_PROCESSOR_POWER_POLICY, Argument2 non viene utilizzato.

  • Se Argument1 è PO_CB_SYSTEM_POWER_POLICY, Argument2 non viene utilizzato.

  • Se Argument1 è PO_CB_SYSTEM_STATE_LOCK, Argument2 è FALSE se il computer sta per uscire dallo stato di alimentazione del sistema S0 ed è TRUE se il computer ha appena immesso S0.

\Callback\ProcessorAdd

Argument1 (ProcessorAdd)

  • Puntatore a una struttura di KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT che descrive l'evento di notifica delle modifiche del processore. Questo puntatore viene eseguito il cast al tipo PVOID. La routine di callback non deve modificare il contenuto di questa struttura.

Argument2 (ProcessorAdd)

Puntatore a una variabile che contiene un valore NTSTATUS. Questo puntatore viene eseguito il cast al tipo PVOID. In determinate condizioni, una routine di callback può scrivere un valore di stato di errore in questa variabile per indicare il motivo per cui il nuovo processore non deve essere aggiunto. Un driver di dispositivo non deve modificare il valore di questa variabile, a meno che non siano soddisfatte tutte e tre le condizioni seguenti:

  • Si verifica un errore durante l'elaborazione della routine di callback che dovrebbe impedire l'aggiunta del nuovo processore.

  • Il valore del membro State della struttura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a cui Argument1 punta è KeProcessorAddStartNotify.

  • Variabile NSTATUS che Argument2 punta a contiene il valore STATUS_SUCCESS. Ovvero, la routine di callback non deve sovrascrivere un valore di stato di errore scritto in precedenza da un altro client di notifica di callback.

A partire da Windows Vista, l'oggetto callback\ProcessorAdd è disponibile per tenere traccia dinamicamente delle modifiche nel popolamento del processore. La routine KeRegisterProcessorChangeCallback fornisce informazioni simili, ma supporta anche un flag di KE_PROCESSOR_CHANGE_ADD_EXISTING che un driver può usare per enumerare i processori nella configurazione iniziale del sistema multiprocessore. Per i driver eseguiti in Windows Server 2008 e versioni successive di Windows, usare KeRegisterProcessorChangeCallback anziché l'oggetto callback\ProcessorAdd , se possibile.

Per altre informazioni sugli oggetti di callback, vedere Oggetti di callback.

Il sistema operativo chiama routine di callback registrate nello stesso IRQL in cui il driver che ha creato il callback denominato routine ExNotifyCallback .

Requisiti

Requisito Valore
Piattaforma di destinazione Universale
Intestazione wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria NtosKrnl.lib
DLL NtosKrnl.exe
IRQL IRQL <= APC_LEVEL
Regole di conformità DDI HwStorPortProhibitedDDDIs(storport), IrqlExApcLte2(wdm)

Vedi anche

ExCreateCallback

ExNotifyCallback

ExUnregisterCallback

KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT

KeRegisterProcessorChangeCallback