Fonction IoCreateSystemThread (wdm.h)

Article
02/29/2024

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