Funzione ObCloseHandle (wdm.h)
La routine ObCloseHandle chiude un handle di oggetto.
Sintassi
NTSTATUS ObCloseHandle(
[in] HANDLE Handle,
[in] KPROCESSOR_MODE PreviousMode
);
Parametri
[in] Handle
Handle per un oggetto fornito dal sistema di qualsiasi tipo.
[in] PreviousMode
Specifica la modalità del processore precedente del thread che ha aperto l'handle. Per chiudere un handle del kernel impostare questo parametro su KernelMode. Per chiudere un handle utente, impostare questo parametro su UserMode. Per altre informazioni su questi due tipi di handle, vedere Osservazioni.
Valore restituito
ObCloseHandle restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti di errore possibili includono i codici NTSTATUS seguenti.
| Codice restituito | Descrizione |
|---|---|
| STATUS_INVALID_HANDLE | Handle non è un handle valido. |
| STATUS_HANDLE_NOT_CLOSABLE | Il thread chiamante non dispone dell'autorizzazione per chiudere l'handle. |
Commenti
Un driver in modalità kernel chiama ObCloseHandle per chiudere un handle a qualsiasi tipo di oggetto creato dal kernel di Windows. Un driver deve chiudere ogni handle che si apre non appena l'handle non è più necessario.
Dopo che ObCloseHandle chiude l'handle di un oggetto, il chiamante deve considerare l'handle come non valido ed evitare di usare l'handle per accedere all'oggetto. Tuttavia, altri handle potrebbero rimanere aperti sullo stesso oggetto. Durante una chiamata ObCloseHandle , il sistema decrementa il numero di handle per l'oggetto e controlla se l'oggetto può essere eliminato. Il sistema non elimina l'oggetto finché tutti gli handle dell'oggetto non vengono chiusi e tutti i puntatori con conteggio dei riferimenti all'oggetto non vengono rilasciati.
Il parametro PreviousMode specifica se l'handle da chiudere è un handle del kernel o un handle utente. Per chiudere un handle del kernel, impostare PreviousMode su KernelMode. Per chiudere un handle utente, impostare PreviousMode su UserMode.
Un handle del kernel è un handle aperto da un thread di sistema o da un driver in modalità kernel che assegna l'attributo OBJ_KERNEL_HANDLE all'handle. Ad esempio, vedere la descrizione di OBJ_KERNEL_HANDLE in ZwCreateFile. Se un driver in modalità kernel apre un handle per l'uso privato e questo driver viene eseguito nel contesto di un thread in modalità utente, il driver deve aprire l'handle con l'attributo OBJ_KERNEL_HANDLE. Questo attributo garantisce che l'handle non sia accessibile alle applicazioni in modalità utente.
Un handle utente è un handle aperto da un'applicazione in modalità utente o da un driver in modalità kernel eseguito nel contesto di un thread in modalità utente, ma che non apre l'handle con l'attributo OBJ_KERNEL_HANDLE. Se un driver crea un handle utente da usare da un'applicazione in modalità utente, ma si verifica un errore che richiede al driver di chiudere l'handle per conto dell'applicazione, il driver può chiamare ObCloseHandle per chiudere l'handle.
La routine ZwClose è simile a ObCloseHandle , ma può chiudere solo gli handle del kernel. La chiamata ZwClose(hObject), che chiude l'handle del kernel hObject, ha lo stesso effetto della chiamata ObCloseHandle(hObject, KernelMode). Per altre informazioni sulla chiusura di un handle del kernel, vedere ZwClose.
Per determinare se un handle è un handle del kernel o un handle utente, un driver che riceve un handle può chiamare la routine ExGetPreviousMode . In alternativa, il driver può leggere il campo RequestorMode dalla struttura IRP che descrive la richiesta di I/O. Il gestore di I/O imposta il campo RequestorMode sulla modalità processore precedente del thread che ha richiesto l'operazione di I/O.
I chiamanti di ObCloseHandle non devono presupporre che questa routine attenda automaticamente il completamento di tutte le operazioni di I/O in sospeso prima che venga restituito.
Per altre informazioni, vedere Handle di oggetti.
ObCloseHandle non è dichiarato in un file di intestazione prima di Windows 7. Per usare questa routine nel driver, includere la dichiarazione di funzione seguente nel codice del driver:
#if (NTDDI_VERSION < NTDDI_WIN7)
NTKERNELAPI
NTSTATUS
ObCloseHandle(
__in HANDLE Handle,
__in KPROCESSOR_MODE PreviousMode
);
#endif
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Intestazione | wdm.h |
| Libreria | Ntoskrnl.lib |
| DLL | Ntoskrnl.exe |
| IRQL | PASSIVE_LEVEL |