PVIDEO_HW_QUERY_INTERFACE fonction de rappel (video.h)

Article
08/07/2023

HwVidQueryInterface retourne une interface fonctionnelle implémentée par un pilote miniport qu’un appareil enfant peut appeler.

Syntaxe

PVIDEO_HW_QUERY_INTERFACE PvideoHwQueryInterface;

VP_STATUS PvideoHwQueryInterface(
  PVOID HwDeviceExtension,
  PQUERY_INTERFACE QueryInterface
)
{...}

Paramètres

HwDeviceExtension

Pointeur vers la zone de stockage par adaptateur du pilote miniport. Pour plus d’informations, consultez Extensions d’appareil.

QueryInterface

Pointeur vers une structure QUERY_INTERFACE dans laquelle le pilote miniport doit retourner des informations sur l’interface qu’il prend en charge.

Valeur retournée

HwVidQueryInterface doit retourner NO_ERROR en cas de réussite ; sinon, il doit retourner le code d’erreur approprié. Par exemple, un pilote miniport doit retourner ERROR_OUTOFMEMORY s’il ne peut pas allouer de mémoire pour terminer l’opération.

Remarques

HwVidQueryInterface expose un mécanisme de communication entre le pilote de miniport vidéo et le pilote d’un appareil enfant. Un pilote miniport qui expose un tel mécanisme doit implémenter cette fonction.

Le port vidéo appelle HwVidQueryInterface lorsqu’il reçoit une demande de IRP_MN_QUERY_INTERFACE. Si le pilote miniport échoue à l’appel, le pilote de port vidéo transmet la demande au parent de l’appareil du pilote miniport.

HwVidQueryInterface doit renseigner les membres de la structure INTERFACE vers lesquels QueryInterface-Interface> pointe comme suit :

Définissez Size sur le nombre d’octets dans la structure INTERFACE. Cette valeur ne doit pas dépasser le nombre d’octets spécifié par QueryInterface->Size.
Définissez Version sur la version de l’interface retournée par le pilote miniport. Le pilote miniport doit correspondre le mieux à la version demandée par le pilote enfant dans QueryInterface->Version.
Définissez Contexte pour qu’il pointe vers un contexte défini par un pilote miniport pour l’interface. En règle générale, un pilote miniport définit Context pour qu’il pointe vers l’extension de périphérique identifiée par HwDeviceExtension.
Initialisez InterfaceReference et InterfaceDereference pour pointer vers les routines de référence et de déréférence implémentées par le pilote miniport pour cette interface.
Initialisez tous les membres supplémentaires spécifiques à l’interface pour qu’ils pointent vers les routines appropriées de l’interface exposée.

Un pilote miniport qui retourne une interface est chargé de référencer l’interface en appelant QueryInterface->Interface.InterfaceReference. Le pilote enfant qui demande l’interface est chargé de la déréférencer lorsque le pilote n’a plus besoin de l’interface en appelant QueryInterface->Interface.InterfaceDereference. Si le pilote enfant transmet l’interface à un autre composant, l’enfant est responsable de la prise d’une autre référence et l’autre composant est responsable de la suppression de la référence supplémentaire lorsqu’il n’a plus besoin d’accéder à l’interface. Le référencement permet à un parent de déterminer quand l’interface est toujours requise par l’appareil enfant et, par conséquent, quand le parent peut libérer toutes les ressources associées à l’interface.

Le pilote d’un appareil enfant peut appeler le pilote miniport via les fonctions exposées par HwVidQueryInterface à tout moment à l’insu du pilote de port vidéo. Par conséquent, le pilote miniport doit synchroniser l’accès à lui-même en acquérant et en libérant le verrou d’appareil géré par le pilote du port vidéo dans toutes les fonctions exposées par HwVidQueryInterface.

Un appareil enfant est énuméré par HwVidGetVideoChildDescriptor.

HwVidQueryInterface doit être rendu paginable.