Función FltCancellableWaitForMultipleObjects (fltkernel.h)
FltCancellableWaitForMultipleObjects ejecuta una operación de espera cancelable (una espera que se puede terminar) en uno o varios objetos distribuidores.
Sintaxis
NTSTATUS FLTAPI FltCancellableWaitForMultipleObjects(
[in] ULONG Count,
[in] PVOID [] ObjectArray,
[in] WAIT_TYPE WaitType,
[in, optional] PLARGE_INTEGER Timeout,
[in, optional] PKWAIT_BLOCK WaitBlockArray,
[in] PFLT_CALLBACK_DATA CallbackData
);
Parámetros
[in] Count
Número de objetos en los que se va a esperar.
[in] ObjectArray
Puntero a una matriz de punteros a objetos de distribuidor (eventos, exclusión mutua, semáforos, subprocesos y temporizadores) para los que el autor de la llamada proporciona el almacenamiento.
[in] WaitType
Enumeración con el valor de WaitAll, que indica que todos los objetos especificados deben alcanzar un estado señalado antes de que se cumpla la espera; o WaitAny, que indica que cualquiera de los objetos debe alcanzar un estado señalado antes de que se cumpla la espera.
[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 en las que 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 cualquiera o todos los objetos del distribuidor se establezcan en el estado señalado.
Un valor positivo especifica una hora absoluta, relativa al 1 de enero de 1601. Un valor 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 no se cumple ninguna de las condiciones de espera especificadas 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] WaitBlockArray
Si Count <= THREAD_WAIT_OBJECTS, WaitBlockArray puede ser NULL. De lo contrario, este parámetro debe apuntar a un búfer de memoria de sizeof(KWAIT_BLOCK) * Count
bytes. La rutina usa este búfer para el mantenimiento de registros mientras realiza la operación de espera.
[in] 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. Este parámetro es opcional y puede ser NULL. El autor de la llamada debe asegurarse de que la operación de E/S permanecerá válida durante la duración de esta rutina y que la E/S no debe tener un conjunto de rutinas de cancelación (por ejemplo, no se debe haber llamado a la función FltSetCancelCompletion en la operación de E/S). Tenga en cuenta que el autor de la llamada debe mantener callbackData , ya que no se puede pasar a un controlador de nivel inferior.
Valor devuelto
FltCancellableWaitForMultipleObjects puede devolver uno de los siguientes valores:
Código devuelto | Descripción |
---|---|
STATUS_SUCCESS | El autor de la llamada especificó WaitAll para el parámetro WaitType y todos los objetos distribuidores de la matriz ObjectArray se han establecido en el estado señalado. |
STATUS_TIMEOUT | Se ha agotado el tiempo de espera antes de que se cumpla el conjunto especificado de condiciones de espera. Este valor también se puede devolver cuando no se puede cumplir inmediatamente el conjunto especificado de condiciones de espera y Timeout se establece en cero. |
STATUS_WAIT_0 a través de STATUS_WAIT_63 | El autor de la llamada especificó WaitAny para WaitType y uno de los objetos distribuidores de la matriz ObjectArray se ha establecido en el estado señalado. Los seis bits inferiores del valor devuelto codifican el índice de base cero del objeto que cumplió la espera. |
STATUS_ABANDONED_WAIT_0 a través de STATUS_ABANDONED_WAIT_63 | El autor de la llamada intentó esperar a una exclusión mutua que se ha abandonado. Los seis bits inferiores del valor devuelto codifican el índice de base cero de la exclusión mutua en la matriz ObjectArray . |
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 que corresponde a una operación basada en IRP se pasa a FltCancellableWaitForMultipleObjects y una rutina como FltCancelIo canceló la E/S. |
STATUS_THREAD_IS_TERMINATING | La espera se interrumpió porque una aplicación o el usuario ha 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
FltCancellableWaitForMultipleObjects ejecuta una operación de espera cancelable en objetos distribuidores. Si el usuario o la aplicación finalizan el subproceso, o si una operación de 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 o varias operaciones de E/S secundarias para procesar una E/S en modo de usuario y esperar sincrónicamente a que se completen las solicitudes secundarias. Una manera de hacerlo es configurar un evento que se indicará mediante la rutina de finalización de las operaciones de E/S secundarias 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 FltCancellableWaitForMultipleObjects pasando los eventos asociados a las operaciones de E/S secundarias 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.
Cada objeto de subproceso tiene una matriz integrada de bloques de espera que puede usar para esperar en varios objetos simultáneamente. Siempre que sea posible, debe usar la matriz integrada de bloques de espera en una operación wait-multiple porque no es necesario asignar almacenamiento de bloque de espera adicional y desasignarse posteriormente. Sin embargo, si el número de objetos que debe esperar simultáneamente es mayor que el número de bloques de espera integrados, use el parámetro WaitBlockArray para especificar un conjunto alternativo de bloques de espera que se usarán en la operación de espera. Los controladores solo necesitan asignar un búfer de memoria suficientemente grande para WaitBlockArray. No es necesario inicializar el búfer y los controladores pueden tratarlo como una estructura opaca. Puede liberar el búfer una vez que la rutina vuelva.
Si Count es mayor que MAXIMUM_WAIT_OBJECTS o si WaitBlockArray es NULL y Count es mayor que THREAD_WAIT_OBJECTS, el sistema emite la comprobación de errores 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED.
Una consideración especial se aplica cuando uno o varios de los elementos del parámetro ObjectArray pasados a FltCancellableWaitForMultipleObjects hace referencia a 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 fltCancellableWaitForMultipleObjects devuelve con STATUS_SUCCESS y el subproceso contiene realmente la exclusión mutua, solo se entregan las API especiales en modo kernel. 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 la rutina FltCancellableWaitForMultipleObjects en IRQL PASSIVE_LEVEL si el parámetro CallbackData representa un IRP de 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.
FltCancellableWaitForMultipleObjects 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 Ntifs.h, Fltkernel.h) |
Library | Fltmgr.lib |
IRQL | vea la sección Comentarios. |
Consulte también
FltCancellableWaitForSingleObject