Función ZwWaitForSingleObject (ntifs.h)
El ZwWaitForSingleObject rutina 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 de espera 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 en la 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 | La espera se anuló 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 establecer el objeto 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 está establecido en cero. |
| STATUS_USER_APC | La espera se anuló para entregar un usuario APC al subproceso actual. |
Tenga en cuenta que la macro NT_SUCCESS reconoce los valores de estado STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT y STATUS_USER_APC como valores de estado "correctos".
Observaciones
ZwWaitForSingleObject espera hasta que el objeto especificado alcance 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 timeout explícito valor de cero, no se producirá ninguna espera si no se puede satisfacer inmediatamente la espera. Un tiempo de espera valor de cero permite probar un conjunto de condiciones de espera y para el rendimiento condicional de cualquier efecto secundario si la espera se puede satisfacer 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 se encuentra en proceso de desvanado. Un subproceso se realiza automáticamente en alerta, por ejemplo, cuando un usuario termina con ctrl+C.
Si el valor de alertable es TRUE y hay una de las siguientes condiciones, se avisará al subproceso:
- Si el origen de la alerta es una rutina de modo kernel no documentado 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 cumple con el 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, por 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 el 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 kernel APC 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 distribuidores durante la espera. Sin embargo, una vez ZwWaitForSingleObject devuelve con STATUS_SUCCESS y el subproceso contiene realmente la exclusión mutua, solo se entregan las API en 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
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 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, vea Precisión del temporizador.
Si la llamada al ZwWaitForSingleObject función 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 NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows 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 de NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows XP |
| de la plataforma de destino de |
Universal |
| encabezado de |
ntifs.h (incluya Ntifs.h, FltKernel.h) |
| biblioteca de |
NtosKrnl.lib |
| DLL de |
NtosKrnl.exe |
| irQL | PASSIVE_LEVEL |
| reglas de cumplimiento de DDI | HwStorPortProhibitedDIs(storport), spNoWait(storport) |