Estrutura KSPROPERTY

Artigo
06/15/2023

A estrutura KSPROPERTY especifica uma única propriedade de streaming de kernel dentro de um conjunto de propriedades.

As estruturas KSEVENT, KSMETHOD e KSPROPERTY são aliases para a estrutura KSIDENTIFIER . Dessa forma, suas definições são idênticas.

Sintaxe

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

Membros

Set

Especifica um GUID que identifica um conjunto de propriedades de streaming de kernel. Para obter mais informações sobre GUIDs de conjunto de propriedades, consulte a seção Comentários abaixo.

Id

Especifica o membro do conjunto de propriedades.

Flags

Especifica o tipo de solicitação. Se você estiver escrevendo um minidriver de classe de fluxo, consulte também KSPROPERTY_ITEM para obter informações de sinalizador específicas da classe.

Os sinalizadores devem ser um dos valores listados na tabela a seguir. Alguns dos sinalizadores podem ser combinados usando uma operação OR bit a bit.

Valor	Descrição
KSPROPERTY_TYPE_GET	Recupera o valor do item de propriedade especificado.
KSPROPERTY_TYPE_SET	Define o valor do item de propriedade especificado.
KSPROPERTY_TYPE_SETSUPPORT	Consulta se o driver dá suporte a esse conjunto de propriedades.
KSPROPERTY_TYPE_BASICSUPPORT	Consulta os tipos de solicitação que o driver manipula para esse item de propriedade. Retorna KSPROPERTY_TYPE_GET ou KSPROPERTY_TYPE_SET ou ambos. Todos os conjuntos de propriedades devem dar suporte a esse sinalizador.
KSPROPERTY_TYPE_DEFAULTVALUES	Consulta os valores padrão para o item de propriedade especificado. Retorna uma estrutura do tipo KSPROPERTY_VALUES.
KSPROPERTY_TYPE_RELATIONS	Consulta todas as propriedades com dependências na configuração atual dessa propriedade. Especifica que a lista de relações de propriedade deve ser retornada ou a quantidade de sala de buffer exigida por essa lista se o buffer de retorno for do tamanho de um ULONG. Cada elemento está em FILE_QUAD_ALIGNMENT, precedido por uma estrutura KSMULTIPLE_ITEM . Isso não é válido ao consultar o suporte da propriedade definida em geral. Todos os conjuntos de propriedades devem dar suporte a esse sinalizador.
KSPROPERTY_TYPE_SERIALIZESET	Serialize o conjunto de propriedades usando as estruturas de KSPROPERTY_SERIALHDR padrão e KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_UNSERIALIZESET	Deserialize o conjunto de propriedades usando as estruturas de KSPROPERTY_SERIALHDR padrão e KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_SERIALIZESIZE	Retorna um ULONG especificando o tamanho dos dados da propriedade quando serializado como parte de uma solicitação de KSPROPERTY_TYPE_SERIALIZESET . Um tamanho de zero indica que uma propriedade não precisa ser serializada.
KSPROPERTY_TYPE_SERIALIZERAW	Especifica que as propriedades nesse conjunto devem ser serializadas pelo manipulador de suporte do conjunto de propriedades, se houver. Caso contrário, a chamada falhará. O formato de serialização é privado. Essa operação deve ser o inverso de KSPROPERTY_TYPE_UNSERIALIZERAW.
KSPROPERTY_TYPE_TOPOLOGY	A propriedade passada é do tipo KSP_NODE, em que NodeId indica a ID numérica do nó de topologia. Não defina esse sinalizador por conta própria; em vez disso, OU com outros sinalizadores nesta tabela.
KSPROPERTY_TYPE_UNSERIALIZERAW	Especifica que o buffer fornecido contém um grupo de propriedades que pertencem a esse conjunto que devem ser nãoializadas pelo manipulador de suporte do conjunto de propriedades, se houver. Caso contrário, a chamada falhará. O formato de serialização é privado. Essa operação deve ser o inverso de KSPROPERTY_TYPE_SERIALIZERAW.

Comentários

O tamanho do buffer de saída passado determina quais dados são retornados de uma solicitação de KSPROPERTY_TYPE_BASICSUPPORT. Se o buffer de saída for do tamanho de um ULONG, somente os sinalizadores de acesso serão retornados. Se o buffer de saída for o tamanho da estrutura KSPROPERTY_DESCRIPTION , a estrutura será preenchida com os sinalizadores de acesso, o tamanho inclusivo das informações de valores inteiros, as informações de tipo de valor da propriedade e o número de listas de membros que correspondem à estrutura.

Para uma solicitação de KSPROPERTY_TYPE_RELATIONS, os dados retornados também dependem do tamanho do buffer de saída. Se o tamanho do buffer de saída for zero, o tamanho necessário para retornar as propriedades relacionadas será retornado em BytesReturned com um aviso status de STATUS_BUFFER_OVERFLOW. Se o buffer for do tamanho de uma estrutura KSMULTIPLE_ITEM , o tamanho do byte e a contagem de relações serão retornados. Caso contrário, espera-se que o buffer seja longo o suficiente para retornar a estrutura KSMULTIPLE_ITEM e todos os identificadores de propriedade relacionados, que é retornado como uma lista de estruturas KSIDENTIFIER .

KSPROPERTY_TYPE_SERIALIZESET e solicitações de KSPROPERTY_TYPE_UNSERIALIZESET permitem a interação com várias propriedades com uma única chamada do cliente. Se o manipulador de streaming de kernel estiver sendo usado para processar solicitações de propriedade, elas serão divididas em várias chamadas pela função KsPropertyHandler . Ao usar esse manipulador, a definição do conjunto de propriedades controla quais propriedades devem ser serializadas.

Para solicitações de serialização, o membro SerializedSize da estrutura de KSPROPERTY_ITEM relevante é verificado quanto a um valor diferente de zero que indica o tamanho, em bytes, da propriedade . Se o valor do membro SerializedSize for 1, ele será desconhecido e deverá ser consultado (todas as propriedades desconhecidas começam com uma estrutura KSMULTIPLE_ITEM que pode ser consultada separadamente). Para consultar o tamanho total que uma serialização levaria, o cliente passa um buffer de comprimento zero na chamada para DeviceIoControl. BytesReturned retorna o tamanho, em bytes, que o buffer deve ser para serializar o conjunto e um aviso status de STATUS_BUFFER_OVERFLOW. Um buffer alocado com esse tamanho pode ser preenchido com os dados serializados.

O formato do buffer de serialização é um KSPROPERTY_SERIALHDR, seguido por propriedades serializadas. Cada propriedade a seguir contém um cabeçalho (KSPROPERTY_SERIAL), seguido pelos dados da propriedade, com o início de cada propriedade em FILE_LONG_ALIGNMENT. Observe que a estrutura do cabeçalho serial é definida como em FILE_LONG_ALIGNMENT.

KSPROPERTY_TYPE_SERIALIZERAW e KSPROPERTY_TYPE_UNSERIALIZERAW têm suporte se houver um manipulador de item de propriedade. A função KsPropertyHandler invoca o manipulador fornecido pelo minidriver. O tamanho do buffer necessário para serialização também pode ser consultado passando um buffer de comprimento zero para uma solicitação bruta de serialização. Como os manipuladores são anexados a itens de propriedade em vez do conjunto de propriedades, um item específico dentro do conjunto de propriedades deve ser especificado no parâmetro Property . Esse manipulador pode lidar com várias propriedades dentro do conjunto.

A Microsoft fornece vários GUIDs de conjunto de propriedades definidos pelo sistema. Os minidrivers especificam um desses GUIDs no membro Set . Os conjuntos de propriedades de streaming de kernel normalmente começam com um KSPROPSETID ou um prefixo PROPSETID . Os conjuntos de propriedades de streaming de kernel são definidos em ks.h, ksmedia.h, bdamedia.h e possivelmente em outros arquivos de cabeçalho.

Para obter mais informações sobre eventos de streaming de kernel, consulte Propriedades, eventos e métodos do KS.