estrutura KSPROPERTY_ITEM (ks.h)

Artigo
02/07/2025

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 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 verdadeiro se essa propriedade der suporte a solicitações de obtenção, FALSE se não o fizer. (O driver de classe atende à solicitação por meio das solicitações SRB_GET_DEVICE_PROPERTY ou SRB_GET_STREAM_PROPERTY.) Esse membro é usado somente por minidrivers em execução na classe stream.

MinProperty

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

MinData

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

SetPropertyHandler

Ponteiro para um KStrSetPropertyHandler fornecido pelo minidriver. Se 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 das solicitações SRB_SET_DEVICE_PROPERTY ou SRB_SET_STREAM_PROPERTY.)

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 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 deKSPROPERTYque 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 Flags membro de cada entrada não é usado.

SupportHandler

Forneça esse membro somente se estiver implementando seu próprio formato para serialização bruta ou inserção bruta. Consultas básicas de suporte, 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 deve ser zero se a propriedade não puder ser serializada. Consulte KSPROPERTY para obter mais informações.

Observações

Os minidrivers de classe de fluxo usam KSPROPERTY_ITEM para descrever ao cliente como atender 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 de KSPROPERTY_ITEM.

O driver de classe de fluxo manipula solicitações de propriedade em nome do minidriver. Quando o driver de classe de fluxo requer mais informações do minidriver, ele passa uma solicitação SRB_XXX para uma das rotinas de 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 verdadeiro, o driver de classe de fluxo enviará uma solicitação SRB_GET_DEVICE_PROPERTY ou SRB_GET_STREAM_PROPERTY para o minidriver apropriado rotina de StrMiniReceiveXXXRequest.
KSPROPERTY_TYPE_SET	Se setSupported for true, o driver de classe de fluxo enviará uma solicitação SRB_SET_DEVICE_PROPERTY ou SRB_SET_STREAM_PROPERTY para o minidriver apropriado rotina de StrMiniReceiveXXXRequest.
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 os valores membro 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 de KSPROPERTY_SET.
KSPROPERTY_TYPE_DEFAULTVALUES	O driver de classe de fluxo usa o Values membro 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 relações 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 Flags membro da estrutura KSPROPERTY_MEMBERSHEADER.

Para obter mais informações, consulte propriedades KS.