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
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| Header | ks.h (einschließlich Ks.h) |
| Bibliothek | Ks.lib |
| IRQL | < DISPATCH_LEVEL |