функция обратного вызова RTL_RUN_ONCE_INIT_FN (ntddk.h)
Подпрограмма RunOnceInitialization выполняет однократную операцию инициализации.
Синтаксис
RTL_RUN_ONCE_INIT_FN (
_Inout_ PRTL_RUN_ONCE RunOnce,
_Inout_opt_ PVOID Parameter,
_Inout_opt_ PVOID *Context
);
Параметры
[in, out] RunOnce
Указатель на RTL_RUN_ONCE структуру однократной инициализации, которую драйвер ранее передал в качестве параметра подпрограмме RtlRunOnceExecuteOnce, которая вызвала эту подпрограмму RunOnceInitialization .
[in, out] Parameter
Значение параметра , переданное драйвером в подпрограмму RtlRunOnceExecuteOnce, которая вызвала эту подпрограмму RunOnceInitialization .
[out] Context
Указатель на переменную PVOID, в которую подпрограмма записывает данные инициализации.
Возвращаемое значение
Подпрограмма RunOnceInitialization возвращает ненулевое значение, указывающее на успешное выполнение, и возвращает ноль, чтобы указать на сбой.
Комментарии
Реализованная драйвером подпрограмма RunOnceInitialization выполняет инициализацию для конкретного драйвера, а затем записывает данные инициализации в расположение памяти, на которое указывает параметр Context . Драйверы используют подпрограмму RtlRunOnceExecuteOnce Для однократного вызова процедуры RunOnceInitialization . Операционная система гарантирует, что подпрограмма RunOnceInitialization не вызывается дважды для одного и того же значения параметра RunOnce .
Небольшое количество битов низкого порядка в расположении, на которое указывает параметр Context, зарезервировано для использования операционной системой. Подпрограмма RunOnceInitialization драйвера должна установить для этих зарезервированных битов значение 0 в выходном значении, которое она записывает в *Context. Константа RTL_RUN_ONCE_CTX_RESERVED_BITS, определенная в ntddk.h, указывает количество зарезервированных битов низкого порядка. В настоящее время RTL_RUN_ONCE_CTX_RESERVED_BITS определяется как два. Это означает, что драйвер должен установить для двух наименее значимых битов значения PVOID, на которое указывает контекст , равным нулю.
Примеры
Чтобы определить подпрограмму обратного вызова RunOnceInitialization , необходимо сначала предоставить объявление функции, определяющее тип определяемой процедуры обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.
Например, чтобы определить подпрограмму обратного вызова RunOnceInitialization с именем MyRunOnceInitialization, используйте тип RTL_RUN_ONCE_INIT_FN, как показано в следующем примере кода:
RTL_RUN_ONCE_INIT_FN MyRunOnceInitialization;
Затем реализуйте процедуру обратного вызова следующим образом:
_Use_decl_annotations_
ULONG
MyRunOnceInitialization(
PRTL_RUN_ONCE RunOnce,
PVOID Parameter,
PVOID *Context
)
{
// Function body
}
Тип функции RTL_RUN_ONCE_INIT_FN определен в файле заголовка Wdm.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку в _Use_decl_annotations_ определение функции. Заметка _Use_decl_annotations_ гарантирует, что будут использоваться заметки, которые применяются к типу функции RTL_RUN_ONCE_INIT_FN в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов WDM. Дополнительные сведения о _Use_decl_annotations_см. в статье Поведение функции с заметками.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Драйверы могут реализовывать подпрограмму RunOnceInitialization только в Windows Vista и более поздних версиях Windows. |
| Целевая платформа | Персональный компьютер |
| Верхняя часть | ntddk.h (включая Ntddk.h, Ntifs.h) |
| IRQL | Вызывается в IRQL <= APC_LEVEL. |