KsAllocateObjectHeader, fonction (ks.h)

La fonction KsAllocateObjectHeader initialise l’en-tête de contexte de fichier requis.

Syntaxe

KSDDKAPI NTSTATUS KsAllocateObjectHeader(
  [out]          KSOBJECT_HEADER        *Header,
  [in]           ULONG                  ItemsCount,
  [in, optional] PKSOBJECT_CREATE_ITEM  ItemsList,
  [in]           PIRP                   Irp,
  [in]           const KSDISPATCH_TABLE *Table
);

Paramètres

[out] Header

Pointe vers l’emplacement alloué par l’appelant dans lequel retourner un pointeur vers le KSOBJECT_HEADER initialisé en cas de réussite.

[in] ItemsCount

Spécifie le nombre d’éléments de création d’objet dans itemsList à ajouter à l’en-tête d’objet une fois l’en-tête alloué. Cette valeur doit être égale à zéro si ItemsList a la valeur NULL.

[in, optional] ItemsList

Spécifie éventuellement un pointeur vers une mémoire tampon allouée par l’appelant contenant une série de structures KSOBJECT_CREATE_ITEM à ajouter à l’en-tête d’objet. Doit être défini sur NULL s’il n’existe aucun élément de création d’objet.

[in] Irp

Pointe vers l’IRP, de la fonction principale IRP_MJ_CREATE, qui contient les informations nécessaires pour terminer la création de l’en-tête d’objet.

[in] Table

Pointe vers une table de répartition initialisée pour cet objet de fichier.

Valeur retournée

La fonction KsAllocateObjectHeader retourne STATUS_SUCCESS en cas de réussite ou STATUS_INSUFFICIENT_RESOURCES si les ressources disponibles ne sont pas suffisantes pour répondre à la demande.

Remarques

Avant d’appeler cette routine, le pilote doit allouer un stockage résident système pour un KSDISPATCH_TABLE et initialiser la table de répartition. La mémoire de cette table de répartition ne peut pas être libérée tant que KsFreeObjectHeader n’est pas appelé.

KsAllocateObjectHeader alloue la mémoire pour la structure KSOBJECT_HEADER et retourne un pointeur vers l’en-tête à l’emplacement En-tête. Les pilotes ne doivent pas tenter de libérer la mémoire eux-mêmes, mais plutôt appeler KsFreeObjectHeader lorsque toutes les opérations nécessitant cet en-tête d’objet ont été effectuées.

S’il existe des sous-objets pour un appareil donné, le pilote doit, avant d’appeler KsAllocateObjectHeader, allouer une mémoire tampon de mémoire paginée ou non paginée de taille suffisante pour contenir une structure KSOBJECT_CREATE_ITEM pour chaque sous-objet. Par exemple :

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

Les pilotes ne doivent pas libérer la mémoire allouée pour le sous-objet KSOBJECT_CREATE_ITEM liste avant d’avoir appelé KsFreeDeviceHeader. Si vous ne le faites pas, vous pouvez créer un bogue case activée condition.

Configuration requise

Voir aussi

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader

KsFreeObjectHeader