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

Weitere Informationen

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader

KsFreeObjectHeader