estrutura KSPROPERTY_ITEM (ks.h)

Artigo
02/29/2024

Os drivers usam a estrutura KSPROPERTY_ITEM para descrever como dão suporte a uma propriedade em um conjunto de propriedades.

Sintaxe

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;

Membros

PropertyId

Especifica a ID da propriedade que está sendo descrita.

GetPropertyHandler

Ponteiro para um KStrGetPropertyHandler fornecido por minidriver. Se FOR NULL, a propriedade não poderá ser lida. Esse membro é usado apenas por drivers que usam as interfaces de classe AVStream ou Stream.

GetSupported

Defina como TRUE se essa propriedade der suporte a solicitações get, FALSE se não o fizer. (O driver de classe atende à solicitação por meio do SRB_GET_DEVICE_PROPERTY ou SRB_GET_STREAM_PROPERTY solicitações.) Esse membro é usado apenas por minidrivers em execução na classe de fluxo.

MinProperty

Especifica o comprimento mínimo do buffer para manter o identificador de propriedade. Deve ser pelo menos sizeof(KSPROPERTY).

MinData

Especifica o comprimento mínimo do buffer para manter os dados lidos ou gravados nessa propriedade.

SetPropertyHandler

Ponteiro para um KStrSetPropertyHandler fornecido por minidriver. Se FOR NULL, a propriedade não poderá ser definida. Esse membro é usado apenas por drivers que usam as interfaces de classe AVStream ou Stream.

SetSupported

Defina como TRUE se essa propriedade der suporte a solicitações definidas, FALSE se não o fizer. (O driver de classe atende à solicitação por meio do SRB_SET_DEVICE_PROPERTY ou SRB_SET_STREAM_PROPERTY solicitações.)

Values

Ponteiro para uma estrutura do tipo KSPROPERTY_VALUES. Especifica os valores aceitáveis e/ou padrão para a propriedade . Eles são os mesmos que os valores relatados por um driver em resposta a uma solicitação de IOCTL_KS_PROPERTY com os sinalizadores KSPROPERTY_TYPE_BASICSUPPORT e KSPROPERTY_TYPE_DEFAULTVALUES definidos.

RelationsCount

Especifica o número de entradas na matriz apontada pelo membro Relações .

Relations

Aponta para uma matriz de estruturas KSPROPERTY que representam propriedades relacionadas a esta. Duas propriedades serão consideradas relacionadas se a alteração de uma propriedade puder afetar o valor da outra propriedade. O membro Flags de cada entrada não é usado.

SupportHandler

Forneça esse membro somente se estiver implementando seu próprio formato para serialização bruta ou deserialização bruta. Consultas de suporte básico, consultas de intervalo e consultas de relações são tratadas automaticamente pelo AVStream, que retorna os valores relevantes de outros membros dessa estrutura KSPROPERTY_ITEM.

SerializedSize

Especifica o tamanho da propriedade quando serializada em uma solicitação de KSPROPERTY_TYPE_SERIALIZESET. Isso deverá ser zero se a propriedade não puder ser serializada. Consulte KSPROPERTY para obter mais informações.

Comentários

Stream minidrivers de classe usam KSPROPERTY_ITEM para descrever ao cliente como atender a solicitações de propriedade em cada propriedade dentro de um conjunto. A manipulação do conjunto de propriedades como um todo é especificada na estrutura KSPROPERTY_SET , que contém ponteiros para matrizes de estruturas KSPROPERTY_ITEM.

O driver da classe de fluxo manipula solicitações de propriedade em nome do minidriver. Quando o driver da classe de fluxo requer mais informações do minidriver, ele passa uma solicitação de SRB_XXX para uma das rotinas StrMiniReceiveXXXRequest do minidriver. O driver de classe de fluxo manipula os diferentes tipos de solicitação, conforme listado na tabela a seguir.

Valor dos sinalizadores de solicitação de propriedade	Resposta
KSPROPERTY_TYPE_GET	Se GetSupported for TRUE, o driver da classe de fluxo enviará uma solicitação de SRB_GET_DEVICE_PROPERTY ou SRB_GET_STREAM_PROPERTY para a rotina de minidriver StrMiniReceiveXXXRequest apropriada.
KSPROPERTY_TYPE_SET	Se SetSupported for TRUE, o driver de classe de fluxo enviará uma solicitação de SRB_SET_DEVICE_PROPERTY ou SRB_SET_STREAM_PROPERTY para a rotina de minidriver StrMiniReceiveXXXRequest apropriada.
KSPROPERTY_TYPE_BASICSUPPORT	O driver de classe de fluxo usa KSPROPERTY_ITEM para obter as informações necessárias para atender a essa solicitação. Por exemplo, para especificar o tipo de dados e os intervalos permitidos dos dados de propriedade, cada um deles usa o membro Values dessa estrutura.
KSPROPERTY_TYPE_SETSUPPORT	O driver de classe de fluxo conclui a solicitação de propriedade IRP como STATUS_SUCCESS somente se o driver fornecer uma entrada para o conjunto de propriedades dentro de sua estrutura KSPROPERTY_SET .
KSPROPERTY_TYPE_DEFAULTVALUES	O driver de classe de fluxo usa o membro Values dessa estrutura para determinar os valores padrão para os dados da propriedade.
KSPROPERTY_TYPE_RELATIONS	O driver de classe de fluxo usa o membro Relations para determinar quais propriedades estão relacionadas a essa propriedade.

Se o cliente especificar KSPROPERTY_TYPE_DEFAULTVALUES, o driver usará o buffer de dados para retornar uma descrição de seu tipo de valor, incluindo possivelmente seu intervalo permitido e o valor padrão. Esse sinalizador é semelhante ao resultado de KSPROPERTY_TYPE_BASICSUPPORT, exceto que todos os valores retornados são aqueles que foram marcados com KSPROPERTY_MEMBER_FLAG_DEFAULT no membro Flags da estrutura KSPROPERTY_MEMBERSHEADER.

Para obter mais informações, consulte Propriedades do KS.