Funzione WdfMemoryCreate (wdfmemory.h)
[Si applica a KMDF e UMDF]
Il metodo WdfMemoryCreate crea un oggetto memoria 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 gli attributi dell'oggetto per il nuovo oggetto memoria. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.
[in] PoolType
Valore POOL_TYPEtipizzato 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 di un massimo di quattro caratteri, delimitati da virgolette singole, in ordine inverso, ad esempio "dcba". Il valore ASCII di ogni carattere nel 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 del 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 fa 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 versioni 1.5 e successive, il driver può usare il DriverPoolTag membro della struttura WDF_DRIVER_CONFIG per specificare un tag del pool predefinito.
[in] BufferSize
Dimensione diversa da 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 potrebbero essere restituiti dal metodo WdfMemoryCreate, vedere Framework Object Creation Errors.
Questo metodo potrebbe anche restituire altri valori NTSTATUS .
Osservazioni:
Il metodo WdfMemoryCreate alloca un buffer delle dimensioni specificate dal parametro BufferSize e crea un oggetto memoria framework che rappresenta il buffer.
Per ottenere l'indirizzo del buffer, il driver può fornire un valore diNULL non per il parametro WdfMemoryCreate funzione Buffer oppure il driver può chiamare WdfMemoryGetBuffer.
È consigliabile zero memoria per l'allocazione di memoria, in particolare per le allocazioni che verranno copiate in un percorso non attendibile (modalità utente, in rete e così via) per evitare di divulgare informazioni riservate. WdfMemoryCreare 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 WdfMemoryCreare
- In alternativa, usare un'API di allocazione zero (ExAllocatePool2, ExAllocatePoolZer o per la modalità kernel; HeapAlloc con il flag di HEAP_ZERO_MEMORY per la modalità utente), seguito da WdfMemoryCreatePreallocated. Poiché il buffer preallocato non viene eliminato automaticamente come parte di WDFMEMORY o l'eliminazione padre, questo non è l'approccio migliore.
L'oggetto padre predefinito per ogni oggetto memoria è l'oggetto driver framework che rappresenta il driver che ha chiamato WdfMemoryCreate. Se il driver crea un oggetto memoria usato con un oggetto dispositivo specifico, un oggetto richiesta o un altro oggetto framework, deve impostare l'elemento 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 non 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 assegna esattamente al chiamante il numero di byte richiesti di memoria. Il buffer non è necessariamente allineato alla pagina, ma è allineato in base al numero di byte specificato dalla costante MEMORY_ALLOCATION_ALIGNMENT in Ntdef.h.
Se bufferSize è PAGE_SIZE o superiore, solo per KMDF il sistema alloca un buffer allineato alla 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 Using Memory Buffers.
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.
Esempi
Nell'esempio di codice seguente viene creato un oggetto memoria framework e viene allocato un buffer le cui dimensioni sono WRITE_BUFFER_SIZE. L'elemento padre dell'oggetto memoria è un oggetto richiesta.
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 minima di KMDF | 1.0 |
| versione minima di UMDF | 2.0 |
| intestazione | wdfmemory.h (include Wdf.h) |
| Biblioteca | 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) |