KsAllocateObjectHeader-Funktion (ks.h)
Die KsAllocateObjectHeader-Funktion initialisiert den erforderlichen Dateikontextheader.
Syntax
KSDDKAPI NTSTATUS KsAllocateObjectHeader(
[out] KSOBJECT_HEADER *Header,
[in] ULONG ItemsCount,
[in, optional] PKSOBJECT_CREATE_ITEM ItemsList,
[in] PIRP Irp,
[in] const KSDISPATCH_TABLE *Table
);
Parameter
[out] Header
Verweist auf den vom Aufrufer zugewiesenen Speicherort, an dem bei erfolgreicher Ausführung ein Zeiger auf die initialisierte KSOBJECT_HEADER zurückgegeben werden soll.
[in] ItemsCount
Gibt die Anzahl der Objekterstellungselemente in ItemsList an, die dem Objektheader hinzugefügt werden sollen, sobald der Header zugeordnet ist. Dieser Wert sollte null sein, wenn ItemsListNULL ist.
[in, optional] ItemsList
Gibt optional einen Zeiger auf einen vom Aufrufer zugewiesenen Puffer an, der eine Reihe von KSOBJECT_CREATE_ITEM Strukturen enthält, die dem Objektheader hinzugefügt werden sollen. Muss auf NULL festgelegt werden, wenn keine Objekterstellungselemente vorhanden sind.
[in] Irp
Verweist auf den IRP der Hauptfunktion IRP_MJ_CREATE, der die erforderlichen Informationen zum Abschließen der Erstellung des Objektheaders enthält.
[in] Table
Verweist auf eine initialisierte Dispatchtabelle für dieses Dateiobjekt.
Rückgabewert
Die KsAllocateObjectHeader-Funktion gibt STATUS_SUCCESS zurück, wenn erfolgreich oder STATUS_INSUFFICIENT_RESOURCES , wenn nicht genügend Ressourcen zur Erfüllung der Anforderung verfügbar sind.
Hinweise
Vor dem Aufrufen dieser Routine muss der Treiber systemresidenten Speicher für eine KSDISPATCH_TABLE zuordnen und die Dispatchtabelle initialisieren. Der Arbeitsspeicher für diese Dispatchtabelle kann erst freigegeben werden , wenn KsFreeObjectHeader aufgerufen wird.
KsAllocateObjectHeader ordnet den Arbeitsspeicher für die KSOBJECT_HEADER-Struktur zu und gibt einen Zeiger auf den Header unter Header zurück. Treiber dürfen nicht versuchen, den Arbeitsspeicher selbst freizugeben, sondern KsFreeObjectHeader aufrufen, wenn alle Vorgänge, die diesen Objektheader erfordern, abgeschlossen sind.
Wenn Für ein bestimmtes Gerät Unterobjekte vorhanden sind, muss der Treiber vor dem Aufruf von KsAllocateObjectHeader einen Puffer mit ausgelagertem oder nicht ausgelagertem Speicher mit ausreichender Größe zuordnen, 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. Andernfalls kann dies zu einer Fehlerprüfungsbedingung führen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| Header | ks.h (ks.h einschließen) |
| Bibliothek | Ks.lib |
| IRQL | < DISPATCH_LEVEL |