Función ZwWaitForSingleObject (ntifs.h)

Artículo
07/11/2023

La rutina ZwWaitForSingleObject espera hasta que el objeto especificado alcanza un estado de Signaled. También se puede especificar un tiempo de espera opcional.

Sintaxis

NTSYSAPI NTSTATUS ZwWaitForSingleObject(
  [in]           HANDLE         Handle,
  [in]           BOOLEAN        Alertable,
  [in, optional] PLARGE_INTEGER Timeout
);

Parámetros

[in] Handle

Identificador del objeto .

[in] Alertable

Valor booleano que especifica si la espera es alertable.

[in, optional] Timeout

Puntero opcional a un valor de tiempo de espera que especifica el tiempo absoluto o relativo en el que se va a completar la espera. Un valor negativo especifica un intervalo relativo a la hora actual. El valor debe expresarse en unidades de 100 nanosegundos. 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.

Valor devuelto

ZwWaitForSingleObject puede devolver uno de los siguientes códigos de estado posibles:

Código devuelto	Descripción
STATUS_ACCESS_DENIED	El autor de la llamada no tenía los privilegios necesarios para el evento especificado por el parámetro Handle .
STATUS_ALERTED	Se anuló la espera para entregar una alerta al subproceso actual.
STATUS_INVALID_HANDLE	El parámetro Handle proporcionado no era válido.
STATUS_SUCCESS	El objeto especificado satisface la espera.
STATUS_TIMEOUT	Se agotó el tiempo de espera antes de que el objeto se estableciera en un estado señalado. Este valor se puede devolver cuando no se puede cumplir inmediatamente el conjunto especificado de condiciones de espera y el parámetro Timeout se establece en cero.
STATUS_USER_APC	Se anuló la espera para entregar un usuario APC al subproceso actual.

Tenga en cuenta que la macro de NT_SUCCESS reconoce los valores de estado STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT y STATUS_USER_APC como valores de estado "correctos".

Comentarios

ZwWaitForSingleObject espera hasta que el objeto especificado alcanza un estado de Signaled. También se puede especificar un tiempo de espera opcional. ZwWaitForSingleObject examina el estado actual del objeto especificado para determinar si la espera se puede satisfacer inmediatamente. Si es así, se realizan acciones. De lo contrario, el subproceso actual se coloca en un estado de espera y se selecciona un nuevo subproceso para su ejecución en el procesador actual.

Si no se especifica un parámetro Timeout , la espera no se cumplirá hasta que el objeto alcance un estado de Signaled. Si se especifica un parámetro Timeout y el objeto no ha alcanzado un estado de Signaled cuando expira el tiempo de espera, la espera se satisface automáticamente. Si se especifica un valor de tiempo de espera explícito de cero, no se producirá ninguna espera si la espera no se puede satisfacer inmediatamente. Un valor de tiempo de espera de cero permite realizar pruebas de un conjunto de condiciones de espera y para el rendimiento condicional de los efectos secundarios si la espera puede cumplirse inmediatamente, como en la adquisición de una exclusión mutua. La espera también se puede especificar como alertable.

El parámetro Alertable especifica si el subproceso se puede alertar y su estado de espera, en consecuencia, anulado. Si el valor de este parámetro es FALSE, no se puede alertar al subproceso. La única excepción a esta regla es la de un subproceso de terminación. En determinadas circunstancias, se puede alertar a un subproceso de terminación mientras está en proceso de desvaneamiento. Un subproceso se hace automáticamente alertable, por ejemplo, cuando un usuario finaliza con ctrl+C.

Si el valor de Alertablees TRUE y una de las condiciones siguientes está presente, se avisará al subproceso:

Si el origen de la alerta es una rutina de modo kernel no documentada interna que se usa para alertar subprocesos.
El origen de la alerta es un APC en modo de usuario.

En el primero de estos dos casos, la espera del subproceso se satisface con un estado de finalización de STATUS_ALERTED. En el segundo caso, se satisface con un estado de finalización de STATUS_USER_APC.

El subproceso debe ser alertable para que se entregue un APC en modo de usuario. Este no es el caso de las API en modo kernel. Un APC en modo kernel se puede entregar y ejecutar aunque el subproceso no esté alertado. Una vez completada la ejecución de APC, se reanuda la espera del subproceso. Un subproceso nunca se alerta, ni su espera anulada, mediante la entrega de un APC en modo kernel.

La entrega de las API en modo kernel a un subproceso en espera no depende de si se puede alertar al subproceso. Si el APC en modo kernel es un APC en modo kernel especial, el APC se entrega siempre que irQL sea menor que APC_LEVEL. Si el APC en modo kernel es un APC en modo kernel normal, el APC se entrega siempre que las tres condiciones siguientes contengan: (1) el IRQL es menor que APC_LEVEL, (2) ningún APC del kernel está en curso y (3) el subproceso no está en una sección crítica.

Si el identificador pasado a ZwWaitForSingleObject hace referencia a 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 ZwWaitForSingleObject vuelve 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 de usuario, está deshabilitada. Esta restricción en la entrega de LAS API persiste hasta que se libera la exclusión mutua.

Es especialmente importante comprobar el valor devuelto de ZwWaitForSingleObject cuando el parámetro Alertable es TRUE, ya que ZwWaitForSingleObject puede devolverse al principio con un estado de STATUS_USER_APC o STATUS_ALERTED.

Un usuario puede anular todas las esperas a largo plazo si el parámetro Alertable está establecido en FALSE.

Para obtener más información, consulte ¿Los subprocesos en espera reciben alertas y API?

Los autores de llamadas de ZwWaitForSingleObject deben ejecutarse en IRQL menor o igual que DISPATCH_LEVEL. Normalmente, el autor de la llamada debe ejecutarse en irQL PASSIVE_LEVEL y en un contexto de subproceso nobitrario. Una llamada mientras se ejecuta en IRQL DISPATCH_LEVEL es válida si y solo si el autor de la llamada especifica un parámetro Timeout de cero. Es decir, un controlador no debe esperar un intervalo distinto de cero en IRQL igual a DISPATCH_LEVEL.

Los intervalos de tiempo de espera se miden en relación con el reloj del sistema y la precisión de la medida de tiempo de espera está limitada por la granularidad del reloj del sistema. Para obtener más información, consulte Precisión del temporizador.

Si la llamada a la función ZwWaitForSingleObject se produce en modo de usuario, debe usar el nombre "NtWaitForSingleObject" en lugar de "ZwWaitForSingleObject".

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Windows Native System Services pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h, FltKernel.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), SpNoWait(storport)