Pinos KS

O minidriver fornece uma estrutura KSPIN_DESCRIPTOR para cada tipo de pino a ser instanciado. Uma estrutura de descritor de pino é conhecida como fábrica de pinos. Cada fábrica de pinos pode instanciar uma ou mais instâncias de fixação de um tipo específico. Uma fábrica de pinos contém várias matrizes que descrevem o tipo de pino que esse descritor instancia.

O minidriver especifica uma ou mais categorias de KS às quais os pinos criados por esse descritor pertencem ao membro Categories do KSPIN_DESCRIPTOR. O KS usa categorias para conectar instâncias de pino quando cria um grafo de filtro. A propriedade KSPROPERTY_TOPOLOGY_CATEGORIES consultas para a matriz de categorias funcionais compatíveis com um driver.

Um minidriver fornece um arquivo INF que registra um ou mais nomes de dispositivo de fixação. Na instalação, o sistema operacional carrega os nomes e as categorias correspondentes no registro do sistema. Em seguida, os clientes podem fazer chamadas de arquivo de criação com esses nomes de dispositivo para instanciar pinos.

Os clientes do modo de usuário chamam a função Win32 CreateFile com o nome do dispositivo. Por exemplo, "\\.\filters\audio\default renderer" pode ser um link para o dispositivo de áudio que foi configurado para saída padrão. Os clientes no modo kernel chamam ZwCreateFile do modo kernel. Depois que a rotina create-file retorna um identificador de arquivo, os clientes KS se comunicam com instâncias de fixação por meio de propriedades KS.

Nas estruturas do descritor de pino, o minidriver dispõe de matrizes de estruturas de KSPIN_INTERFACE e estruturas KSPIN_MEDIUM que especificam as interfaces e os meios compatíveis com essa fábrica de pinos. KSPIN_DESCRIPTOR também é onde o minidriver especifica os intervalos de dados válidos para pinos criados por essa fábrica. Ele faz isso fornecendo um ponteiro para uma matriz de estruturas KSDATARANGE . O minidriver também especifica as direções de fluxo de dados e comunicação para novos pinos criados por essa fábrica de pinos.

Um minidriver permite a descoberta em tempo de execução de fábricas de pinos dando suporte ao conjunto de propriedades KSPROPSETID_Pin .

Para criar uma conexão de pino, chame a rotina KsCreatePin . Nessa chamada, o minidriver passa um ponteiro para uma estrutura do tipo KSPIN_CONNECT que descreve a conexão solicitada. Quando um pin é criado, o filtro vê o novo pin como um objeto de arquivo subordinado ao objeto de arquivo para esse filtro.

O minidriver chama KsValidateConnectRequest com as estruturas de descritor fornecidas no IRP_MJ_CREATE resultante. Essa rotina valida essas estruturas e retorna um ponteiro para a estrutura de conexão e o objeto de arquivo raiz.

Os minidrivers usam os membros dataflow e communication de estruturas de KSPIN_DESCRIPTOR para definir as seguintes especificações de pino:

• Pino de origem IRP versus pino do coletor IRP

  Um pino de origem IRP emite IRPs; um pino de coletor IRP os recebe. Um cliente no modo de usuário envia solicitações de E/S diretamente para um pino de coletor IRP por meio do identificador de arquivo relevante. Os clientes usam KSPROPERTY_PIN_COMMUNICATION para marcar se os dados fluem para dentro ou para fora de um tipo de pino.

• Pin da fonte de dados versus pin do coletor de dados

  Um pin de fonte de dados é um pino de saída em um filtro; um pin do coletor de dados é um pino de entrada. A propriedade de ser uma fonte de dados ou coletor é independente de ser uma fonte ou coletor IRP. Por exemplo, o cliente pode conectar uma fonte de dados, pino de coletor IRP a um coletor de dados, pino de origem IRP. Os clientes usam KSPROPERTY_PIN_DATAFLOW para marcar se os dados fluem para dentro ou para fora de um tipo de pino.

Ao encerrar uma conexão, o identificador do pino de origem deve ser fechado antes que o objeto de arquivo subjacente seja destruído. Se o pino de origem depender dos recursos fornecidos pelo pino do coletor, será responsabilidade do pino do coletor notificar a origem quando a conexão for encerrada.

Um cliente interage com um pino de streaming de kernel chamando a rotina DeviceIoControl (descrita na documentação do SDK do Microsoft Windows) com IRP_MJ_DEVICE_CONTROL. O chamador identifica sua solicitação pelo código de controle de E/S que ele coloca em Parameters.DeviceIoControl.IoControlCode na estrutura de local da pilha de E/S.

Para dar suporte a solicitações, o minidriver fornece um ponteiro para uma estrutura KSDISPATCH_TABLE em uma chamada para KsAllocateObjectHeader.

As solicitações de gravação contêm um ponteiro para uma matriz de estruturas de KSSTREAM_HEADER que, por sua vez, contêm ponteiros para transmitir dados. As solicitações de leitura contêm um ponteiro para uma matriz de estruturas de cabeçalho vazias em que os dados de leitura devem ser retornados.