функция обратного вызова RTL_RUN_ONCE_INIT_FN (ntddk.h)

Статья
03/08/2023

Подпрограмма 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.