Função IoCreateSystemThread (wdm.h)
A rotina IoCreateSystemThread cria um thread do sistema que é executado no modo kernel e fornece um identificador para o thread.
Sintaxe
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
Um ponteiro para o DEVICE_OBJECT ou DRIVER_OBJECT para associar ao thread criado. IoCreateSystemThread faz uma referência contada a esse objeto. O gerenciador de E/S posteriormente libera essa referência quando o thread é encerrado. Para obter mais informações, consulte Comentários.
[out] ThreadHandle
Um ponteiro para uma variável na qual a rotina grava o identificador de kernel para o thread criado. Quando o identificador não for mais necessário, o driver deverá fechar o identificador chamando a rotina ZwClose .
[in] DesiredAccess
O valor ACCESS_MASK que representa os tipos de acesso às solicitações de chamador para o thread criado.
[in, optional] ObjectAttributes
Um ponteiro para uma estrutura OBJECT_ATTRIBUTES que especifica os atributos do objeto thread. Os atributos OBJ_PERMANENT, OBJ_EXCLUSIVE e OBJ_OPENIF não são atributos válidos para um objeto thread. Se o chamador não estiver em execução no contexto do processo do sistema, ele deverá definir o atributo OBJ_KERNEL_HANDLE na estrutura OBJECT_ATTRIBUTES .
[in, optional] ProcessHandle
Um identificador aberto para o processo em cujo espaço de endereço o thread criado deve ser executado. O thread do chamador deve ter PROCESS_CREATE_THREAD acesso a esse processo. Se esse parâmetro for NULL, o thread será criado no processo inicial do sistema. Esse parâmetro deve ser NULL para um thread criado pelo driver. Use a macro NtCurrentProcess , definida no arquivo de cabeçalho Wdm.h, para especificar o processo atual.
[out, optional] ClientId
Um ponteiro para uma estrutura na qual a rotina grava o identificador do cliente para o thread criado. Esse parâmetro deve ser NULL para um thread criado pelo driver.
[in] StartRoutine
Um ponteiro para uma rotina ThreadStart que é o ponto de entrada para o thread criado.
[in, optional] StartContext
Um ponteiro de contexto que é passado como o parâmetro StartContext para a rotina ThreadStart quando o thread criado começa a ser executado.
Retornar valor
IoCreateSystemThread retornará STATUS_SUCCESS se o novo thread tiver sido criado com êxito. Os possíveis valores retornados incluem o seguinte erro status códigos.
| Código de retorno | Descrição |
|---|---|
| STATUS_INVALID_HANDLE | ProcessHandle não é um identificador de processo válido. |
| STATUS_PROCESS_IS_TERMINATING | O processo especificado pelo ProcessHandle está sendo encerrado. |
| STATUS_INSUFFICIENT_RESOURCES | Recursos insuficientes do sistema estão disponíveis para executar a operação solicitada. |
Comentários
Começando com Windows 8, um driver pode chamar IoCreateSystemThread para criar um thread dedicado ao dispositivo. Essa rotina cria um novo thread do sistema que não tem nenhum bloco de ambiente de thread (TEB) ou contexto de modo de usuário e é executado somente no modo kernel.
Normalmente, o driver chama IoCreateSystemThread quando inicia o dispositivo ou quando as rotinas de Expediçãoxxx do driver começam a receber solicitações de E/S. Por exemplo, um driver pode chamar essa rotina para criar um thread quando uma rotina DispatchXxx recebe uma solicitação de controle de dispositivo assíncrona.
Se o parâmetro ProcessHandle for NULL, o thread criado será associado ao processo do sistema. Esse thread continua em execução até que o sistema seja desligado ou o thread seja encerrado.
Rotinas de driver executadas em um contexto de processo diferente do processo do sistema devem definir o atributo OBJ_KERNEL_HANDLE para o parâmetro ObjectAttributes de IoCreateSystemThread. Esse atributo restringe o uso do identificador retornado por IoCreateSystemThread a processos em execução no modo kernel. Caso contrário, o identificador de thread pode ser acessado pelo processo em cujo contexto o driver está em execução. Os drivers podem chamar a macro InitializeObjectAttributes para definir o atributo OBJ_KERNEL_HANDLE nos atributos de objeto, conforme mostrado no exemplo de código a seguir.
OBJECT_ATTRIBUTES ObjectAttributes;
InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);
IoCreateSystemThread é semelhante à rotina PsCreateSystemThread , mas tem um parâmetro adicional, IoObject, que é um ponteiro para o objeto de driver ou objeto do dispositivo do chamador. IoCreateSystemThread usa esse parâmetro para garantir que o driver não possa descarregar enquanto o thread criado existir. Antes de agendar StartRoutine para execução neste thread, IoCreateSystemThread usa uma referência contada ao objeto IoObject . O gerenciador de E/S libera essa referência após a saída do thread criado. Portanto, esse objeto persiste durante o tempo de vida do thread criado.
Em contraste com um thread do sistema criado pela rotina PsCreateSystemThread , um thread criado por IoCreateSystemThread não chama a rotina PsTerminateSystemThread para terminar sozinho. Em vez disso, o gerente de E/S chama PsTerminateSystemThread em nome do thread criado quando o thread é encerrado.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível a partir do Windows 8. |
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |