Функция 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 для параметра WdfMemoryCreatebuffer, или драйвер может вызывать 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 выделяется только буфер с выравниванием страницы. Если параметр poolTypeNonPagedPool, система выделяет количество страниц, необходимых для хранения всех байтов. Все неиспользуемые байты на последней выделенной странице по сути неиспользуются.
Дополнительные сведения об объектах памяти платформы см. в разделе Использование буферов памяти.
Если драйвер указывает 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 (include Wdf.h) |
| Библиотека | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | См. раздел "Примечания". |
| правил соответствия DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf) |