structure KSPROPERTY_ITEM (ks.h)

Article
02/26/2024

Les pilotes utilisent la structure KSPROPERTY_ITEM pour décrire la façon dont ils 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é décrite.

GetPropertyHandler

Pointeur vers un KStrGetPropertyHandler fourni par mini-driver. Si la valeur est 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 demandes d’obtention, 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 mini-drivers s’exécutant sous la classe stream.

MinProperty

Spécifie la longueur minimale de la mémoire tampon pour contenir l’identificateur de propriété. Il doit s’agir d’au moins sizeof(KSPROPERTY).

MinData

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

SetPropertyHandler

Pointeur vers un KStrSetPropertyHandler fourni par mini-driver. Si la valeur est 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éfinissez sur TRUE si cette propriété prend en charge les demandes de jeu, false si ce n’est pas le cas. (Le pilote de classe répond à la demande par le biais des 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 pour 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 KSPROPERTY_TYPE_BASICSUPPORT et KSPROPERTY_TYPE_DEFAULTVALUES définis.

RelationsCount

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

Relations

Pointe vers un tableau de structures KSPROPERTY représentant des 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é. Le membre Flags de chaque entrée n’est pas utilisé.

SupportHandler

Fournissez ce membre uniquement si vous implémentez votre propre format pour la sérialisation brute ou la désé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é en cas de sérialisation dans une demande de KSPROPERTY_TYPE_SERIALIZESET. Cette valeur doit être égale à zéro si la propriété ne peut pas être sérialisée. Pour plus d’informations, consultez KSPROPERTY .

Remarques

Stream classe minidrivers utilisent KSPROPERTY_ITEM pour décrire au client comment répondre aux demandes de propriété sur chaque propriété au sein d’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és pour le compte du minidriver. Lorsque le pilote de classe de flux a besoin d’informations supplémentaires du minidriver, il transmet une requête SRB_XXX à l’une des routines StrMiniReceiveXXXRequest du minidriver. Le pilote de classe de flux gère les différents types de requête, comme indiqué dans le tableau suivant.

Valeur des indicateurs de demande de propriété	response
KSPROPERTY_TYPE_GET	Si GetSupported a la valeur TRUE, le pilote de classe de flux envoie une requête SRB_GET_DEVICE_PROPERTY ou SRB_GET_STREAM_PROPERTY à la routine strMiniReceiveXXXRequest du minidriver approprié.
KSPROPERTY_TYPE_SET	Si SetSupported a la valeur TRUE, le pilote de classe de flux envoie une requête SRB_SET_DEVICE_PROPERTY ou SRB_SET_STREAM_PROPERTY à la routine strMiniReceiveXXXRequest du minidriver approprié.
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 membre Values de cette structure.
KSPROPERTY_TYPE_SETSUPPORT	Le pilote de classe de flux effectue l’IRP de demande 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 membre Values de cette structure pour déterminer les valeurs par défaut des 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 renvoyer une description de son type de valeur, y compris éventuellement sa plage autorisée et sa valeur par défaut. Ce résultat est similaire à KSPROPERTY_TYPE_BASICSUPPORT, sauf que les valeurs retournées sont celles qui ont été marquées avec KSPROPERTY_MEMBER_FLAG_DEFAULT dans le membre Indicateurs de la structure KSPROPERTY_MEMBERSHEADER.

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