Estrutura KSIDENTIFIER (ks.h)
A estrutura KSIDENTIFIER especifica um GUID que identifica exclusivamente um conjunto relacionado de GUIDs e um valor de índice para se referir a um membro específico dentro desse conjunto.
Os typedefs KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM e KSPROPERTY são aliases para a estrutura KSIDENTIFIER . Dessa forma, suas definições são idênticas. Consulte os tópicos de typedef individuais para obter detalhes sobre o uso.
Sintaxe
typedef struct {
union {
struct {
GUID Set;
ULONG Id;
ULONG Flags;
} _IDENTIFIER;
struct {
GUID Set;
ULONG Id;
ULONG Flags;
};
LONGLONG Alignment;
};
} KSIDENTIFIER, *PKSIDENTIFIER;
Membros
_IDENTIFIER
Consulte os comentários abaixo.
_IDENTIFIER.Set
Consulte os comentários abaixo.
_IDENTIFIER.Id
Consulte os comentários abaixo.
_IDENTIFIER.Flags
Consulte os comentários abaixo.
Set
Consulte os comentários abaixo.
Id
Consulte os comentários abaixo.
Flags
Consulte os comentários abaixo.
Alignment
Consulte os comentários abaixo.
Comentários
Descrições de membro KSIDENTIFIER
Set
Especifica um GUID que identifica uma propriedade de streaming de kernel, evento, método, conjunto de barramento de comunicação. A estrutura KSPIN_INTERFACE descreve uma interface específica dentro de um conjunto de interfaces. A estrutura KSDEGRADE contém especificações de estratégias de degradação. Para obter mais informações, consulte a seção Comentários abaixo.
Id
Especifica o membro da propriedade, evento, conjunto de métodos. Por KSPIN_MEDIUM, identifica uma conexão exclusiva no barramento. Para KSPIN_INTERFACE, especifica o número de ID dessa interface específica dentro do conjunto de interfaces. Para KSDEGRADE, especifica o identificador específico do conjunto para um item dentro do conjunto.
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.
Consulte os tópicos de typedef KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM e KSPROPERTY para obter detalhes sobre o uso.
Especifica o tipo de solicitação KSPROPERTY .
| Valor do sinalizador KSPROPERTY | 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. |
Especifica o tipo de solicitação KSEVENT . Esse sinalizador deve ser um dos valores listados na tabela a seguir.
| Valor do sinalizador KSEVENT | Descrição |
|---|---|
| KSEVENT_TYPE_ENABLE | Habilita a notificação de evento para esse tipo de evento. O driver continua a notificação de eventos até que o cliente a desabilite explicitamente. |
| KSEVENT_TYPE_ONESHOT | Habilita a notificação de evento somente para a próxima ocorrência desse evento. O cliente não precisa (e não deve) desabilitar o evento depois que ele ocorreu. |
| KSEVENT_TYPE_SETSUPPORT | Consulta a lista de conjuntos de eventos ou para dar suporte a um conjunto de eventos específico. |
| KSEVENT_TYPE_BASICSUPPORT | Consulta o suporte a um tipo de evento específico. |
| KSEVENT_TYPE_ENABLEBUFFERED | Em vez de notificar o cliente, o driver enfileira as notificações de evento. Em seguida, o cliente emite uma segunda solicitação de IOCTL_KS_ENABLE_EVENT com o KSEVENT_TYPE_QUERYBUFFER para receber as notificações de evento enfileiradas. |
| KSEVENT_TYPE_TOPOLOGY | Indica que o evento passado é do tipo KSE_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 desta lista. |
| KSEVENT_TYPE_QUERYBUFFER | Recupera a próxima notificação de evento em buffer. |
Especifica o tipo de solicitação KSMETHOD . Além disso, consulte os sinalizadores de KSMETHOD_TYPE_Xxx para KSMETHOD_ITEM. Uma solicitação pode conter uma combinação dos valores listados na tabela a seguir.
| Valor do sinalizador KSMETHOD | Descrição |
|---|---|
| KSMETHOD_TYPE_BASICSUPPORT | Indica consultar o minidriver para determinar se ele dá suporte ao método especificado do conjunto de métodos. |
| KSMETHOD_TYPE_SEND | Indica que o minidriver deve executar o método especificado. O efeito do método nos parâmetros especificados deve ser conhecido pelo cliente, ou seja, se os parâmetros são lidos, gravados em, ambos ou nenhum deles. O minidriver usa a estrutura KSMETHOD_ITEM para especificar o efeito do método nos parâmetros. |
| KSMETHOD_TYPE_SETSUPPORT | Indica consultar o minidriver para determinar se ele dá suporte ao conjunto de métodos especificado. |
| KSMETHOD_TYPE_TOPOLOGY | Indica que o método especificado é do tipo KSM_NODE, em que o membro NodeId é o identificador do nó de topologia. Não defina esse sinalizador por conta própria; em vez disso, OU com outros sinalizadores desta lista. |
Para KSDEGRADE, especifica o percentual atual de degradação, expresso em partes por milhar (em que um valor de 1000 não representa degradação) ou especifica a quantidade de tempo em unidades nativas, conforme especificado pela interface.
Alignment
Não usado. Um membro de uma união sem nome usada para forçar o alinhamento adequado na estrutura sem nome.
Observações
Consulte os tópicos de typedef KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM e KSPROPERTY para obter detalhes sobre o uso.
O uso de uma ID dentro do conjunto permite que um execute uma única comparação grande para um identificador de conjunto e, em seguida, comparações rápidas menores (por exemplo, usando uma instrução switch para identificadores dentro de um conjunto). Por exemplo, um conjunto de propriedades é referenciado por um identificador GUID exclusivo e as propriedades dentro desse conjunto são referenciadas pela ID curta.
Método, Evento, Interface e conjuntos médios podem ser considerados como "classes" de conjuntos.
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 desse 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 de 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 do kernel normalmente começam com um KSPROPSETID ou um prefixo PROPSETID . Os conjuntos de propriedades de streaming do 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 propriedades de streaming de kernel, consulte Propriedades, eventos e métodos do KS.
A Microsoft fornece vários GUIDs de conjunto de eventos definidos pelo sistema. Os minidrivers especificam um desses GUIDs no membro Set . Os conjuntos de eventos de streaming de kernel normalmente começam com um prefixo KSEVENTSETID . Os conjuntos de eventos 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.
A Microsoft fornece vários GUIDs de conjunto de métodos definidos pelo sistema. Os minidrivers especificam um desses GUIDs no membro Set . Os conjuntos de métodos de streaming de kernel normalmente começam com um prefixo KSMETHODSETID . Os conjuntos de métodos 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 métodos de streaming de kernel, consulte Propriedades, eventos e métodos do KS.
Um cliente pode usar a solicitação IOCTL_KS_METHOD junto com a estrutura KSMETHOD para executar métodos em um objeto de streaming de kernel que o minidriver manipula. Para obter mais informações, consulte Métodos KS.
A estrutura KSPIN_MEDIUM identifica um meio, com um GUID médio exclusivo e um identificador de instância, que é gerado de maneira específica do barramento. Há um valor de identificador reservado KSMEDIUM_TYPE_ANYINSTANCE que é usado quando as instâncias de barramento não são preocupantes. Por exemplo, o KSMEDIUMSETID_Standard refere-se ao barramento do sistema, do qual deve haver apenas um. Portanto, esse identificador de instância sempre é usado como uma conveniência.
Um pin pode dar suporte a vários meios e interfaces nesses meios. A maneira como um pin é descrito implica que há suporte para a lista de interfaces em todos os meios enumerados para um pin. Se houver um caso em que isso não seja verdadeiro, outro pino poderá ser usado para descrever cada subconjunto de interfaces para os meios específicos.
O meio também é armazenado em cache pelo streaming de kernel para acelerar a pesquisa de uma possível conexão.
Um exemplo de uso dessa estrutura pode ser encontrado em um exemplo de sintonizador, no qual KSPIN_MEDIUM representa conexões exclusivas entre sintonizadores, barras cruzadas e outros componentes do sintonizador.
O membro Flags pode conter valores diferentes com base no tipo de degradação de sinal que o cliente emprega. Consulte Gerenciamento de Qualidade. para obter mais detalhes sobre diferentes estratégias para resolver problemas de gerenciamento de qualidade, reduzindo a qualidade do sinal.
Como Flags contém um valor ULONG, várias solicitações Skip podem ser necessárias para corrigir o problema de gerenciamento de qualidade.
Requisitos
| Requisito | Valor |
|---|---|
| Cabeçalho | ks.h (inclua Ks.h) |