Funzione WdfMemoryCreate (wdfmemory.h)
[Si applica a KMDF e UMDF]
Il metodo WdfMemoryCreate crea un oggetto memoria del framework e alloca un buffer di memoria di una dimensione specificata.
Sintassi
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
);
Parametri
[in, optional] Attributes
Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che contiene attributi di oggetto per il nuovo oggetto memoria. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.
[in] PoolType
Valore POOL_TYPE tipizzato che specifica il tipo di memoria da allocare.
[in, optional] PoolTag
Tag del pool definito dal driver per la memoria allocata. I debugger visualizzano questo tag. I driver specificano in genere una stringa di caratteri fino a quattro caratteri, delimitata da virgolette singole, in ordine inverso(ad esempio, 'dcba'). Il valore ASCII di ogni carattere del tag deve essere compreso tra 0 e 127. Il debug del driver è più semplice se ogni tag del pool è univoco.
Se PoolTag è zero, il framework fornisce un tag di pool predefinito che usa i primi quattro caratteri del nome del servizio in modalità kernel del driver. Se il nome del servizio inizia con "WDF" (il nome non è distinzione tra maiuscole e minuscole e non include le virgolette), vengono usati i quattro caratteri successivi. Se sono disponibili meno di quattro caratteri, viene usato "FxDr".
Per kmDF versione 1.5 e successiva, il driver può usare il membro DriverPoolTag della struttura WDF_DRIVER_CONFIG per specificare un tag di pool predefinito.
[in] BufferSize
Dimensione non zero specificata, in byte, del buffer.
[out] Memory
Puntatore a una posizione che riceve un handle per il nuovo oggetto memoria.
[out, optional] Buffer
Puntatore a una posizione che riceve un puntatore al buffer associato al nuovo oggetto memoria. Questo parametro è facoltativo e può essere NULL.
Valore restituito
WdfMemoryCreate 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 WdfMemoryCreate potrebbe restituire, vedere Errori di creazione dell'oggetto Framework.
Questo metodo potrebbe restituire anche altri valori NTSTATUS.
Commenti
Il metodo WdfMemoryCreate alloca un buffer delle dimensioni specificate dal parametro BufferSize e crea un oggetto di memoria del framework che rappresenta il buffer.
Per ottenere l'indirizzo del buffer, il driver può fornire un valore non NULL per il parametro Buffer della funzione WdfMemoryCreate oppure il driver può chiamare WdfMemoryGetBuffer.
È consigliabile zero memoria per l'allocazione della memoria, in particolare per le allocazioni copiate in una posizione non attendibile (modalità utente, tramite la rete e così via) per evitare la divulgazione di informazioni sensibili. WdfMemoryCreate non inizializza la memoria allocata per impostazione predefinita.
In base al modello di utilizzo del driver della memoria allocata, è consigliabile prendere in considerazione la raccomandazione per i writer di driver:
- RtlZeroMemory immediatamente dopo aver chiamato WdfMemoryCreate
- In alternativa, usare un'API di allocazione zero (ExAllocatePool2, ExAllocatePoolZero per la modalità kernel; HeapAlloc con il flag HEAP_ZERO_MEMORY per la modalità utente), seguito da WdfMemoryCreatePreallocated. Poiché il buffer pre-allocato non viene eliminato automaticamente come parte di WDFMEMORY o la relativa eliminazione padre, questo non è l'approccio migliore.
L'oggetto padre predefinito per ogni oggetto memoria è l'oggetto driver del framework che rappresenta il driver che ha chiamato WdfMemoryCreate. Se il driver crea un oggetto memoria usato con un oggetto dispositivo specifico, un oggetto request o un altro oggetto framework, deve impostare l'oggetto padre dell'oggetto memoria in modo appropriato. L'oggetto memoria e il relativo buffer verranno eliminati quando l'oggetto padre viene eliminato. Se non si modifica l'oggetto padre predefinito, l'oggetto memoria e il relativo buffer rimarranno finché il gestore di I/O scarica il driver.
Un driver può anche eliminare un oggetto memoria e il relativo buffer chiamando WdfObjectDelete.
Se BufferSize è minore di PAGE_SIZE, il sistema operativo fornisce al chiamante esattamente il numero di byte richiesti di memoria. Il buffer non è necessariamente allineato alla pagina, ma è allineato al numero di byte specificato dalla costante MEMORY_ALLOCATION_ALIGNMENT in Ntdef.h.
Se BufferSize è PAGE_SIZE o versione successiva, solo per KMDF il sistema alloca un buffer allineato a pagina. Se il parametro PoolType è NonPagedPool, il sistema alloca il numero di pagine necessarie per contenere tutti i byte. Tutti i byte inutilizzati nell'ultima pagina allocata sono essenzialmente sprecati.
Per altre informazioni sugli oggetti di memoria del framework, vedere Uso dei buffer di memoria.
Se il driver specifica PagedPool per PoolType, il metodo WdfMemoryCreate deve essere chiamato in IRQL <= APC_LEVEL. In caso contrario, il metodo può essere chiamato in IRQL <= DISPATCH_LEVEL.
Esempio
Nell'esempio di codice seguente viene creato un oggetto memoria del framework e viene allocato un buffer le cui dimensioni sono WRITE_BUFFER_SIZE. L'oggetto padre della memoria è un oggetto request.
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
);
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 | Vedere La sezione Osservazioni. |
| Regole di conformità DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf) |