Funzione KsAllocateDeviceHeader (ks.h)
La funzione KsAllocateDeviceHeader alloca e inizializza l'intestazione dell'estensione del dispositivo richiesta.
Sintassi
KSDDKAPI NTSTATUS KsAllocateDeviceHeader(
[out] KSDEVICE_HEADER *Header,
[in] ULONG ItemsCount,
[in, optional] PKSOBJECT_CREATE_ITEM ItemsList
);
Parametri
[out] Header
Punta alla posizione in cui restituire un puntatore all'intestazione inizializzata.
[in] ItemsCount
Specifica il numero di elementi secondari nel ItemsList. Deve essere zero se non viene passato un ItemsList.
[in, optional] ItemsList
Opzionale. Punta a una struttura KSOBJECT_CREATE_ITEM per ogni elemento secondario. Se non sono presenti elementi secondari, questo valore deve essere NULL e ItemsCount deve essere zero.
Valore restituito
La funzione KsAllocateDeviceHeader restituisce STATUS_SUCCESS se ha esito positivo o STATUS_INSUFFICIENT_RESOURCES se non è possibile allocare le risorse necessarie.
Osservazioni
La funzione KsAllocateDeviceHeader alloca memoria per la struttura KSDEVICE_HEADER per un dispositivo. Quando l'intestazione non è più necessaria, il driver deve chiamare la funzione KsFreeDeviceHeader per liberare la memoria allocata.
Se esistono oggetti secondari per un determinato dispositivo, il driver deve, prima di chiamare KsAllocateDeviceHeader, allocare un buffer di memoria di paging o di dimensioni sufficienti per contenere una struttura KSOBJECT_CREATE_ITEM per ogni sottooggetto. Per esempio:
/* Allocate a buffer for 4 subobjects for a given streaming device */
PKSOBJECT_CREATE_ITEM createBuffer ;
ULONG bufferSize = (sizeof (KSOBJECT_CREATE_ITEM)) * 4 ;
createBuffer = (PKSOBJECT_CREATE_ITEM)
ExAllocatePoolWithTag (PagedPool, bufferSize) ;
I driver non devono liberare la memoria allocata per il sottooggetto KSOBJECT_CREATE_ITEM elenco finché non dopo aver chiamato KsFreeDeviceHeader. In caso contrario, può verificarsi una condizione di controllo dei bug.
Fabbisogno
| Requisito | Valore |
|---|---|
| piattaforma di destinazione | Universale |
| intestazione | ks.h (include Ks.h) |
| libreria | Ks.lib |
| IRQL | < DISPATCH_LEVEL |