Función WdfMemoryCreatePreallocated (wdfmemory.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfMemoryCreatePreallocated crea un objeto de memoria de marco para un búfer de memoria proporcionado por el controlador.

Sintaxis

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

Parámetros

[in, optional] Attributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES que contiene atributos de objeto para el nuevo objeto de memoria. Este parámetro es opcional y se puede WDF_NO_OBJECT_ATTRIBUTES.

[in] Buffer

Puntero a un búfer proporcionado por el controlador.

[in] BufferSize

Tamaño distinto de cero, en bytes, del búfer al que apunta buffer .

[out] Memory

Puntero a una ubicación que recibe un identificador para el nuevo objeto de memoria.

Valor devuelto

WdfMemoryCreatePreallocated devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Se ha detectado un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	No había memoria suficiente.

Para obtener una lista de otros valores devueltos que el método WdfMemoryCreatePreallocated podría devolver, vea Errores de creación de objetos de marco.

Este método también podría devolver otros valores NTSTATUS.

Comentarios

El método WdfMemoryCreatePreallocated crea un objeto de memoria de marco para un búfer que el controlador ha asignado o obtenido previamente.

El controlador puede llamar a WdfMemoryCreatePreallocated si necesita crear objetos de memoria que representen búferes de memoria preexistentes. Por ejemplo, el controlador podría recibir una estructura definida por el controlador dentro de un búfer para una solicitud de E/S que contiene un código de control de E/S interno. El controlador puede llamar a WdfMemoryCreatePreallocated para crear un objeto de memoria para que el controlador pueda pasar la estructura a un destino de E/S.

Una vez que un controlador ha llamado a WdfMemoryCreatePreallocated, el controlador puede llamar a WdfMemoryAssignBuffer para asignar un búfer diferente al objeto de memoria que WdfMemoryCreatePreallocated creó.

El objeto primario predeterminado para cada objeto de memoria es el objeto del controlador de marco que representa el controlador que llamó a WdfMemoryCreatePreallocated. Si el controlador crea un objeto de memoria que usa con un objeto de dispositivo específico, un objeto de solicitud u otro objeto de marco, debe establecer el elemento primario del objeto de memoria adecuadamente. El objeto de memoria se eliminará cuando se elimine el objeto primario. Si no cambia el objeto primario predeterminado, el objeto de memoria permanecerá en memoria hasta que el administrador de E/S descargue el controlador.

Un controlador también puede eliminar un objeto de memoria llamando a WdfObjectDelete.

Cuando se elimina el objeto de memoria del marco que WdfMemoryCreatePreallocated creó, el marco no desasigna el búfer preexistente. Del mismo modo, una llamada a WdfMemoryAssignBuffer no desasigna el búfer asignado previamente.

Para obtener más información sobre los objetos de memoria del marco, consulte Uso de búferes de memoria.

Ejemplos

En el ejemplo de código siguiente se asigna un búfer y, a continuación, se crea un objeto de memoria de marco para el búfer.

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
                                     );

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfmemory.h (incluya Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Reglas de cumplimiento de DDI	BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)