estrutura KSFILTER_DESCRIPTOR (ks.h)

Artigo
03/09/2023

A estrutura KSFILTER_DESCRIPTOR descreve as características de um filtro criado por uma determinada fábrica de filtros.

Sintaxe

typedef struct _KSFILTER_DESCRIPTOR {
  const KSFILTER_DISPATCH     *Dispatch;
  const KSAUTOMATION_TABLE    *AutomationTable;
  ULONG                       Version;
  ULONG                       Flags;
  const GUID                  *ReferenceGuid;
  ULONG                       PinDescriptorsCount;
  ULONG                       PinDescriptorSize;
  const KSPIN_DESCRIPTOR_EX   *PinDescriptors;
  ULONG                       CategoriesCount;
  const GUID                  *Categories;
  ULONG                       NodeDescriptorsCount;
  ULONG                       NodeDescriptorSize;
  const KSNODE_DESCRIPTOR     *NodeDescriptors;
  ULONG                       ConnectionsCount;
  const KSTOPOLOGY_CONNECTION *Connections;
  const KSCOMPONENTID         *ComponentId;
} KSFILTER_DESCRIPTOR, *PKSFILTER_DESCRIPTOR;

Membros

Dispatch

Um ponteiro para uma estrutura KSFILTER_DISPATCH para esse tipo de filtro. Esse membro é opcional e só precisa ser fornecido por clientes que desejam receber notificações sobre criações de filtro, exclusões e assim por diante. Os drivers interessados no processamento de dados (transformações) normalmente fornecem essa tabela de expedição e uma função de processamento. Fornecer uma função de processamento de filtro em vez de funções individuais de processamento de pinos é o que torna um driver centrado em filtro em vez de centrado em pin.

AutomationTable

Um ponteiro para uma estrutura KSAUTOMATION_TABLE para esse tipo de filtro. A tabela de automação é o que descreve as propriedades, os métodos e os eventos compatíveis com esse filtro. Essa tabela de automação é mesclada com a tabela de automação fornecida pelo AVStream para todos os filtros. Se o cliente fornecer uma propriedade, método ou manipulador de eventos já implementado pelo AVStream, a implementação do cliente substituirá a do AVStream.

Version

Esse membro especifica a versão do descritor de filtro. Esse membro deve ser definido como KSFILTER_DESCRIPTOR_VERSION.

Flags

Sinalizadores que descrevem o comportamento do filtro. Especifique sinalizadores usando um OR bit a bit, com exceção de KSFILTER_FLAG_CRITICAL_PROCESSING e KSFILTER_FLAG_HYPERCRITICAL_PROCESSING, que são mutuamente exclusivos:

Sinalizador	Descrição
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING	Indica que os processos de filtro no IRQL DISPATCH_LEVEL em vez de PASSIVE_LEVEL. Isso se aplica ao retorno de chamada do processo de filtro, conforme descrito em KSFILTER_DISPATCH.
KSFILTER_FLAG_CRITICAL_PROCESSING	Se o processamento assíncrono tiver sido especificado ou se o sistema estiver em execução em PASSIVE_LEVEL e uma chamada de processo chegar em DISPATCH_LEVEL, o processamento será feito em um item de trabalho enfileirado. Esse sinalizador indica que o item de trabalho deve ser colocado na fila de trabalho crítica em vez da fila de trabalho atrasada.
KSFILTER_FLAG_RECEIVE_ZERO_LENGTH_SAMPLES	Defina esse sinalizador se um filtro centrado em filtro precisar receber amostras de comprimento zero (cabeçalhos de fluxo com sinalizadores, mas sem dados). Se esse sinalizador não estiver definido, amostras de comprimento zero serão passadas para pinos downstream, com propagação automática de sinalizadores necessários. Observe que isso é idêntico ao comportamento padrão no DX8 e anterior. Se isso acontecer, esses exemplos ignorarão o minidriver. Defina o sinalizador Terminate no KSPROCESSPIN para "desativar" esse sinalizador. Consulte também Processamento centrado em filtro.
KSFILTER_FLAG_DENY_USERMODE_ACCESS	Esse sinalizador impede o acesso do modo de usuário a um filtro específico e todos os pinos instanciados nesse filtro.
KSFILTER_FLAG_HYPERCRITICAL_PROCESSING	Se o processamento assíncrono tiver sido especificado ou se o sistema estiver em execução em PASSIVE_LEVEL e uma chamada de processo chegar em DISPATCH_LEVEL, o AVStream processará um item de trabalho enfileirado. Esse sinalizador indica que o item de trabalho deve ser colocado na fila de trabalho hipercrítica em vez da fila de trabalho atrasada ou da fila de trabalho crítica.

ReferenceGuid

Um ponteiro para um GUID que é a representação binária da cadeia de caracteres de referência Unicode que identifica esse tipo de filtro. Se existirem várias fábricas de filtros, cada uma deverá ter um GUID exclusivo. Observe também que outros métodos de fornecimento de uma cadeia de caracteres de referência exigem que o descritor de filtro seja registrado usando KsCreateFilterFactory. O valor especificado em ReferenceGuid deve corresponder ao GUID de referência específico do filtro no arquivo INF do driver. Consulte Inicializando um minidriver AVStream.

PinDescriptorsCount

Esse membro especifica o número de descritores de pin fornecidos para esse tipo de filtro no membro PinDescriptors . No Windows XP e posterior, PinDescriptorsCount poderá ser zero se o driver criar pinos dinamicamente.

PinDescriptorSize

Esse membro especifica o tamanho de cada descritor individual na tabela do descritor. Esse valor deve ser um múltiplo de oito e deve ser pelo menos sizeof (KSPIN_DESCRIPTOR_EX). Valores maiores permitem que informações de descritor específicas do cliente sejam acrescentadas para fixar descritores. Consulte informações adicionais em Comentários.

PinDescriptors

Um ponteiro para uma matriz de estruturas de KSPIN_DESCRIPTOR_EX que descrevem os pinos compatíveis com esse tipo de filtro. Se PinDescriptorsCount for zero, defina esse membro como NULL..

CategoriesCount

Esse membro especifica o número de GUIDs de categoria fornecidos no membro Categorias para esse tipo de filtro. Zero é um valor legal para esse membro.

Categories

Um ponteiro para uma matriz de GUIDs de categoria para esse tipo de filtro. Se necessário, uma interface do dispositivo é registrada para cada categoria. Esse membro poderá ser nulo se e somente se CategoriesCount for zero.

NodeDescriptorsCount

Esse membro especifica o número de descritores de nó de topologia fornecidos em NodeDescriptors. Zero é um valor legal para esse membro.

NodeDescriptorSize

Esse membro especifica o tamanho em bytes de cada descritor individual na tabela do descritor. Esse valor deve ser um múltiplo de oito e pelo menos sizeof(KSNODE_DESCRIPTOR). Valores maiores permitem que informações de descritor específicas do cliente sejam acrescentadas a descritores de nó. Consulte informações adicionais em Comentários.

NodeDescriptors

Um ponteiro para uma matriz de estruturas de KSNODE_DESCRIPTOR que descrevem os nós de topologia para esse tipo de filtro. Esse membro poderá ser nulo se e somente se NodeDescriptorsCount for zero.

ConnectionsCount

Esse membro especifica o número de conexões de topologia presentes em Connections. Esse membro pode ser zero indicando que o conjunto de conexões padrão é usado. Usar conexões padrão significa que a topologia do filtro é descrita com um único nó de topologia em que cada pino no filtro está conectado à ID correspondente no nó de topologia. A direção de cada conexão é determinada pelo fluxo de dados de fixação.

Connections

Um ponteiro para uma matriz de estruturas de KSTOPOLOGY_CONNECTION presentes nesse tipo de filtro. Esse membro é opcional; ele poderá ser NULL se e somente se ConnectionsCount for zero (nesse caso, a topologia padrão será usada).

ComponentId

Um ponteiro para a estrutura KSCOMPONENTID para esse tipo de filtro. Isso é usado para a propriedade ID do componente que fornece informações de identificação. Esse membro é opcional.

Comentários

Ao definir o descritor de filtro, há várias macros que o chamador pode achar úteis. Em vez de especificar contagem, tamanho e uma tabela para descritores de pino, categorias, descritores de nó e conexões, há várias macros úteis:

Macro	Descrição
DEFINE_KSFILTER_PIN_DESCRIPTORS(Table)	Insere automaticamente o número de itens na tabela, o tamanho de cada item na tabela e a tabela de descritores de pin em si no descritor de filtro.
DEFINE_KSFILTER_CATEGORIES(Table)	Insere automaticamente o número de categorias na tabela e na própria tabela no descritor de filtro.
DEFINE_KSFILTER_CATEGORIES_NULL	Preenche automaticamente os membros da categoria para um filtro que não define nenhuma categoria.
DEFINE_KSFILTER_NODE_DESCRIPTORS(Table)	Insere automaticamente o número de itens na tabela, o tamanho de cada item na tabela e a tabela de descritores de nó em si no descritor de filtro.
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL	Preenche automaticamente os membros do descritor de nó para um filtro que não define nós de topologia.
DEFINE_KSFILTER_CONNECTIONS(Table)	Insere automaticamente o número de conexões na tabela e na própria tabela no descritor de filtro.
DEFINE_KSFILTER_DEFAULT_CONNECTIONS	Preenche automaticamente a tabela de conexões para um filtro que não define conexões explícitas.

Se você não usar DEFINE_KS_FILTER_PIN_DESCRIPTORS para definir PinDescriptorSize, deverá definir PinDescriptorSize como sizeof(KSPIN_DESCRIPTOR_EX).

Da mesma forma, se você não usar DEFINE_KS_FILTER_NODE_DESCRIPTORS para definir NodeDescriptorSize, deverá definir NodeDescriptorSize como sizeof(KSNODE_DESCRIPTOR).