Функция WdfMemoryCreatePreallocated (wdfmemory.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfMemoryCreatePreallocated создает объект памяти платформы для буфера памяти, предоставленного драйвером.

Синтаксис

NTSTATUS WdfMemoryCreatePreallocated(
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]           __drv_aliasesMem PVOID Buffer,
  [in]           size_t                 BufferSize,
  [out]          WDFMEMORY              *Memory
);

Параметры

[in, optional] Attributes

Указатель на структуру WDF_OBJECT_ATTRIBUTES , содержащую атрибуты объекта для нового объекта памяти. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[in] Buffer

Указатель на буфер, предоставленный драйвером.

[in] BufferSize

Ненулевой размер (в байтах) буфера, на который указывает buffer .

[out] Memory

Указатель на расположение, которое получает дескриптор нового объекта памяти.

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

WdfMemoryCreatePreallocated возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.

Список других возвращаемых значений, которые может возвращать метод WdfMemoryCreatePreallocated , см. в разделе Ошибки создания объекта платформы.

Этот метод также может возвращать другие значения NTSTATUS.

Драйвер может вызвать WdfMemoryCreatePreallocated , если необходимо создать объекты памяти, представляющие существующие буферы памяти. Например, драйвер может получить определяемую драйвером структуру в буфере для запроса ввода-вывода, содержащего внутренний код элемента управления вводом-выводом. Драйвер может вызвать WdfMemoryCreatePreallocated , чтобы создать объект памяти, чтобы драйвер смог передать структуру целевому объекту ввода-вывода.

После вызова WdfMemoryCreatePreallocated драйвер может вызвать WdfMemoryAssignBuffer , чтобы назначить другой буфер объекту памяти, созданному WdfMemoryCreatePreallocated .

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

Драйвер также может удалить объект памяти, вызвав WdfObjectDelete.

При удалении объекта памяти платформы, созданного WdfMemoryCreatePreallocated , платформа не освобождает существующий буфер. Аналогичным образом вызов WdfMemoryAssignBuffer не освобождает ранее назначенный буфер.

Дополнительные сведения об объектах памяти платформы см. в разделе Использование буферов памяти.

Примеры

В следующем примере кода выделяется буфер, а затем создается объект памяти платформы для буфера.

PVOID  pBuffer = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;
WDFMEMORY  memHandle;

pBuffer = ExAllocatePoolWithTag(
                                NonPagedPool,
                                MY_BUFFER_SIZE,
                                MY_DRIVER_TAG
                                );
if (pBuffer == NULL){
    goto Error;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;

status = WdfMemoryCreatePreallocated(
                                     &attributes,
                                     pBuffer,
                                     MY_BUFFER_SIZE,
                                     &memHandle
                                     );

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfmemory.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)