Condividi tramite


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

Vedere anche

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader

KsFreeObjectHeader