Funzione WdfMemoryCreatePreallocated (wdfmemory.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfMemoryCreatePreallocated crea un oggetto memoria framework per un buffer di memoria fornito dal driver.

Sintassi

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

Parametri

[in, optional] Attributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che contiene gli attributi dell'oggetto per il nuovo oggetto memoria. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[in] Buffer

Puntatore a un buffer fornito dal driver.

[in] BufferSize

Dimensione diversa da zero, in byte, del buffer a cui punta Buffer .

[out] Memory

Puntatore a una posizione che riceve un handle per il nuovo oggetto memoria.

Valore restituito

WdfMemoryCreatePreallocated restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente.

Per un elenco di altri valori restituiti che il metodo WdfMemoryCreatePreallocated potrebbe restituire, vedere Errori di creazione di oggetti framework.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Commenti

Il metodo WdfMemoryCreatePreallocated crea un oggetto memoria del framework per un buffer allocato o ottenuto in precedenza dal driver.

Il driver può chiamare WdfMemoryCreatePreallocated se è necessario creare oggetti di memoria che rappresentano buffer di memoria preesistenti. Ad esempio, il driver potrebbe ricevere una struttura definita dal driver all'interno di un buffer per una richiesta di I/O contenente un codice di controllo di I/O interno. Il driver può chiamare WdfMemoryCreatePreallocated per creare un oggetto memoria in modo che il driver possa passare la struttura a una destinazione di I/O.

Dopo che un driver ha chiamato WdfMemoryCreatePreallocated, il driver può chiamare WdfMemoryAssignBuffer per assegnare un buffer diverso all'oggetto memoria creato da WdfMemoryCreatePreallocated .

L'oggetto padre predefinito per ogni oggetto memoria è l'oggetto driver framework che rappresenta il driver che ha chiamato WdfMemoryCreatePreallocated. Se il driver crea un oggetto memoria che usa con un oggetto dispositivo specifico, un oggetto richiesta o un altro oggetto framework, deve impostare l'oggetto padre dell'oggetto memoria in modo appropriato. L'oggetto memory verrà eliminato quando l'oggetto padre viene eliminato. Se non si modifica l'oggetto padre predefinito, l'oggetto memoria rimarrà in memoria fino a quando il gestore di I/O non scarica il driver.

Un driver può anche eliminare un oggetto memoria chiamando WdfObjectDelete.

Quando viene eliminato l'oggetto memoria framework creato da WdfMemoryCreatePreallocated , il framework non dealloca il buffer preesistente. Analogamente, una chiamata a WdfMemoryAssignBuffer non dealloca il buffer assegnato in precedenza.

Per altre informazioni sugli oggetti di memoria del framework, vedere Uso dei buffer di memoria.

Esempio

Nell'esempio di codice seguente viene allocato un buffer e quindi viene creato un oggetto memoria framework per il buffer.

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

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2,0
Intestazione	wdfmemory.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)