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
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| En-tête | ks.h (inclure Ks.h) |
| Bibliothèque | Ks.lib |
| IRQL | < DISPATCH_LEVEL |