Função KeRemoveQueue (ntifs.h)
A rotina de KeRemoveQueue dá ao thread de chamada um ponteiro para uma entrada desqueada do objeto de fila fornecido ou permite que o chamador aguarde, até um intervalo opcional de tempo limite, no objeto de fila.
Sintaxe
PLIST_ENTRY KeRemoveQueue(
[in, out] PRKQUEUE Queue,
[in] KPROCESSOR_MODE WaitMode,
[in, optional] PLARGE_INTEGER Timeout
);
Parâmetros
[in, out] Queue
Ponteiro para um objeto de fila inicializado para o qual o chamador fornece armazenamento residente no pool nãopagado.
[in] WaitMode
O modo de processador no qual o chamador está aguardando, que pode ser KernelMode ou UserMode. Se alguma coisa em sua pilha puder ser acessada em IRQL >= DISPATCH_LEVEL, o chamador deverá especificar kernelMode.
[in, optional] Timeout
Ponteiro para uma variável que especifica o tempo absoluto ou relativo, em unidades de 100 nanossegundos, em que a espera deve expirar. Se o valor de Timeout for negativo, o tempo de expiração será relativo ao tempo atual do sistema; caso contrário, é absoluto. Os tempos de expiração absolutos acompanham as alterações no tempo do sistema; os tempos de expiração relativos não são afetados pelas alterações de tempo do sistema. Esse ponteiro pode ser NULL.
Valor de retorno
KeRemoveQueue retorna um dos seguintes:
- Um ponteiro para uma entrada desqueada do objeto de fila fornecido, se houver um disponível.
- STATUS_TIMEOUT, se o intervalo de tempo limite especificado expirou antes de uma entrada ficar disponível
- STATUS_USER_APC, se um APC no modo de usuário foi entregue no contexto do thread de chamada
- STATUS_ABANDONED, se a fila tiver sido executada
Observações
Os chamadores do KeRemoveQueue devem testar se seu valor retornado é STATUS_TIMEOUT ou STATUS_USER_APC antes de acessar os membros de entrada. Testar o valor retornado de KeRemoveQueue em NULL é um erro de programação.
Especificar um valor zero para Timeout indica a relutância do chamador em aguardar uma entrada se a fila estiver vazia no momento. Especificar um ponteiro **NULL*Timeout indica a disposição do chamador de aguardar indefinidamente por uma entrada.
Se o parâmetro WaitMode for UserMode, a pilha de kernel poderá ser trocada durante a espera. Consequentemente, um chamador nunca deve tentar passar parâmetros na pilha ao chamar KeRemoveQueue com WaitMode definido como UserMode.
Especificar WaitMode como kernelMode em uma chamada para KeRemoveQueue impede que a pilha de kernel do thread de chamada seja trocada, além de impedir a entrega de chamadas de procedimento assíncrono (APC) no modo de usuário. Isso não impede a entrega de APCs no modo kernel, como as usadas pelo Gerenciador de E/S para concluir IRPs, quando um thread chama KeRemoveQueue do IRQL PASSIVE_LEVEL. A entrega desse APC no modo kernel não impede que o thread de chamada espere no objeto de fila nem seja expedido para execução com uma entrada após a execução do APC do kernel.
Para obter mais informações sobre como usar filas internas gerenciadas pelo driver, consulte Driver-Managed Filas.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| cabeçalho | ntifs.h (inclua Ntifs.h, FltKernel.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |
| regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |