Pinos KS

O minidriver fornece uma estrutura KSPIN_DESCRIPTOR para cada tipo de pino a ser instanciado. Uma estrutura de descritor de pinos é conhecida como uma fábrica de pinos. Cada fábrica de pinos pode instanciar uma ou mais instâncias de pin 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 pinos quando cria um grafo de filtro. A propriedade KSPROPERTY_TOPOLOGY_CATEGORIES consulta a matriz de categorias funcionais que um driver suporta.

Um minidriver fornece um arquivo INF que registra um ou mais nomes de dispositivos de pinos. 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 criação de arquivo 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. Clientes no modo kernel chamam ZwCreateFile do modo kernel. Depois que a rotina de criação de arquivo retorna um identificador de arquivo, os clientes KS se comunicam com instâncias de pin por meio de propriedades KS.

Nas estruturas do descritor de pino, o minidriver dispõe de matrizes de estruturas 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 dados e o fluxo de 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 . Nesta chamada, o minidriver passa um ponteiro para uma estrutura do tipo KSPIN_CONNECT que descreve a conexão solicitada. Quando um pino é criado, o filtro vê o novo pino 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 KSPIN_DESCRIPTOR para definir as seguintes especificidades de pino:

• Pino de origem IRP versus pino de 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 verificar se os dados fluem para dentro ou para fora de um tipo de pino.

• Pino da fonte de dados versus pino do coletor de dados

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

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

Um cliente interage com um pino de fluxo do kernel chamando a rotina DeviceIoControl (descrita na documentação do Microsoft Windows SDK) 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 localização 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.