Funzione ExCreateCallback (wdm.h)
La routine ExCreateCallback crea un nuovo oggetto callback o apre un oggetto callback esistente per conto del chiamante.
Sintassi
NTSTATUS ExCreateCallback(
[out] PCALLBACK_OBJECT *CallbackObject,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] BOOLEAN Create,
[in] BOOLEAN AllowMultipleCallbacks
);
Parametri
[out] CallbackObject
Puntatore a una posizione che riceve un puntatore a un oggetto callback, ovvero una struttura di sistema opaca. Se il ExCreateCallback chiamata ha esito positivo, la routine scrive l'indirizzo dell'oggetto callback appena creato o aperto in questa posizione. Il puntatore all'oggetto callback ottenuto da questa routine può essere fornito come parametro alla routine ExRegisterCallback o routine exNotifyCallback.
[in] ObjectAttributes
Puntatore a una struttura OBJECT_ATTRIBUTES che contiene gli attributi dell'oggetto di callback. Questa struttura è stata inizializzata in precedenza dalla routine InitializeObjectAttributes.
[in] Create
Indica se creare un oggetto callback. Impostare su TRUE per creare un nuovo oggetto di callback se l'oggetto richiesto non può essere aperto. In caso contrario, impostare su FALSE.
[in] AllowMultipleCallbacks
Indica se un oggetto callback appena creato deve consentire più routine di callback registrate. Impostare su TRUE per consentire più routine di callback registrate. In caso contrario, impostare su FALSE. Questo parametro viene ignorato quando Create è false o quando si apre un oggetto esistente.
Valore restituito
exCreateCallback restituisce STATUS_SUCCESS se un oggetto callback è stato aperto o creato. In caso contrario, restituisce un codice di errore NTSTATUS per indicare la natura dell'errore.
Osservazioni
Un driver chiama ExCreateCallback per creare un nuovo oggetto callback o per aprire un oggetto callback esistente. Dopo aver creato o aperto l'oggetto, altri componenti possono chiamare la routine ExRegisterCallback per registrare routine di callback con l'oggetto callback.
Prima di chiamare ExCreateCallback, il driver deve chiamare InitializeObjectAttributes per inizializzare la struttura OBJECT_ATTRIBUTES per l'oggetto di callback. Gli oggetti callback senza nome non sono consentiti. Il chiamante deve specificare un nome per l'oggetto; in caso contrario, la chiamata ha esito negativo con STATUS_UNSUCCESSFUL. Il chiamante deve specificare l'attributo OBJ_PERMANENT nell'oggetto callback per impedire l'eliminazione dell'oggetto prima che possa essere registrato con gestione oggetti. Il chiamante deve inoltre specificare qualsiasi altro attributo, ad esempio OBJ_CASE_INSENSITIVE, che potrebbe essere necessario.
Quando tutte le operazioni sono state completate con l'oggetto callback, il driver deve eliminare l'oggetto per evitare una perdita di memoria. Per informazioni sull'eliminazione di un oggetto creato con l'attributo dell'oggetto OBJ_PERMANENT, vedere ObDereferenceObject.
Nella tabella seguente vengono illustrati gli oggetti callback creati dal sistema operativo per l'uso da parte dei driver.
| Nome dell'oggetto callback | Uso |
|---|---|
| \Callback\SetSystemTime | Il sistema operativo chiama tutte le routine di callback registrate per questo oggetto ogni volta che cambia l'ora di sistema. |
| \Callback\PowerState | Il sistema operativo chiama tutte le routine di callback registrate per questo oggetto ogni volta che determinate caratteristiche di alimentazione del sistema cambiano. Quando un driver esegue la registrazione per la notifica di callback (chiamando ExRegisterCallback), può specificare le modifiche per cui deve ricevere una notifica. |
Per altre informazioni sugli oggetti callback, vedere oggetti callback.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Disponibile a partire da Windows 2000. |
| piattaforma di destinazione | Universale |
| intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| libreria | NtosKrnl.lib |
| dll | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
| regole di conformità DDI | HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm), IrqlExPassive |