Funzione WdfMemoryCreatePreallocated (wdfmemory.h)
[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 |
|---|---|
|
È stato rilevato un parametro non valido. |
|
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) |