Función IoCreateSystemThread (wdm.h)

Artículo
02/27/2024

La rutina IoCreateSystemThread crea un subproceso del sistema que se ejecuta en modo kernel y proporciona un identificador para el subproceso.

Sintaxis

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
);

Parámetros

[in, out] IoObject

Puntero al DEVICE_OBJECT o DRIVER_OBJECT que se va a asociar al subproceso creado. IoCreateSystemThread toma una referencia contada a este objeto. El administrador de E/S publica esta referencia más adelante cuando se cierra el subproceso. Para obtener más información, vea la sección Comentarios.

[out] ThreadHandle

Puntero a una variable en la que la rutina escribe el identificador del kernel para el subproceso creado. Cuando el controlador ya no es necesario, el controlador debe cerrarlo llamando a la rutina ZwClose .

[in] DesiredAccess

Valor de ACCESS_MASK que representa los tipos de acceso a las solicitudes del autor de la llamada al subproceso creado.

[in, optional] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES que especifica los atributos del objeto de subproceso. Los atributos OBJ_PERMANENT, OBJ_EXCLUSIVE y OBJ_OPENIF no son atributos válidos para un objeto de subproceso. Si el autor de la llamada no se está ejecutando en el contexto del proceso del sistema, debe establecer el atributo OBJ_KERNEL_HANDLE en la estructura OBJECT_ATTRIBUTES .

[in, optional] ProcessHandle

Identificador abierto del proceso en cuyo espacio de direcciones se va a ejecutar el subproceso creado. El subproceso del autor de la llamada debe tener PROCESS_CREATE_THREAD acceso a este proceso. Si este parámetro es NULL, el subproceso se creará en el proceso inicial del sistema. Este parámetro debe ser NULL para un subproceso creado por el controlador. Use la macro NtCurrentProcess , definida en el archivo de encabezado Wdm.h, para especificar el proceso actual.

[out, optional] ClientId

Puntero a una estructura en la que la rutina escribe el identificador de cliente para el subproceso creado. Este parámetro debe ser NULL para un subproceso creado por el controlador.

[in] StartRoutine

Puntero a una rutina ThreadStart que es el punto de entrada del subproceso creado.

[in, optional] StartContext

Puntero de contexto que se pasa como parámetro StartContext a la rutina ThreadStart cuando el subproceso creado comienza a ejecutarse.

Valor devuelto

IoCreateSystemThread devuelve STATUS_SUCCESS si el nuevo subproceso se creó correctamente. Entre los posibles valores devueltos se incluyen los siguientes códigos de estado de error.

Código devuelto	Descripción
STATUS_INVALID_HANDLE	ProcessHandle no es un identificador de proceso válido.
STATUS_PROCESS_IS_TERMINATING	El proceso especificado por ProcessHandle finaliza.
STATUS_INSUFFICIENT_RESOURCES	Hay recursos del sistema insuficientes disponibles para realizar la operación solicitada.

Comentarios

A partir de Windows 8, un controlador puede llamar a IoCreateSystemThread para crear un subproceso dedicado al dispositivo. Esta rutina crea un nuevo subproceso del sistema que no tiene ningún bloque de entorno de subproceso (TEB) o contexto en modo de usuario, y solo se ejecuta en modo kernel.

Normalmente, el controlador llama a IoCreateSystemThread cuando inicia el dispositivo o cuando las rutinas DispatchXxx del controlador comienzan a recibir solicitudes de E/S. Por ejemplo, un controlador podría llamar a esta rutina para crear un subproceso cuando una rutina DispatchXxx recibe una solicitud de control de dispositivo asincrónica.

Si el parámetro ProcessHandle es NULL, el subproceso creado se asocia al proceso del sistema. Este subproceso continúa ejecutándose hasta que se cierra el sistema o se cierra el subproceso.

Las rutinas de controlador que se ejecutan en un contexto de proceso distinto del del proceso del sistema deben establecer el atributo OBJ_KERNEL_HANDLE para el parámetro ObjectAttributes de IoCreateSystemThread. Este atributo restringe el uso del identificador devuelto por IoCreateSystemThread a los procesos que se ejecutan en modo kernel. De lo contrario, el proceso podría tener acceso al identificador del subproceso en cuyo contexto se está ejecutando el controlador. Los controladores pueden llamar a la macro InitializeObjectAttributes para establecer el atributo OBJ_KERNEL_HANDLE en los atributos del objeto, como se muestra en el ejemplo de código siguiente.

OBJECT_ATTRIBUTES ObjectAttributes;

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

IoCreateSystemThread es similar a la rutina PsCreateSystemThread , pero tiene un parámetro adicional, IoObject, que es un puntero al objeto de controlador o al objeto de dispositivo del autor de la llamada. IoCreateSystemThread usa este parámetro para asegurarse de que el controlador no se puede descargar mientras existe el subproceso creado. Antes de programar StartRoutine para que se ejecute en este subproceso, IoCreateSystemThread toma una referencia contada al objeto IoObject . El administrador de E/S libera esta referencia después de que se cierre el subproceso creado. Por lo tanto, este objeto persiste durante la vigencia del subproceso creado.

A diferencia de un subproceso del sistema creado por la rutina PsCreateSystemThread , un subproceso creado por IoCreateSystemThread no llama a la rutina PsTerminateSystemThread para finalizar. En su lugar, el administrador de E/S llama a PsTerminateSystemThread en nombre del subproceso creado cuando se cierra el subproceso.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 8.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL