Structure KSPROPERTY

Article
06/15/2023

La structure KSPROPERTY spécifie une propriété de diffusion en continu de noyau unique dans un jeu de propriétés.

Les structures KSEVENT, KSMETHOD et KSPROPERTY sont des alias pour la structure KSIDENTIFIER . Par conséquent, leurs définitions sont identiques.

Syntaxe

struct KSPROPERTY {
  GUID Set;
  ULONG Id;
  ULONG Flags;
};

Membres

Set

Spécifie un GUID qui identifie un jeu de propriétés de diffusion en continu du noyau. Pour plus d’informations sur les GUID de jeu de propriétés, consultez la section Remarques ci-dessous.

Id

Spécifie le membre du jeu de propriétés.

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.

Valeur	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_SERIALHDR et KSPROPERTY_SERIAL 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.

Remarques

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 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 événements de diffusion en continu du noyau, consultez Propriétés, événements et méthodes KS.