Функция WdfMemoryCreate (wdfmemory.h)
[Применимо к KMDF и UMDF]
Метод WdfMemoryCreate создает объект памяти платформы и выделяет буфер памяти указанного размера.
Синтаксис
NTSTATUS WdfMemoryCreate(
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[in] POOL_TYPE PoolType,
[in, optional] ULONG PoolTag,
[in] size_t BufferSize,
[out] WDFMEMORY *Memory,
[out, optional] PVOID *Buffer
);
Параметры
[in, optional] Attributes
Указатель на структуру WDF_OBJECT_ATTRIBUTES , содержащую атрибуты объекта для нового объекта памяти. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.
[in] PoolType
POOL_TYPE типизированное значение, указывающее тип выделенной памяти.
[in, optional] PoolTag
Определенный драйвером тег пула для выделенной памяти. Отладчики отображают этот тег. Драйверы обычно указывают строку символов длиной до четырех символов, разделенную одними кавычками, в обратном порядке (например, dcba). Значение ASCII каждого символа в теге должно находиться в диапазоне от 0 до 127. Отладка драйвера упрощается, если каждый тег пула уникален.
Если значение PoolTag равно нулю, платформа предоставляет тег пула по умолчанию, который использует первые четыре символа имени службы драйвера в режиме ядра. Если имя службы начинается с "WDF" (имя не учитывает регистр и не содержит кавычки), используются следующие четыре символа. Если доступно менее четырех символов, используется FxDr.
Для KMDF версии 1.5 и более поздних драйвер может использовать элемент DriverPoolTag структуры WDF_DRIVER_CONFIG , чтобы указать тег пула по умолчанию.
[in] BufferSize
Ненулевой указанный размер буфера в байтах.
[out] Memory
Указатель на расположение, которое получает дескриптор нового объекта памяти.
[out, optional] Buffer
Указатель на расположение, которое получает указатель на буфер, связанный с новым объектом памяти. Этот параметр является необязательным и может иметь значение NULL.
Возвращаемое значение
WdfMemoryCreate возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:
| Код возврата | Описание |
|---|---|
|
Обнаружен недопустимый параметр. |
|
Недостаточно памяти. |
Список других возвращаемых значений, которые может возвращать метод WdfMemoryCreate , см. в разделе Ошибки создания объекта платформы.
Этот метод также может возвращать другие значения NTSTATUS.
Комментарии
Метод WdfMemoryCreate выделяет буфер размера, указанного параметром BufferSize , и создает объект памяти платформы, представляющий буфер.
Чтобы получить адрес буфера, драйвер может указать значение, отличное от NULL, для параметра Buffer функции WdfMemoryCreate или вызвать WdfMemoryGetBuffer.
Рекомендуется обнулять память для выделения памяти, особенно для выделений, которые будут скопированы в ненадежное расположение (пользовательский режим, по сети и т. д.), чтобы избежать раскрытия конфиденциальной информации. WdfMemoryCreate не инициализирует выделенную память по умолчанию.
В зависимости от модели использования выделенной памяти драйвером рекомендуется учесть следующее:
- RtlZeroMemory сразу после вызова WdfMemoryCreate
- Или используйте API с нулевым выделением (ExAllocatePool2, ExAllocatePoolZero для режима ядра; HeapAlloc с флагом HEAP_ZERO_MEMORY для пользовательского режима), за которым следует WdfMemoryCreatePreallocated. Так как предварительно выделенный буфер не удаляется автоматически в рамках WDFMEMORY или его родительского удаления, это не лучший подход.
Родительским объектом по умолчанию для каждого объекта памяти является объект драйвера платформы, представляющий драйвер, который называется WdfMemoryCreate. Если драйвер создает объект памяти, который он использует с определенным объектом устройства, объектом запроса или другим объектом платформы, он должен правильно задать родительский объект памяти. Объект памяти и его буфер будут удалены при удалении родительского объекта. Если не изменить родительский объект по умолчанию, объект памяти и его буфер останутся до тех пор, пока диспетчер ввода-вывода не выгрузит драйвер.
Драйвер также может удалить объект памяти и его буфер, вызвав WdfObjectDelete.
Если значение BufferSize меньше PAGE_SIZE, операционная система предоставляет вызывающей объекту точное количество запрошенных байтов памяти. Буфер не обязательно выравнивается по страницам, но он выравнивается по количеству байтов, заданному константой MEMORY_ALLOCATION_ALIGNMENT в ntdef.h.
Если параметр BufferSize PAGE_SIZE или больше, для KMDF только система выделяет буфер, выровняемый по страницам. Если параметр PoolType имеет значение NonPagedPool, система выделяет количество страниц, необходимых для хранения всех байтов. Все неиспользуемые байты на последней выделенной странице по сути тратятся впустую.
Дополнительные сведения об объектах памяти платформы см. в разделе Использование буферов памяти.
Если драйвер указывает PagedPool для poolType, метод WdfMemoryCreate должен вызываться в irQL <= APC_LEVEL. В противном случае метод можно вызвать в IRQL <= DISPATCH_LEVEL.
Примеры
В следующем примере кода создается объект памяти платформы и выделяется буфер, размер которого составляет WRITE_BUFFER_SIZE. Родительский объект памяти является объектом запроса.
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY writeBufferMemHandle;
PVOID writeBufferPointer;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
0,
WRITE_BUFFER_SIZE,
&writeBufferMemHandle,
&writeBufferPointer
);
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Минимальная версия KMDF | 1,0 |
| Минимальная версия UMDF | 2,0 |
| Верхняя часть | wdfmemory.h (включая Wdf.h) |
| Библиотека | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | См. раздел "Примечания". |
| Правила соответствия DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf) |