Structure KSIDENTIFIER (ks.h)

La structure KSIDENTIFIER spécifie un GUID qui identifie de manière unique un ensemble associé de GUID et une valeur d’index pour faire référence à un membre spécifique au sein de ce jeu.

Les typesdef KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM et KSPROPERTY sont des alias pour la structure KSIDENTIFIER . Par conséquent, leurs définitions sont identiques. Pour plus d’informations sur l’utilisation, consultez les rubriques typedef individuelles.

Syntaxe

typedef struct {
  union {
    struct {
      GUID  Set;
      ULONG Id;
      ULONG Flags;
    } _IDENTIFIER;
    struct {
      GUID  Set;
      ULONG Id;
      ULONG Flags;
    };
    LONGLONG Alignment;
  };
} KSIDENTIFIER, *PKSIDENTIFIER;

Membres

_IDENTIFIER

Consultez la section Notes ci-dessous.

_IDENTIFIER.Set

Consultez la section Notes ci-dessous.

_IDENTIFIER.Id

Consultez la section Notes ci-dessous.

_IDENTIFIER.Flags

Consultez la section Notes ci-dessous.

Set

Consultez la section Notes ci-dessous.

Id

Consultez la section Notes ci-dessous.

Flags

Consultez la section Notes ci-dessous.

Alignment

Consultez la section Notes ci-dessous.

Remarques

Descriptions des membres KSIDENTIFIER

Set

Spécifie un GUID qui identifie une propriété de diffusion en continu du noyau, un événement, une méthode, un jeu de bus de communication. La structure KSPIN_INTERFACE décrit une interface spécifique au sein d’un jeu d’interface. La structure KSDEGRADE contient des spécificités des stratégies de dégradation. Pour plus d’informations, consultez la section Remarques ci-dessous.

Id

Spécifie le membre de la propriété, de l’événement, de la méthode définie. Pour KSPIN_MEDIUM, identifie une connexion unique sur le bus. Pour KSPIN_INTERFACE, spécifie le numéro d’ID de cette interface particulière dans le jeu d’interface. Pour KSDEGRADE, spécifie l’identificateur spécifique au jeu pour un élément dans le jeu.

Flags

Spécifie le type de demande. Si vous écrivez un minidriver de classe de flux, consultez également KSPROPERTY_ITEM pour obtenir des informations d’indicateur spécifiques à la classe. Les indicateurs doivent être l’une des valeurs répertoriées dans le tableau suivant. Certains indicateurs peuvent être combinés à l’aide d’une opération OR au niveau du bit.

Pour plus d’informations sur l’utilisation, consultez les rubriques typedef KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM et KSPROPERTY .

Spécifie le type de requête KSPROPERTY .

Valeur de l’indicateur KSPROPERTY	Description
KSPROPERTY_TYPE_GET	Récupère la valeur de l’élément de propriété spécifié.
KSPROPERTY_TYPE_SET	Définit la valeur de l’élément de propriété spécifié.
KSPROPERTY_TYPE_SETSUPPORT	Demande si le pilote prend en charge cette propriété définie.
KSPROPERTY_TYPE_BASICSUPPORT	Interroge les types de requêtes que le pilote gère pour cet élément de propriété. Retourne KSPROPERTY_TYPE_GET ou KSPROPERTY_TYPE_SET ou les deux. Tous les jeux de propriétés doivent prendre en charge cet indicateur.
KSPROPERTY_TYPE_DEFAULTVALUES	Interroge les valeurs par défaut de l’élément de propriété spécifié. Retourne une structure de type KSPROPERTY_VALUES.
KSPROPERTY_TYPE_RELATIONS	Interroge toutes les propriétés avec des dépendances sur le paramètre actuel de cette propriété. Spécifie que la liste des relations de propriété doit être retournée, ou la quantité de salle de mémoire tampon requise par une telle liste si la mémoire tampon de retour est de la taille d’un ULONG. Chaque élément est sur FILE_QUAD_ALIGNMENT, précédé d’une structure KSMULTIPLE_ITEM. Cela n’est pas valide lors de l’interrogation de la prise en charge du jeu de propriétés en général. Tous les jeux de propriétés doivent prendre en charge cet indicateur.
KSPROPERTY_TYPE_SERIALIZESET	Sérialisez le jeu de propriétés à l’aide des structures KSPROPERTY_SERIAL et KSPROPERTY_SERIALHDR standard.
KSPROPERTY_TYPE_UNSERIALIZESET	Annulez l’ensemble de propriétés à l’aide des structures KSPROPERTY_SERIALHDR et KSPROPERTY_SERIAL standard.
KSPROPERTY_TYPE_SERIALIZESIZE	Retourne un ULONG spécifiant la taille des données de propriété lorsqu’elles sont sérialisées dans le cadre d’une demande de KSPROPERTY_TYPE_SERIALIZESET. Une taille de zéro indique qu’une propriété n’a pas besoin d’être sérialisée.
KSPROPERTY_TYPE_SERIALIZERAW	Spécifie que les propriétés de ce jeu doivent être sérialisées par le gestionnaire de prise en charge du jeu de propriétés, le cas échéant. Si ce n’est pas le cas, l’appel échoue. Le format de sérialisation est privé. Cette opération doit être l’inverse de KSPROPERTY_TYPE_UNSERIALIZERAW.
KSPROPERTY_TYPE_TOPOLOGY	La propriété passée est de type KSP_NODE, où NodeId indique l’ID numérique du nœud de topologie. Ne définissez pas cet indicateur seul ; à la place, OU avec d’autres indicateurs dans cette table.
KSPROPERTY_TYPE_UNSERIALIZERAW	Spécifie que la mémoire tampon fournie contient un groupe de propriétés qui appartiennent à ce jeu qui doivent être désérialisées par le gestionnaire de prise en charge du jeu de propriétés, le cas échéant. Si ce n’est pas le cas, l’appel échoue. Le format de sérialisation est privé. Cette opération doit être l’inverse de KSPROPERTY_TYPE_SERIALIZERAW.

Spécifie le type de requête KSEVENT . Cet indicateur doit être l’une des valeurs répertoriées dans le tableau suivant.

Valeur de l’indicateur KSEVENT	Description
KSEVENT_TYPE_ENABLE	Active la notification d’événement pour ce type d’événement. Le pilote continue la notification d’événement jusqu’à ce que le client la désactive explicitement.
KSEVENT_TYPE_ONESHOT	Active la notification d’événement pour l’occurrence suivante de cet événement uniquement. Le client n’a pas besoin (et ne doit pas) désactiver l’événement une fois qu’il s’est produit.
KSEVENT_TYPE_SETSUPPORT	Requêtes pour la liste des jeux d’événements ou pour la prise en charge d’un jeu d’événements particulier.
KSEVENT_TYPE_BASICSUPPORT	Requêtes pour la prise en charge d’un type d’événement particulier.
KSEVENT_TYPE_ENABLEBUFFERED	Au lieu de notifier le client, le pilote met en file d’attente les notifications d’événements. Le client émet ensuite une deuxième demande IOCTL_KS_ENABLE_EVENT avec le KSEVENT_TYPE_QUERYBUFFER pour recevoir les notifications d’événements mis en file d’attente.
KSEVENT_TYPE_TOPOLOGY	Indique que l’événement passé est de type KSE_NODE, où NodeId indique l’ID numérique du nœud de topologie. Ne définissez pas cet indicateur seul ; à la place, OU avec d’autres indicateurs de cette liste.
KSEVENT_TYPE_QUERYBUFFER	Récupère la notification d’événement mis en mémoire tampon suivante.

Spécifie le type de requête KSMETHOD . Consultez également les indicateurs de KSMETHOD_TYPE_Xxx pour KSMETHOD_ITEM. Une demande peut contenir une combinaison des valeurs répertoriées dans le tableau suivant.

Valeur de l’indicateur KSMETHOD	Description
KSMETHOD_TYPE_BASICSUPPORT	Indique d’interroger le minidriver pour déterminer s’il prend en charge la méthode spécifiée du jeu de méthodes.
KSMETHOD_TYPE_SEND	Indique que le minidriver doit exécuter la méthode spécifiée. L’effet de la méthode sur les paramètres donnés doit être connu du client, c’est-à-dire si les paramètres sont lus, écrits dans, les deux ou aucun des deux. Le minidriver utilise la structure KSMETHOD_ITEM pour spécifier l’effet de la méthode sur les paramètres.
KSMETHOD_TYPE_SETSUPPORT	Indique d’interroger le minidriver pour déterminer s’il prend en charge l’ensemble de méthodes spécifié.
KSMETHOD_TYPE_TOPOLOGY	Indique que la méthode spécifiée est de type KSM_NODE, où le membre NodeId est l’identificateur du nœud de topologie. Ne définissez pas cet indicateur seul ; à la place, OU avec d’autres indicateurs de cette liste.

Pour KSDEGRADE, spécifie le pourcentage actuel de dégradation, exprimé en parties par millier (où une valeur de 1 000 ne représente aucune dégradation), ou spécifie la durée en unités natives spécifiée par l’interface.

Alignment

Non utilisé. Membre d’une union sans nom utilisée pour forcer l’alignement correct sur la structure sans nom.

Notes

Pour plus d’informations sur l’utilisation, consultez les rubriques typedef KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM et KSPROPERTY .

L’utilisation d’un ID dans le jeu permet d’effectuer une seule comparaison de grande taille pour un identificateur d’ensemble, puis de comparer rapidement plus petites (par exemple, en utilisant une instruction switch pour les identificateurs au sein d’un jeu). Par exemple, un jeu de propriétés est référencé par un identificateur GUID unique, et les propriétés de ce jeu sont référencées par l’ID court.

Les jeux method, Event, Interface et medium peuvent être considérés comme des « classes » d’ensembles.

La taille de la mémoire tampon de sortie passée détermine les données retournées à partir d’une demande de KSPROPERTY_TYPE_BASICSUPPORT. Si la mémoire tampon de sortie est de la taille d’un ULONG, seuls les indicateurs d’accès sont retournés. Si la mémoire tampon de sortie est la taille de la structure KSPROPERTY_DESCRIPTION , la structure est remplie avec les indicateurs d’accès, la taille inclusive des informations de valeurs entières, les informations de type de valeur de propriété et le nombre de listes de membres qui correspondent à la structure.

Pour une requête KSPROPERTY_TYPE_RELATIONS, les données retournées dépendent également de la taille de la mémoire tampon de sortie. Si la taille de la mémoire tampon de sortie est égale à zéro, la taille requise pour retourner les propriétés associées est retournée dans BytesReturned avec un avertissement status de STATUS_BUFFER_OVERFLOW. Si la mémoire tampon est de la taille d’une structure KSMULTIPLE_ITEM , la taille d’octets et le nombre de relations sont retournés. Sinon, la mémoire tampon est censée être suffisamment longue pour renvoyer la structure KSMULTIPLE_ITEM et tous les identificateurs de propriété associés, qui sont retournés sous la forme d’une liste de structures KSIDENTIFIER .

KSPROPERTY_TYPE_SERIALIZESET et les demandes de KSPROPERTY_TYPE_UNSERIALIZESET autorisent l’interaction avec plusieurs propriétés avec un seul appel du client. Si le gestionnaire de diffusion en continu du noyau est utilisé pour traiter les demandes de propriété, celles-ci sont divisées en plusieurs appels par la fonction KsPropertyHandler . Lors de l’utilisation de ce gestionnaire, la définition du jeu de propriétés contrôle les propriétés à sérialiser.

Pour les demandes de sérialisation, le membre SerializedSize de la structure KSPROPERTY_ITEM appropriée est vérifié pour une valeur différente de zéro qui indique la taille, en octets, de la propriété. Si la valeur du membre SerializedSize est 1, elle est inconnue et doit être interrogée (toutes les propriétés inconnues commencent par une structure KSMULTIPLE_ITEM qui peut être interrogée séparément). Pour interroger la taille totale d’une sérialisation, le client passe une mémoire tampon de longueur nulle dans l’appel à DeviceIoControl. BytesReturned retourne ensuite la taille, en octets, que la mémoire tampon doit être pour sérialiser l’ensemble, et un avertissement status de STATUS_BUFFER_OVERFLOW. Une mémoire tampon allouée à cette taille peut ensuite être remplie avec les données sérialisées.

Le format de la mémoire tampon de sérialisation est un KSPROPERTY_SERIALHDR, suivi de propriétés sérialisées. Chaque propriété qui suit contient un en-tête (KSPROPERTY_SERIAL), suivi des données de propriété, avec le début de chaque propriété sur FILE_LONG_ALIGNMENT. Notez que la structure d’en-tête série est définie pour être sur FILE_LONG_ALIGNMENT.

KSPROPERTY_TYPE_SERIALIZERAW et KSPROPERTY_TYPE_UNSERIALIZERAW sont pris en charge si un gestionnaire d’éléments de propriété existe. La fonction KsPropertyHandler appelle le gestionnaire fourni par le minidriver. La taille de la mémoire tampon requise pour la sérialisation peut également être interrogée en passant une mémoire tampon de longueur nulle à une requête brute sérialisée. Étant donné que les gestionnaires sont attachés à des éléments de propriété plutôt qu’au jeu de propriétés, un élément spécifique dans le jeu de propriétés doit être spécifié dans le paramètre Property . Ce gestionnaire peut traiter plusieurs propriétés au sein de l’ensemble.

Microsoft fournit plusieurs GUID d’ensemble de propriétés définis par le système. Les minidrivers spécifient l’un de ces GUID dans le membre Set . Les jeux de propriétés de diffusion en continu du noyau commencent généralement par un préfixe KSPROPSETID ou PROPSETID . Les jeux de propriétés de diffusion en continu du noyau sont définis dans ks.h, ksmedia.h, bdamedia.h et éventuellement dans d’autres fichiers d’en-tête.

Pour plus d’informations sur les propriétés de diffusion en continu du noyau, consultez Propriétés, événements et méthodes KS.

Microsoft fournit plusieurs GUID de jeu d’événements définis par le système. Les minidrivers spécifient l’un de ces GUID dans le membre Set . Les jeux d’événements de diffusion en continu du noyau commencent généralement par un préfixe KSEVENTSETID . Les jeux d’événements de diffusion en continu du noyau sont définis dans ks.h, ksmedia.h, bdamedia.h et éventuellement d’autres fichiers d’en-tête.

Pour plus d’informations sur les événements de diffusion en continu du noyau, consultez Propriétés, événements et méthodes KS.

Microsoft fournit plusieurs GUID d’ensemble de méthodes définis par le système. Les minidrivers spécifient l’un de ces GUID dans le membre Set . Les jeux de méthodes de diffusion en continu du noyau commencent généralement par un préfixe KSMETHODSETID . Les jeux de méthodes de diffusion en continu du noyau sont définis dans ks.h, ksmedia.h, bdamedia.h et éventuellement dans d’autres fichiers d’en-tête.

Pour plus d’informations sur les méthodes de diffusion en continu du noyau, consultez Propriétés, événements et méthodes KS.

Un client peut utiliser la requête IOCTL_KS_METHOD avec la structure KSMETHOD pour exécuter des méthodes sur un objet de diffusion en continu de noyau que le minidriver gère. Pour plus d’informations, consultez Méthodes KS.

La structure KSPIN_MEDIUM identifie un support, avec un GUID de support unique et un identificateur de instance, qui est généré de manière spécifique au bus. Il existe une valeur d’identificateur réservée KSMEDIUM_TYPE_ANYINSTANCE qui est utilisée lorsque les instances de bus ne sont pas préoccupantes. Par exemple, le KSMEDIUMSETID_Standard fait référence au bus système, dont il ne doit y avoir qu’un seul. Cet identificateur de instance est donc toujours utilisé pour des raisons pratiques.

Une broche peut prendre en charge plusieurs supports et interfaces sur ces supports. La façon dont une broche est décrite implique que la liste des interfaces est prise en charge sur tous les supports énumérés pour une broche. S’il existe un cas où cela n’est pas vrai, une autre broche peut être utilisée pour décrire chaque sous-ensemble d’interfaces pour les supports spécifiques.

Le support est également mis en cache par la diffusion en continu du noyau pour accélérer la recherche d’une connexion possible.

Vous trouverez un exemple d’utilisation de cette structure dans un exemple de tuner, dans lequel KSPIN_MEDIUM représente des connexions uniques entre les tuners, les barres croisées et d’autres composants de tuner.

Le membre Flags peut contenir des valeurs différentes en fonction du type de dégradation du signal que le client utilise. Consultez Gestion de la qualité. pour plus d’informations sur les différentes stratégies de résolution des problèmes de gestion de la qualité en réduisant la qualité des signaux.

Étant donné que Flags contient une valeur ULONG, plusieurs demandes Skip peuvent être nécessaires pour résoudre le problème de gestion de la qualité.

Configuration requise

Condition requise	Valeur
En-tête	ks.h (inclure Ks.h)

Voir aussi

KSDEGRADE

KSEVENT

KSMETHOD

KSPIN_INTERFACE

KSPIN_MEDIUM

KSPROPERTY