Función FltCancellableWaitForSingleObject (fltkernel.h)

Artículo
08/07/2023

La rutina FltCancellableWaitForSingleObject ejecuta una operación de espera cancelable (una espera que se puede terminar) en un objeto distribuidor.

Sintaxis

NTSTATUS FLTAPI FltCancellableWaitForSingleObject(
  [in]           PVOID              Object,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PFLT_CALLBACK_DATA CallbackData
);

Parámetros

[in] Object

Puntero a un objeto de distribuidor inicializado (evento, exclusión mutua, semáforo, subproceso o temporizador) para el que el autor de la llamada proporciona el almacenamiento.

[in, optional] Timeout

Puntero a un valor de tiempo de espera opcional. Este parámetro especifica el tiempo absoluto o relativo, en 100 unidades nanosegundas, cuando se va a completar la espera.

Si Timeout apunta a un valor cero (es decir, *Timeout == 0), la rutina devuelve sin esperar. Si el autor de la llamada proporciona un puntero NULL (es decir, Timeout == NULL), la rutina espera indefinidamente hasta que el objeto se establece en el estado señalado.

Un valor de tiempo de espera positivo especifica una hora absoluta, con respecto al 1 de enero de 1601. Un valor de tiempo de espera negativo especifica un intervalo relativo a la hora actual. Los tiempos de expiración absolutos realizan un seguimiento de los cambios en la hora del sistema. Los tiempos de expiración relativos no se ven afectados por los cambios de hora del sistema.

Si se especifica Timeout , la espera se satisface automáticamente si el objeto no está establecido en el estado señalado cuando expira el intervalo especificado.

Un valor de tiempo de espera de cero (es decir, *Timeout == 0) permite probar un conjunto de condiciones de espera y realizar condicionalmente cualquier acción adicional si la espera se puede satisfacer inmediatamente, como en la adquisición de una exclusión mutua.

[in, optional] CallbackData

Puntero a la estructura de FLT_CALLBACK_DATA que representa la operación de E/S emitida por el usuario y que el usuario puede cancelar. El autor de la llamada debe asegurarse de que la operación de E/S permanecerá válida durante esta rutina y que la E/S no debe tener establecido una rutina de cancelación (por ejemplo, no se debe haber llamado a una función FltSetCancelCompletion en la operación de E/S). Tenga en cuenta que el autor de la llamada debe contener callbackData; no se puede pasar a un controlador de nivel inferior.

Valor devuelto

FltCancellableWaitForSingleObject puede devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_SUCCESS	El objeto distribuidor especificado por el parámetro Object se ha establecido en el estado señalado.
STATUS_TIMEOUT	Se ha agotado el tiempo de espera antes de establecer el objeto en un estado señalado. Este valor también se puede devolver cuando no se puede cumplir inmediatamente la condición de espera especificada y Timeout se establece en cero.
STATUS_ABANDONED_WAIT_0	El autor de la llamada intentó esperar a una exclusión mutua que se ha abandonado.
STATUS_CANCELLED	La espera se interrumpió mediante una solicitud de cancelación pendiente en la operación de E/S. Tenga en cuenta que este valor solo se devuelve si CallbackData corresponde a una operación basada en IRP se pasa a FltCancellableWaitForSingleObject y una rutina como FltCancelIo canceló la E/S.
STATUS_THREAD_IS_TERMINATING	La espera se interrumpió porque la aplicación o el usuario han terminado el subproceso.

El valor devuelto solo indica el estado de la espera.

Tenga en cuenta que la macro de NT_SUCCESS devuelve FALSE ("error") para el STATUS_CANCELLED y STATUS_THREAD_IS_TERMINATING valores de estado y TRUE ("correcto") para todos los demás valores de estado.

Comentarios

La rutina FltCancellableWaitForSingleObject ejecuta una operación de espera cancelable en un objeto distribuidor. Si el usuario o la aplicación finaliza el subproceso o si una E/S asociada al subproceso se canceló mediante una rutina como FltCancelIo, se cancela la espera.

La rutina está diseñada para admitir las directrices de finalización o cancelación de E/S. El objetivo de estas directrices es permitir que los usuarios finalicen rápidamente las aplicaciones. Esto, a su vez, requiere que las aplicaciones tengan la capacidad de finalizar rápidamente los subprocesos que ejecutan E/S y las operaciones de E/S actuales. Esta rutina proporciona una manera de que los subprocesos de usuario bloqueen (es decir, espere) en el kernel para la finalización de E/S, los objetos de distribuidor o las variables de sincronización de una manera que permita que la espera se cancele fácilmente. Esta rutina también permite finalizar la espera del subproceso si un usuario o una aplicación finalizan el subproceso.

Por ejemplo, un redirector puede necesitar crear una operación de E/S secundaria para procesar una E/S en modo de usuario y esperar sincrónicamente a que se complete la solicitud secundaria. Una manera de hacerlo es configurar un evento que se indicará mediante la rutina de finalización de la operación de E/S secundaria y, a continuación, esperar a que se señale el evento. A continuación, para realizar una operación de espera cancelable, se llama FltCancellableWaitForSingleObject pasando el evento asociado a la operación de E/S secundaria y la operación de E/S en modo de usuario original. La espera del subproceso para que se indique el evento se cancela si se produce un evento de finalización pendiente o si se cancela la operación de E/S en modo de usuario original.

Tenga en cuenta que la terminación de la espera no cancela automáticamente ninguna operación de E/S emitida por el autor de la llamada, que el autor de la llamada debe controlar por separado.

Se aplica una consideración especial cuando el parámetro Object pasado a FltCancellableWaitForSingleObject es una exclusión mutua. Si el objeto dispatcher que se espera es una exclusión mutua, la entrega de APC es la misma que para todos los demás objetos de distribuidor durante la espera. Sin embargo, una vez que FltCancellableWaitForSingleObject devuelve con STATUS_SUCCESS y el subproceso contiene realmente la exclusión mutua, solo se entregan las API de modo kernel especiales. La entrega de todas las demás API, tanto en modo kernel como en modo usuario, está deshabilitada. Esta restricción en la entrega de APCs persiste hasta que se libera la exclusión mutua.

Una exclusión mutua solo se puede adquirir de forma recursiva solo las veces de MINLONG. Si se supera este límite, la rutina genera una excepción de STATUS_MUTANT_LIMIT_EXCEEDED.

Se debe llamar a FltCancellableWaitForSingleObject en irQL PASSIVE_LEVEL si el parámetro CallbackData representa un IRP del administrador de filtros válido. De lo contrario, se puede llamar a la rutina en IRQL menor o igual que APC_LEVEL. Las API normales del kernel se pueden deshabilitar mediante el autor de la llamada, si es necesario, llamando a las rutinas KeEnterCriticalRegion o FsRtlEnterFileSystem . Sin embargo, las API especiales del kernel no deben estar deshabilitadas.

La rutina FltCancellableWaitForSingleObject se afirmará en las compilaciones de depuración si CallbackData representa una operación IRP del Administrador de filtros, pero el IRP de la estructura CallbackData es NULL.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Plataforma de destino	Universal
Encabezado	fltkernel.h (incluya Fltkernel.h, Ntifs.h)
Library	Fltmgr.lib
Archivo DLL	Fltmgr.sys
IRQL	vea la sección Comentarios.