Funzione IoCreateSystemThread (wdm.h)
La routine IoCreateSystemThread crea un thread di sistema che esegue in modalità kernel e fornisce un handle per il thread.
Sintassi
NTSTATUS IoCreateSystemThread(
[in, out] PVOID IoObject,
[out] PHANDLE ThreadHandle,
[in] ULONG DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] HANDLE ProcessHandle,
[out, optional] PCLIENT_ID ClientId,
[in] PKSTART_ROUTINE StartRoutine,
[in, optional] PVOID StartContext
);
Parametri
[in, out] IoObject
Puntatore al DEVICE_OBJECT o DRIVER_OBJECT da associare al thread creato. IoCreateSystemThread accetta un riferimento conteggiato a questo oggetto. Il gestore di I/O rilascia in seguito questo riferimento quando il thread viene chiuso. Per altre informazioni, vedere la sezione Osservazioni.
[out] ThreadHandle
Puntatore a una variabile a cui la routine scrive l'handle del kernel per il thread creato. Quando l'handle non è più necessario, il driver deve chiudere l'handle chiamando la routine ZwClose .
[in] DesiredAccess
Valore ACCESS_MASK che rappresenta i tipi di accesso alle richieste del chiamante al thread creato.
[in, optional] ObjectAttributes
Puntatore a una struttura OBJECT_ATTRIBUTES che specifica gli attributi dell'oggetto thread. Gli attributi OBJ_PERMANENT, OBJ_EXCLUSIVE e OBJ_OPENIF non sono validi per un oggetto thread. Se il chiamante non è in esecuzione nel contesto del processo di sistema, deve impostare l'attributo OBJ_KERNEL_HANDLE nella struttura OBJECT_ATTRIBUTES .
[in, optional] ProcessHandle
Handle aperto per il processo nel cui spazio indirizzi è necessario eseguire il thread creato. Il thread del chiamante deve avere PROCESS_CREATE_THREAD accesso a questo processo. Se questo parametro è NULL, il thread verrà creato nel processo di sistema iniziale. Questo parametro deve essere NULL per un thread creato dal driver. Usare la macro NtCurrentProcess , definita nel file di intestazione Wdm.h, per specificare il processo corrente.
[out, optional] ClientId
Puntatore a una struttura a cui la routine scrive l'identificatore client per il thread creato. Questo parametro deve essere NULL per un thread creato dal driver.
[in] StartRoutine
Puntatore a una routine ThreadStart che rappresenta il punto di ingresso per il thread creato.
[in, optional] StartContext
Puntatore di contesto passato come parametro StartContext alla routine ThreadStart quando il thread creato inizia a essere eseguito.
Valore restituito
IoCreateSystemThread restituisce STATUS_SUCCESS se il nuovo thread è stato creato correttamente. I valori restituiti possibili includono i codici di stato degli errori seguenti.
| Codice restituito | Descrizione |
|---|---|
| STATUS_INVALID_HANDLE | ProcessHandle non è un handle di processo valido. |
| STATUS_PROCESS_IS_TERMINATING | Il processo specificato da ProcessHandle termina. |
| STATUS_INSUFFICIENT_RESOURCES | Sono disponibili risorse di sistema insufficienti per eseguire l'operazione richiesta. |
Commenti
A partire da Windows 8, un driver può chiamare IoCreateSystemThread per creare un thread dedicato al dispositivo. Questa routine crea un nuovo thread di sistema senza blocchi di ambiente thread (TEB) o contesto in modalità utente e viene eseguito solo in modalità kernel.
In genere, il driver chiama IoCreateSystemThread quando avvia il dispositivo o quando le routine Dispatch Xxx deldriver iniziano a ricevere richieste di I/O. Ad esempio, un driver potrebbe chiamare questa routine per creare un thread quando una routine DispatchXxx riceve una richiesta di controllo del dispositivo asincrona.
Se il parametro ProcessHandle è NULL, il thread creato è associato al processo di sistema. Tale thread continua a essere in esecuzione finché il sistema non viene arrestato o il thread viene chiuso.
Le routine del driver eseguite in un contesto di processo diverso da quello del processo di sistema devono impostare l'attributo OBJ_KERNEL_HANDLE per il parametro ObjectAttributes di IoCreateSystemThread. Questo attributo limita l'uso dell'handle restituito da IoCreateSystemThread per i processi in esecuzione in modalità kernel. In caso contrario, l'handle del thread può essere accessibile dal processo nel cui contesto è in esecuzione il driver. I driver possono chiamare la macro InitializeObjectAttributes per impostare l'attributo OBJ_KERNEL_HANDLE negli attributi dell'oggetto, come illustrato nell'esempio di codice seguente.
OBJECT_ATTRIBUTES ObjectAttributes;
InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);
IoCreateSystemThread è simile alla routine PsCreateSystemThread , ma ha un parametro aggiuntivo, IoObject, che è un puntatore all'oggetto driver o al dispositivo del chiamante. IoCreateSystemThread usa questo parametro per assicurarsi che il driver non possa scaricare mentre esiste il thread creato. Prima di pianificare l'esecuzione di StartRoutine in questo thread, IoCreateSystemThread accetta un riferimento conteggiato all'oggetto IoObject . Gestione I/O rilascia questo riferimento dopo l'uscita dal thread creato. Pertanto, questo oggetto persiste per la durata del thread creato.
Al contrario di un thread di sistema creato dalla routine PsCreateSystemThread , un thread creato da IoCreateSystemThread non chiama la routine PsTerminateSystemThread per terminare se stessa. Al contrario, il gestore I/O chiama PsTerminateSystemThread per conto del thread creato quando il thread viene chiuso.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile a partire da Windows 8. |
| Piattaforma di destinazione | Universale |
| Intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Libreria | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |