функция обратного вызова RTL_RUN_ONCE_INIT_FN (ntddk.h)
Подпрограмма RunOnceInitialization выполняет однократную операцию инициализации.
Синтаксис
ULONG /* LOGICAL */
NTAPI
RTL_RUN_ONCE_INIT_FN (
_Inout_ PRTL_RUN_ONCE RunOnce,
_Inout_opt_ PVOID Parameter,
_Inout_opt_ PVOID *Context
);
typedef RTL_RUN_ONCE_INIT_FN *PRTL_RUN_ONCE_INIT_FN;
Параметры
[in, out] RunOnce
Указатель на структуру однократной инициализации RTL_RUN_ONCE, которую драйвер ранее передал в качестве параметра в подпрограмму RtlRunOn ceExecuteOnce, которая вызвала эту процедуру RunOnceInitialization.
[in, out] Parameter
Значение параметра параметра, переданное драйверу подпрограмме RtlRunOnceExecuteOnceOnce, которая вызвала эту подпрограмму RunOnceInitialization.
[out] Context
Указатель на переменную PVOID, в которую подпрограмма записывает данные инициализации.
Возвращаемое значение
Подпрограмма runOnceInitialization возвращает ненулевое значение для указания успешности и возвращает нулевое значение, указывающее на сбой.
Замечания
Реализованная драйвером подпрограмма RunOnceInitialization выполняет инициализацию для конкретного драйвера, а затем записывает данные инициализации в расположение памяти, на которое указывает параметр контекста контекста. Драйверы используют подпрограмму RtlRunOnceExecuteOnceOnce для однократного вызова подпрограммы RunOnceInitialization. Операционная система гарантирует, что подпрограмма runOnceInitialization не вызывается дважды для того же значения параметра RunOnce.
Небольшое количество битов низкого порядка в расположении, на которое указывает параметр контекста контекста, зарезервировано для использования операционной системой. Подпрограмма runOnceInitial ization драйвера должна задать для этих зарезервированных битов нулевое значение в выходном значении, которое оно записывает в *Context. Константа RTL_RUN_ONCE_CTX_RESERVED_BITS, определенная в ntddk.h, указывает количество зарезервированных битов с низким порядком. В настоящее время RTL_RUN_ONCE_CTX_RESERVED_BITS определяется как два, что означает, что драйвер должен задать два наименее значимых бита значения PVOID, на которые указывает Контекст нулю.
Примеры
Чтобы определить подпрограмму обратного вызова RunOnceInitialization, необходимо сначала указать объявление функции, определяющее тип определяемой процедуры обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализ кода для драйверов, статический проверяющий драйвер (SDV) и другие средства проверки подлинности, и это требование для написания драйверов для операционной системы Windows.
Например, чтобы определить подпрограмму обратного вызова RunOnceInitialization 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 (include Ntddk.h, Ntifs.h) |
| IRQL | Вызывается в IRQL <= APC_LEVEL. |