Función IoCreateSystemThread (wdm.h)

La rutina IoCreateSystemTh read 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 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 de ZwClose.

[in] DesiredAccess

Valor 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 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 ejecuta 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 un ThreadStart rutina 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. Los valores devueltos posibles incluyen los siguientes códigos de estado de error.

Observaciones

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 se 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 de 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 el sistema se apaga 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 acceder 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 de 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 de 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 ejecutarse 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 de PsCreateSystemThread, un subproceso creado por IoCreateSystemThread no llama a la rutina PsTerminateSystemThread para terminarse. En su lugar, el administrador de E/S llama a PsTerminateSystemThread en nombre del subproceso creado cuando se cierra el subproceso.

Requisitos

Consulte también

ACCESS_MASK

DEVICE_OBJECT

DRIVER_OBJECT

initializeObjectAttributes

OBJECT_ATTRIBUTES

psCreateSystemThread

PsTerminateSystemThread

threadStart

ZwClose