structure KSPROPERTY_ITEM (ks.h)

Article
02/07/2025

Les pilotes utilisent la structure KSPROPERTY_ITEM pour décrire comment elles prennent en charge une propriété dans un jeu de propriétés.

Syntaxe

typedef struct {
  ULONG                   PropertyId;
  union {
    PFNKSHANDLER GetPropertyHandler;
    BOOLEAN      GetSupported;
  };
  ULONG                   MinProperty;
  ULONG                   MinData;
  union {
    PFNKSHANDLER SetPropertyHandler;
    BOOLEAN      SetSupported;
  };
  const KSPROPERTY_VALUES *Values;
  ULONG                   RelationsCount;
  const KSPROPERTY        *Relations;
  PFNKSHANDLER            SupportHandler;
  ULONG                   SerializedSize;
} KSPROPERTY_ITEM, *PKSPROPERTY_ITEM;

Membres

PropertyId

Spécifie l’ID de la propriété en cours de description.

GetPropertyHandler

Pointeur vers un minidriver fourni KStrGetPropertyHandler. Si NULL, la propriété ne peut pas être lue. Ce membre est utilisé uniquement par les pilotes qui utilisent les interfaces de classe AVStream ou Stream.

GetSupported

Défini sur TRUE si cette propriété prend en charge les requêtes get, FALSE si ce n’est pas le cas. (Le pilote de classe répond à la demande via les requêtes SRB_GET_DEVICE_PROPERTY ou SRB_GET_STREAM_PROPERTY.) Ce membre est utilisé uniquement par les minidrivers s’exécutant sous la classe de flux.

MinProperty

Spécifie la longueur minimale de la mémoire tampon pour contenir l’identificateur de propriété. Cela doit être au moins taille de(KSPROPERTY).

MinData

Spécifie la longueur minimale de la mémoire tampon pour contenir les données lues ou écrites dans cette propriété.

SetPropertyHandler

Pointeur vers un minidriver fourni KStrSetPropertyHandler. Si NULL, la propriété ne peut pas être définie. Ce membre est utilisé uniquement par les pilotes qui utilisent les interfaces de classe AVStream ou Stream.

SetSupported

Défini sur TRUE si cette propriété prend en charge les requêtes définies, FALSE si ce n’est pas le cas. (Le pilote de classe répond à la demande via les requêtes SRB_SET_DEVICE_PROPERTY ou SRB_SET_STREAM_PROPERTY.)

Values

Pointeur vers une structure de type KSPROPERTY_VALUES. Spécifie les valeurs acceptables et/ou par défaut de la propriété. Ces valeurs sont identiques aux valeurs signalées par un pilote en réponse à une demande de IOCTL_KS_PROPERTY avec les indicateurs de KSPROPERTY_TYPE_BASICSUPPORT et de KSPROPERTY_TYPE_DEFAULTVALUES définis.

RelationsCount

Spécifie le nombre d’entrées dans le tableau pointé par le membre Relations.

Relations

Pointe vers un tableau de structures KSPROPERTY représentant les propriétés associées à celle-ci. Deux propriétés sont considérées comme liées si la modification d’une propriété peut affecter la valeur de l’autre propriété. Les indicateurs membre de chaque entrée ne sont pas utilisés.

SupportHandler

Fournissez ce membre uniquement si vous implémentez votre propre format pour la sérialisation brute ou la nonsérialisation brute. Les requêtes de prise en charge de base, les requêtes de plage et les requêtes de relations sont gérées automatiquement par AVStream, qui retourne les valeurs pertinentes d’autres membres de cette structure KSPROPERTY_ITEM.

SerializedSize

Spécifie la taille de la propriété lorsqu’elle est sérialisée dans une requête KSPROPERTY_TYPE_SERIALIZESET. Cela doit être égal à zéro si la propriété ne peut pas être sérialisée. Pour plus d’informations, consultez KSPROPERTY.

Remarques

Les minidrivers de classe de flux utilisent KSPROPERTY_ITEM pour décrire au client comment répondre aux demandes de propriété sur chaque propriété dans un ensemble. La gestion du jeu de propriétés dans son ensemble est spécifiée dans la structure KSPROPERTY_SET, qui contient des pointeurs vers des tableaux de structures KSPROPERTY_ITEM.

Le pilote de classe de flux gère les demandes de propriété pour le compte du minidriver. Lorsque le pilote de classe de flux nécessite plus d’informations à partir du minidriver, il transmet une requête SRB_XXX à l’une des routines StrMiniReceiveXXXRequest. Le pilote de classe de flux gère les différents types de requêtes, comme indiqué dans le tableau suivant.

Valeur des indicateurs de demande de propriété	Réponse
KSPROPERTY_TYPE_GET	Si GetSupported est TRUE, le pilote de classe de flux envoie une requête SRB_GET_DEVICE_PROPERTY ou SRB_GET_STREAM_PROPERTY à la routine de minidriver appropriée StrMiniReceiveXXXRequest.
KSPROPERTY_TYPE_SET	Si SetSupported est TRUE, le pilote de classe de flux envoie une demande de SRB_SET_DEVICE_PROPERTY ou de SRB_SET_STREAM_PROPERTY à la routine de minidriver appropriée StrMiniReceiveXXXRequest routine.
KSPROPERTY_TYPE_BASICSUPPORT	Le pilote de classe de flux utilise KSPROPERTY_ITEM pour obtenir les informations nécessaires pour répondre à cette demande. Par exemple, pour spécifier le type de données et les plages autorisées des données de propriété, ils utilisent chacun le Values membre de cette structure.
KSPROPERTY_TYPE_SETSUPPORT	Le pilote de classe de flux termine l’IRP de requête de propriété comme STATUS_SUCCESS uniquement si le pilote fournit une entrée pour la propriété définie dans sa structure KSPROPERTY_SET.
KSPROPERTY_TYPE_DEFAULTVALUES	Le pilote de classe de flux utilise le Values membre de cette structure pour déterminer les valeurs par défaut pour les données de propriété.
KSPROPERTY_TYPE_RELATIONS	Le pilote de classe de flux utilise le membre Relations pour déterminer les propriétés associées à cette propriété.

Si le client spécifie KSPROPERTY_TYPE_DEFAULTVALUES, le pilote utilise la mémoire tampon de données pour retourner une description de son type valeur, y compris éventuellement sa plage autorisée et sa valeur par défaut. Cet indicateur est similaire à KSPROPERTY_TYPE_BASICSUPPORT, sauf que les valeurs retournées sont celles qui ont été marquées avec KSPROPERTY_MEMBER_FLAG_DEFAULT dans les indicateurs membre de la structure KSPROPERTY_MEMBERSHEADER.

Pour plus d’informations, consultez propriétés KS.