KsAllocateDeviceHeader-Funktion (ks.h)

Die KsAllocateDeviceHeader-Funktion weist den erforderlichen Geräteerweiterungsheader zu und initialisiert diese.

Syntax

KSDDKAPI NTSTATUS KsAllocateDeviceHeader(
  [out]          KSDEVICE_HEADER       *Header,
  [in]           ULONG                 ItemsCount,
  [in, optional] PKSOBJECT_CREATE_ITEM ItemsList
);

Parameter

[out] Header

Zeigt auf die Position, an der ein Zeiger auf den initialisierten Header zurückgegeben werden soll.

[in] ItemsCount

Gibt die Anzahl der Unterelemente in der ItemsList an. Dies sollte null sein, wenn eine ItemsList nicht übergeben wird.

[in, optional] ItemsList

Optional. Zeigt auf eine KSOBJECT_CREATE_ITEM-Struktur für jedes Unterelement. Wenn keine Unterelemente vorhanden sind, sollte dieser Wert NULL und ItemsCount 0 sein.

Rückgabewert

Die KsAllocateDeviceHeader-Funktion gibt STATUS_SUCCESS zurück, wenn sie erfolgreich oder STATUS_INSUFFICIENT_RESOURCES, wenn die erforderlichen Ressourcen nicht zugeordnet werden können.

Hinweise

Die KsAllocateDeviceHeader-Funktion weist Arbeitsspeicher für die KSDEVICE_HEADER-Struktur eines Geräts zu. Wenn der Header nicht mehr benötigt wird, sollte der Treiber die KsFreeDeviceHeader-Funktion aufrufen, um den zugewiesenen Arbeitsspeicher freizugeben.

Wenn Unterobjekte für ein bestimmtes Gerät vorhanden sind, muss der Treiber vor dem Aufruf von KsAllocateDeviceHeader einen Puffer mit ausgelagertem oder nicht ausgelagertem Speicher mit ausreichender Größe zuweisen, um eine KSOBJECT_CREATE_ITEM Struktur für jedes Unterobjekt zu speichern. Beispiel:

/* 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) ;

Treiber dürfen den für das Unterobjekt KSOBJECT_CREATE_ITEM Liste zugewiesenen Arbeitsspeicher erst nach dem Aufruf von KsFreeDeviceHeader freigeben. Wenn dies nicht geschieht, kann dies zu einer Fehlerüberprüfungsbedingung führen.

Anforderungen

Weitere Informationen

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader