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’objets dans l'ItemsList à ajouter à l’en-tête de l’objet une fois que l’en-tête est alloué. Cette valeur doit être égale à zéro si ItemsList est 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 de l’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 de retour
La fonction KsAllocateObjectHeader retourne STATUS_SUCCESS si elle réussit ou STATUS_INSUFFICIENT_RESOURCES si des ressources insuffisantes sont disponibles pour répondre à la demande.
Remarques
Avant d’appeler cette routine, le pilote doit allouer le stockage résident du 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 est appelée.
KsAllocateObjectHeader alloue la mémoire de la structure KSOBJECT_HEADER et retourne un pointeur vers l’en-tête à d’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é terminées.
Si des sous-objets existent 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 la liste des sous-objets KSOBJECT_CREATE_ITEM tant qu’après l’appel de KsFreeDeviceHeader. L’échec de cette opération peut entraîner une condition de vérification des bogues.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Universel |
| d’en-tête | ks.h (include Ks.h) |
| bibliothèque | Ks.lib |
| IRQL | < DISPATCH_LEVEL |