Funzione KsAllocateObjectHeader (ks.h)
La funzione KsAllocateObjectHeader inizializza l'intestazione del contesto di file richiesta.
Sintassi
KSDDKAPI NTSTATUS KsAllocateObjectHeader(
[out] KSOBJECT_HEADER *Header,
[in] ULONG ItemsCount,
[in, optional] PKSOBJECT_CREATE_ITEM ItemsList,
[in] PIRP Irp,
[in] const KSDISPATCH_TABLE *Table
);
Parametri
[out] Header
Punta alla posizione allocata dal chiamante in cui restituire un puntatore al KSOBJECT_HEADER inizializzato in caso di esito positivo.
[in] ItemsCount
Specifica il numero di elementi di creazione dell'oggetto nel ItemsList da aggiungere all'intestazione dell'oggetto dopo l'allocazione dell'intestazione. Questo valore deve essere zero se ItemsList è NULL.
[in, optional] ItemsList
Facoltativamente, specifica un puntatore a un buffer allocato dal chiamante contenente una serie di strutture KSOBJECT_CREATE_ITEM da aggiungere all'intestazione dell'oggetto. Deve essere impostato su NULL se non sono presenti elementi di creazione di oggetti.
[in] Irp
Punta all'IRP, della funzione principale IRP_MJ_CREATE, che contiene le informazioni necessarie per completare la creazione dell'intestazione dell'oggetto.
[in] Table
Punta a una tabella dispatch inizializzata per questo oggetto file.
Valore restituito
La funzione KsAllocateObjectHeader restituisce STATUS_SUCCESS se ha esito positivo o STATUS_INSUFFICIENT_RESOURCES se non sono disponibili risorse sufficienti per soddisfare la richiesta.
Osservazioni
Prima di chiamare questa routine, il driver deve allocare l'archiviazione residente nel sistema per un KSDISPATCH_TABLE e inizializzare la tabella dispatch. La memoria per questa tabella dispatch non può essere rilasciata fino a quando non viene chiamato KsFreeObjectHeader.
KsAllocateObjectHeader alloca la memoria per la struttura KSOBJECT_HEADER e restituisce un puntatore all'intestazione Header. I driver non devono tentare di liberare la memoria, ma chiamare KsFreeObjectHeader quando tutte le operazioni che richiedono l'intestazione dell'oggetto sono state completate.
Se esistono oggetti secondari per un determinato dispositivo, è necessario che il driver, prima di chiamare KsAllocateObjectHeader, 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 l'elenco di KSOBJECT_CREATE_ITEM oggetto secondario fino a quando non viene 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 |