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 dans ce jeu.

LesKSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMet 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 les remarques ci-dessous.

_IDENTIFIER.Set

Consultez les remarques ci-dessous.

_IDENTIFIER.Id

Consultez les remarques ci-dessous.

_IDENTIFIER.Flags

Consultez les remarques ci-dessous.

Set

Consultez les remarques ci-dessous.

Id

Consultez les remarques ci-dessous.

Flags

Consultez les remarques ci-dessous.

Alignment

Consultez les remarques 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’interfaces. 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 set. 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’interfaces. Pour KSDEGRADE, spécifie l’identificateur spécifique à l’ensemble pour un élément.

Flags

Spécifie le type de requête. Si vous écrivez un minidriver de classe de flux, consultez également KSPROPERTY_ITEM pour obtenir des informations d’indicateur spécifiques à la classe. indicateurs doit ê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.

Consultez lesKSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMet rubriques de typedef KSPROPERTY pour des informations spécifiques sur l’utilisation.

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	Interroge si le pilote prend en charge ce jeu de propriétés.
KSPROPERTY_TYPE_BASICSUPPORT	Interroge les types de requêtes gérés par le pilote 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és doit être retournée ou la quantité de salle de mémoire tampon requise par cette liste si la mémoire tampon de retour est la taille d’un ULONG. Chaque élément se trouve 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 de la propriété définie 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 standard KSPROPERTY_SERIALHDR et KSPROPERTY_SERIAL.
KSPROPERTY_TYPE_UNSERIALIZESET	Annulez l’ensemble de propriétés à l’aide des structures standard KSPROPERTY_SERIALHDR et KSPROPERTY_SERIAL.
KSPROPERTY_TYPE_SERIALIZESIZE	Retourne une taille 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 cet ensemble 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 par lui-même ; au lieu de cela, OU avec d’autres indicateurs dans ce tableau.
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 nonialisé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 le 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 d’avertir le client, le pilote met en file d’attente les notifications d’événements. Le client émet ensuite une deuxième demande de IOCTL_KS_ENABLE_EVENT avec l’KSEVENT_TYPE_QUERYBUFFER pour recevoir les notifications d’événement 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 par lui-même ; au lieu de cela, OU avec d’autres indicateurs de cette liste.
KSEVENT_TYPE_QUERYBUFFER	Récupère la notification d’événement mise 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 requête 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 à la fois ou non. 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 le jeu 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 par lui-même ; au lieu de cela, OU avec d’autres indicateurs de cette liste.

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

Alignment

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

Notes

Consultez lesKSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMet rubriques de typedef KSPROPERTY pour des informations spécifiques sur l’utilisation.

L’utilisation d’un ID dans l’ensemble permet d’effectuer une comparaison large unique pour un identificateur de jeu, puis des comparaisons rapides plus petites (par exemple, à l’aide d’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.

méthode, Event, Interfaceet jeux moyens peuvent être considérés comme des « classes » de jeux.

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 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 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 octetsRe tourné avec un état d’avertissement de STATUS_BUFFER_OVERFLOW. Si la mémoire tampon est la taille d’une structure KSMULTIPLE_ITEM, la taille d’octet et le nombre de relations sont retournées. Dans le cas contraire, la mémoire tampon devrait ê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 requêtes 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és, ceux-ci sont divisés en plusieurs appels par la fonction KsPropertyHandler. Lorsque vous utilisez 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, la SerializedSize membre de la structure KSPROPERTY_ITEM appropriée est vérifiée 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 rechercher la taille totale qu’une sérialisation prend, le client transmet 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 le jeu et un état d’avertissement 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 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 gérer plusieurs propriétés au sein de l’ensemble.

Microsoft fournit plusieurs GUID définis par le système. Les minidrivers spécifient l’une de ces GUID dans le membre Définir. Les ensembles de propriétés de diffusion en continu du noyau commencent généralement par un KSPROPSETID ou un préfixe 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 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’une de ces GUID dans le membre Définir. 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 streaming 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éfinis par le système. Les minidrivers spécifient l’une de ces GUID dans le membre Définir. 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 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 du noyau géré par le minidriver. Pour plus d’informations, consultez méthodes KS.

La structure KSPIN_MEDIUM identifie un support, avec un GUID moyen unique et un identificateur d’instance, générés de manière spécifique au bus. Il existe une valeur d’identificateur réservée KSMEDIUM_TYPE_ANYINSTANCE 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 en avoir qu’un. Ainsi, cet identificateur d’instance est toujours utilisé comme commodité.

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 dans lequel 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.

Les indicateurs membre peuvent contenir des valeurs différentes en fonction du type de dégradation du signal utilisé par le client. 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 indicateurs contient une valeur ULONG, plusieurs demandes Skip peuvent être nécessaires pour résoudre le problème de gestion de la qualité.

Exigences

Exigence	Valeur
d’en-tête	ks.h (include Ks.h)

Voir aussi

KSDEGRADE

KSEVENT

KSMETHOD

KSPIN_INTERFACE

KSPIN_MEDIUM

KSPROPERTY