Função KeRemoveQueue (ntifs.h)

A rotina KeRemoveQueue fornece ao thread de chamada um ponteiro para uma entrada desativada do objeto de fila fornecido ou permite que o chamador aguarde, até um intervalo de tempo limite opcional, 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 em 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 à hora atual do sistema; caso contrário, é absoluto. Os tempos de expiração absolutos acompanham as alterações na hora do sistema; os tempos de expiração relativos não são afetados pelas alterações de tempo do sistema. Este ponteiro pode ser nulo.

Retornar valor

KeRemoveQueue retorna um dos seguintes:

• Um ponteiro para uma entrada removida 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

Comentários

Os chamadores de KeRemoveQueue devem testar se seu valor retornado é STATUS_TIMEOUT ou STATUS_USER_APC antes de acessar qualquer membro de entrada. Testar o valor retornado de KeRemoveQueue em relação a 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 de tempo limite **NULL* 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, bem como impedir a entrega de APC (chamadas de procedimento assíncrono) no modo de usuário. Ele não impede a entrega de APCs no modo kernel, como aquelas 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 Filas gerenciadas pelo driver.

Requisitos

Confira também

KeInsertHeadQueue

KeInsertQueue