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

[Применимо к 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, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

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

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

Комментарии

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

Драйвер может вызвать 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
                                     );

Требования

См. также раздел

ExAllocatePoolWithTag

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfMemoryAssignBuffer

WdfMemoryCreate

WdfMemoryCreateFromLookaside