Fonction IoCreateSystemThread (wdm.h)
La routine IoCreateSystemThread crée un thread système qui s’exécute en mode noyau et fournit un handle pour le thread.
Syntaxe
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
);
Paramètres
[in, out] IoObject
Pointeur vers le DEVICE_OBJECT ou le DRIVER_OBJECT à associer au thread créé. IoCreateSystemThread prend une référence comptée à cet objet. Le gestionnaire d’E/S publie ultérieurement cette référence à la sortie du thread. Pour plus d'informations, consultez la section Notes.
[out] ThreadHandle
Pointeur vers une variable dans laquelle la routine écrit le handle du noyau pour le thread créé. Lorsque la poignée n’est plus nécessaire, le pilote doit fermer la poignée en appelant la routine ZwClose .
[in] DesiredAccess
Valeur ACCESS_MASK qui représente les types d’accès que l’appelant demande au thread créé.
[in, optional] ObjectAttributes
Pointeur vers une structure OBJECT_ATTRIBUTES qui spécifie les attributs de l’objet thread. Les attributs OBJ_PERMANENT, OBJ_EXCLUSIVE et OBJ_OPENIF ne sont pas des attributs valides pour un objet thread. Si l’appelant n’est pas en cours d’exécution dans le contexte du processus système, il doit définir l’attribut OBJ_KERNEL_HANDLE dans la structure OBJECT_ATTRIBUTES .
[in, optional] ProcessHandle
Handle ouvert pour le processus dans lequel le thread créé doit exécuter l’espace d’adressage. Le thread de l’appelant doit avoir PROCESS_CREATE_THREAD accès à ce processus. Si ce paramètre a la valeur NULL, le thread est créé dans le processus système initial. Ce paramètre doit avoir la valeur NULL pour un thread créé par un pilote. Utilisez la macro NtCurrentProcess , définie dans le fichier d’en-tête Wdm.h, pour spécifier le processus en cours.
[out, optional] ClientId
Pointeur vers une structure dans laquelle la routine écrit l’identificateur client pour le thread créé. Ce paramètre doit avoir la valeur NULL pour un thread créé par un pilote.
[in] StartRoutine
Pointeur vers une routine ThreadStart qui est le point d’entrée du thread créé.
[in, optional] StartContext
Pointeur de contexte qui est passé en tant que paramètre StartContext à la routine ThreadStart lorsque le thread créé commence à s’exécuter.
Valeur retournée
IoCreateSystemThread retourne STATUS_SUCCESS si le nouveau thread a été créé avec succès. Les valeurs de retour possibles incluent les codes de status d’erreur suivants.
| Code de retour | Description |
|---|---|
| STATUS_INVALID_HANDLE | ProcessHandle n’est pas un handle de processus valide. |
| STATUS_PROCESS_IS_TERMINATING | Le processus spécifié par ProcessHandle se termine. |
| STATUS_INSUFFICIENT_RESOURCES | Les ressources système sont insuffisantes pour effectuer l’opération demandée. |
Remarques
À compter de Windows 8, un pilote peut appeler IoCreateSystemThread pour créer un thread dédié à l’appareil. Cette routine crée un thread système qui n’a pas de bloc d’environnement de thread (TEB) ou de contexte en mode utilisateur, et qui s’exécute uniquement en mode noyau.
En règle générale, le pilote appelle IoCreateSystemThread au démarrage de l’appareil ou lorsque les routines DispatchXxx du pilote commencent à recevoir des demandes d’E/S. Par exemple, un pilote peut appeler cette routine pour créer un thread lorsqu’une routine DispatchXxx reçoit une demande de contrôle d’appareil asynchrone.
Si le paramètre ProcessHandle a la valeur NULL, le thread créé est associé au processus système. Un tel thread continue de s’exécuter jusqu’à ce que le système soit arrêté ou que le thread se ferme.
Les routines de pilote qui s’exécutent dans un contexte de processus autre que celui du processus système doivent définir l’attribut OBJ_KERNEL_HANDLE pour le paramètre ObjectAttributesd’IoCreateSystemThread. Cet attribut limite l’utilisation du handle retourné par IoCreateSystemThread aux processus s’exécutant en mode noyau. Sinon, le handle de thread est accessible par le processus dans lequel le pilote est en cours d’exécution. Les pilotes peuvent appeler la macro InitializeObjectAttributes pour définir l’attribut OBJ_KERNEL_HANDLE dans les attributs d’objet, comme illustré dans l’exemple de code suivant.
OBJECT_ATTRIBUTES ObjectAttributes;
InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);
IoCreateSystemThread est similaire à la routine PsCreateSystemThread , mais a un paramètre supplémentaire, IoObject, qui est un pointeur vers l’objet de pilote ou l’objet d’appareil de l’appelant. IoCreateSystemThread utilise ce paramètre pour s’assurer que le pilote ne peut pas se décharger tant que le thread créé existe. Avant de planifier l’exécution de StartRoutine dans ce thread, IoCreateSystemThread prend une référence comptée à l’objet IoObject . Le gestionnaire d’E/S libère cette référence après la sortie du thread créé. Par conséquent, cet objet persiste pendant la durée de vie du thread créé.
Contrairement à un thread système créé par la routine PsCreateSystemThread , un thread créé par IoCreateSystemThread n’appelle pas la routine PsTerminateSystemThread pour se terminer elle-même. Au lieu de cela, le gestionnaire d’E/S appelle PsTerminateSystemThread au nom du thread créé à la sortie du thread.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible à partir de Windows 8. |
| Plateforme cible | Universal |
| En-tête | wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h) |
| Bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |