Функция ZwWaitForSingleObject (ntifs.h)

Статья
12/21/2024

Подпрограмма ZwWaitForSingleObject ожидает, пока указанный объект не достигнет состояния Signaled. Также можно указать дополнительное время ожидания.

Синтаксис

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

Параметры

[in] Handle

Дескриптор объекта.

[in] Alertable

Логическое значение, указывающее, является ли ожидание оповещением.

[in, optional] Timeout

Необязательный указатель на значение времени ожидания, указывающее абсолютное или относительное время завершения ожидания. Отрицательное значение указывает интервал относительно текущего времени. Значение должно быть выражено в единицах 100 наносекунд. Абсолютное время истечения срока действия отслеживает любые изменения в системном времени. Относительные сроки действия не влияют на изменения системного времени.

Возвращаемое значение

ZwWaitForSingleObject может возвращать один из следующих возможных кодов состояния:

Возвращаемый код	Описание
STATUS_ACCESS_DENIED	Вызывающий объект не имеет необходимых привилегий для события, указанного параметром Handle.
STATUS_ALERTED	Ожидание было прервано, чтобы доставить оповещение текущему потоку.
STATUS_INVALID_HANDLE	Указанный параметр Handle был недопустимым.
STATUS_SUCCESS	Указанный объект удовлетворил ожидание.
STATUS_TIMEOUT	Время ожидания произошло до того, как объект был задан в сигнальном состоянии. Это значение можно вернуть, если указанный набор условий ожидания не может быть немедленно выполнен, а параметр Timeout имеет значение нулю.
STATUS_USER_APC	Ожидание было прервано для доставки пользовательского APC в текущий поток.

Обратите внимание, что макрос NT_SUCCESS распознает STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT и STATUS_USER_APC значения состояния как "успешно".

Замечания

ZwWaitForSingleObject ожидает, пока указанный объект не достигнет состояния Signaled. Также можно указать необязательное время ожидания. ZwWaitForSingleObject проверяет текущее состояние указанного объекта, чтобы определить, может ли ожидание быть удовлетворено немедленно. В этом случае выполняются действия. В противном случае текущий поток помещается в состояние ожидания, а новый поток выбирается для выполнения на текущем процессоре.

Если параметр времени ожидания не указан, ожидание не будет удовлетворено, пока объект не достигнет состояния Signaled. Если указан параметр Timeout, и объект не достиг состояния Signaled при истечении времени ожидания, ожидание будет автоматически удовлетворено. Если указано явное время ожидания нулю, то в случае, если ожидание не может быть удовлетворено немедленно. Значение времени ожидания позволяет проверять набор условий ожидания и для условной производительности любых побочных эффектов, если ожидание может быть немедленно удовлетворено, как при приобретении мьютекса. Ожидание также можно указать как оповещенное.

Параметр оповещений указывает, может ли поток быть оповещен и его состояние ожидания, следовательно, прервано. Если значение этого параметра равно FALSE, поток не может быть оповещен. Единственным исключением из этого правила является завершение потока. При определенных обстоятельствах конечный поток может быть оповещен, пока он находится в процессе свертки. Поток автоматически становится оповещенным, например, при завершении пользователем с помощью CTRL+C.

Если значение оповещенийимеет значение TRUE и одно из следующих условий присутствует, поток будет оповещен:

Если источник оповещения является внутренней, незадокументированной подпрограммой режима ядра, используемой для оповещений потоков.
Источником оповещения является APC в пользовательском режиме.

В первом из этих двух случаев ожидание потока удовлетворено состоянием завершения STATUS_ALERTED. Во втором случае оно удовлетворено состоянием завершения STATUS_USER_APC.

Поток должен быть оповещен для доставки APC в пользовательском режиме. Это не так для API-интерфейсов в режиме ядра. APC в режиме ядра можно доставлять и выполнять, даже если поток не оповещен. После завершения выполнения APC поток возобновляется. Поток никогда не оповещается, и его ожидание прерывается доставкой APC в режиме ядра.

Доставка API режима ядра в ожидающий поток не зависит от того, может ли поток быть оповещен. Если APC в режиме ядра является специальным APC в режиме ядра, то APC предоставляется при условии, что IRQL меньше APC_LEVEL. Если APC в режиме ядра является обычным APC в режиме ядра, то APC предоставляется при условии, что следующие три условия хранятся: (1) IRQL меньше APC_LEVEL, (2) не выполняется ядро APC, и (3) поток не находится в критическом разделе.

Если дескриптор, переданный в ZwWaitForSingleObject, относится к мьютексу, доставка APC совпадает со всеми другими объектами диспетчера во время ожидания. Однако после ZwWaitForSingleObject возвращается с STATUS_SUCCESS, а поток фактически содержит мьютекс, доставляются только специальные API в режиме ядра. Доставка всех остальных API, как в режиме ядра, так и в пользовательском режиме, отключена. Это ограничение на доставку API сохраняется до тех пор, пока мьютекс не будет освобожден.

Особенно важно проверить возвращаемое значение ZwWaitForSingleObject, если параметр alertable имеет значение TRUE, так как ZwWaitForSingleObject может вернуться рано с состоянием STATUS_USER_APC или STATUS_ALERTED.

Все долгосрочные ожидания могут быть прерваны пользователем, если параметр alertable имеет значение FALSE.

Дополнительные сведения см. в разделе Получение оповещений и API-интерфейсов ожидающих потоков?

Вызывающие ZwWaitForSingleObject должны работать в IRQL меньше или равно DISPATCH_LEVEL. Как правило, вызывающий объект должен выполняться в irQL PASSIVE_LEVEL и в контексте непарбитрарного потока. Вызов при выполнении в IRQL DISPATCH_LEVEL действителен, если и только если вызывающий объект задает параметр Timeout нулю. То есть драйвер не должен ждать ненулевого интервала в IRQL равным DISPATCH_LEVEL.

Интервалы времени ожидания измеряются относительно системных часов, а точность измерения времени ожидания ограничена детализацией системных часов. Дополнительные сведения см. вточности таймера .

Если вызов функции ZwWaitForSingleObject происходит в пользовательском режиме, следует использовать имя "NtWaitForSingleObject" вместо "ZwWaitForSingleObject".

Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h, FltKernel.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
правил соответствия DDI	HwStorPortProhibitedDIs(storport), SpNoWait(storport)