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 in ItemsList. Questo valore deve essere zero se un elemento ItemsList non viene passato.

[in, optional] ItemsList

facoltativo. 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 è in grado di allocare le risorse necessarie.

Commenti

La funzione KsAllocateDeviceHeader alloca la 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 gli oggetti secondari esistono per un determinato dispositivo, il driver deve, prima di chiamare KsAllocateDeviceHeader, allocare un buffer di memoria paginata o non impaginata di dimensioni sufficienti per contenere una struttura KSOBJECT_CREATE_ITEM per ogni oggetto secondario. Ad 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 subobject finché non dopo aver chiamato KsFreeDeviceHeader. La mancata operazione può causare una condizione di controllo di bug.

Requisiti

Vedi anche

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader