IoCreateSystemThread, fonction (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 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 lors de la sortie du thread. Pour plus d’informations, consultez Remarques.
[out] ThreadHandle
Pointeur vers une variable vers 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 aux demandes de l’appelant 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 l’espace d’adressage du thread créé doit s’exécuter. Le thread de l’appelant doit avoir PROCESS_CREATE_THREAD accès à ce processus. Si ce paramètre est NULL, le thread est créé dans le processus système initial. Ce paramètre doit être 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 actuel.
[out, optional] ClientId
Pointeur vers une structure dans laquelle la routine écrit l’identificateur client pour le thread créé. Ce paramètre doit être NULL pour un thread créé par un pilote.
[in] StartRoutine
Pointeur vers un ThreadStart routine qui est le point d’entrée du thread créé.
[in, optional] StartContext
Pointeur de contexte passé en tant que paramètre StartContext à la routine ThreadStart lors de l’exécution du thread créé.
Valeur de retour
IoCreateSystemThread retourne STATUS_SUCCESS si le nouveau thread a été créé avec succès. Les valeurs de retour possibles incluent les codes d’état d’erreur suivants.
| Retourner le code | 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 insuffisantes sont disponibles 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 s’exécute uniquement en mode noyau.
En règle générale, le pilote appelle IoCreateSystemThread lorsqu’il démarre l’appareil, ou lorsque les routines dispatch DispatchXxx commencent à recevoir des demandes d’E/S. Par exemple, un pilote peut appeler cette routine pour créer un thread lorsqu’une routine dispatch DispatchXxx reçoit une demande de contrôle d’appareil asynchrone.
Si le paramètre ProcessHandle est 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 ObjectAttributes de 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 de périphérique de l’appelant. IoCreateSystemThread utilise ce paramètre pour s’assurer que le pilote ne peut pas décharger pendant que le thread créé existe. Avant de planifier StartRoutine à exécuter 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éé. Ainsi, 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. Au lieu de cela, le gestionnaire d’E/S appelle PsTerminateSystemThread pour le compte du thread créé lors de la sortie du thread.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 8. |
| plateforme cible | Universel |
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |