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

Статья
03/08/2023

Подпрограмма LookasideListAllocateEx выделяет хранилище для новой записи списка lookaside, когда клиент запрашивает запись из списка lookaside, который является пустым.

Синтаксис

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

Параметры

[in] PoolType

Указывает тип хранилища, выделяемого для новой записи lookaside-list. Вызывающий объект задает этому параметру допустимое значение перечисления POOL_TYPE и, возможно, побитовое значение OR с одним из следующих битов флага:

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

Дополнительные сведения о флаге POOL_RAISE_IF_ALLOCATION_FAILURE см. в разделе ExAllocatePoolWithTag. Дополнительные сведения о флаге POOL_QUOTA_FAIL_INSTEAD_OF_RAISE см. в разделе ExAllocatePoolWithQuotaTag.

Если в вызове ExInitializeLookasideListEx , который инициализировал список lookaside, параметр Flags равен нулю, параметр PoolType , который получает подпрограмма LookasideListAllocateEx , будет тем же значением параметра PoolType , которое было передано в ExInitializeLookasideListEx.

Если в вызове ExInitializeLookasideListExфлаги = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, то параметр PoolType , который получает подпрограмма LookasideListAllocateEx , — это побитовое ИЛИ POOL_RAISE_IF_ALLOCATION_FAILURE и значение параметра PoolType , переданное в ExInitializeLookasideListEx. Подпрограмма LookasideListAllocateEx может передавать значение параметра PoolType без изменения в подпрограмму ExAllocatePoolWithTag.

Если в вызове ExInitializeLookasideListEx Флаги = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, параметр PoolType , который получает подпрограмма LookasideListAllocateEx , является побитовой or POOL_QUOTA_FAIL_INSTEAD_OF_RAISE и значением PoolType , переданным в ExInitializeLookasideListEx. Подпрограмма LookasideListAllocateEx может передавать значение параметра PoolType без изменения в подпрограмму ExAllocatePoolWithQuotaTag.

[in] NumberOfBytes

Задает размер выделенной записи lookaside-list в байтах.

[in] Tag

Указывает четырехбайтовой тег пула, используемый для пометки выделенного хранилища для новой записи lookaside-list. Дополнительные сведения о тегах пула см. в описании параметра Tag в ExAllocatePoolWithTag.

[in, out] Lookaside

Указатель на структуру LOOKASIDE_LIST_EX , описывающую список lookaside. Эта структура ранее была инициализирована подпрограммой ExInitializeLookasideListEx .

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

LookasideListAllocateEx возвращает указатель на выделенную запись lookaside-list. Если подпрограмма не может выделить запись, она возвращает значение NULL.

Драйвер, создающий список lookaside, может реализовать подпрограмму LookasideListAllocateEx для динамического выделения буферов для списка. Буфер, который не используется, сохраняется как запись в списке. Все записи в списке lookaside являются буферами единого размера, который драйвер указывает при инициализации списка.

Драйвер предоставляет указатель на настраиваемую подпрограмму LookasideListAllocateEx в качестве входного параметра в вызове ExInitializeLookasideListEx , который инициализирует список lookaside. Если драйвер задает этому параметру значение NULL, в списке lookaside используется подпрограмма выделения по умолчанию.

Драйвер вызывает подпрограмму ExAllocateFromLookasideListEx для выделения записи из списка просмотра. Если список пуст (не содержит записей), ExAllocateFromLookasideListEx вызывает LookasideListAllocateEx , чтобы динамически выделить хранилище для новой записи. LookasideListAllocateEx возвращает указатель на только что выделенную запись, если выделение выполнено успешно. В противном случае возвращается значение NULL.

Параметры PoolType, NumberOfBytes, Tag и Lookaside содержат те же значения, которые были переданы в качестве входных параметров в вызове ExInitializeLookasideListEx , который инициализировал список lookaside.

Подпрограмма LookasideListAllocateEx может использовать параметр Lookaside для доступа к данным частного контекста, связанного драйвером со списком lookaside. Дополнительные сведения см. в примере кода в exInitializeLookasideListEx.

Дополнительные сведения о списках lookaside см. в разделе Использование lookaside Списки.

Подпрограмма LookasideListAllocateEx вызывается в том же IRQL, что и вызов ExAllocateFromLookasideListEx, запрашивающий запись. Для вызова, запрашивающего запись, которая находится в памяти со страницами, вызывающий объект должен выполнять IRQL <= APC_LEVEL. Для вызова, запрашивающего запись, которая находится в неотгромождаемой памяти, вызывающий объект должен выполнять IRQL <= DISPATCH_LEVEL.

Примеры

Чтобы определить подпрограмму обратного вызова LookasideListAllocateEx , необходимо сначала предоставить объявление функции, определяющее тип определяемой процедуры обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить подпрограмму обратного вызова LookasideListAllocateEx с именем MyLookasideListAllocateEx, используйте тип FREE_FUNCTION_EX, как показано в следующем примере кода:

FREE_FUNCTION_EX MyLookasideListFreeEx;

Затем реализуйте процедуру обратного вызова следующим образом:

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

Тип функции FREE_FUNCTION_EX определен в файле заголовка Wdm.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку в _Use_decl_annotations_ определение функции. Заметка _Use_decl_annotations_ гарантирует использование заметок, которые применяются к типу функции FREE_FUNCTION_EX в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов WDM. Дополнительные сведения о _Use_decl_annotations_см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
IRQL	См. раздел "Примечания".