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 "fábrica de pinos". Cada fábrica de pinos pode instanciar uma ou mais instâncias de pinos 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 KS às quais os pinos criados por este descritor pertencem ao membro Categorias do KSPIN_DESCRIPTOR. O KS usa categorias para conectar instâncias de pinos quando cria um gráfico de filtro. A propriedade KSPROPERTY_TOPOLOGY_CATEGORIES consulta a matriz de categorias funcionais suportadas por um driver.

Um minidriver fornece um ficheiro INF que regista um ou mais nomes de dispositivos de pin. Na instalação, o sistema operacional carrega os nomes e as categorias correspondentes no registro do sistema. Os clientes podem então realizar chamadas create-file com estes nomes de dispositivos para instanciar pinos.

Clientes de 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 a saída padrão. Os clientes do 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 pino por meio das Propriedades do KS.

Nas estruturas do descritor de pinos, o minidriver define matrizes de estruturas KSPIN_INTERFACE e de estruturas KSPIN_MEDIUM que especificam as interfaces e meios suportados por 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 fluxo de comunicação para novos pinos criados por esta fábrica de pinos.

Um minidriver permite a descoberta em tempo de execução de fábricas de pinos, suportando o 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 usando as estruturas de descritor que foram 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 das estruturas KSPIN_DESCRIPTOR para definir os seguintes detalhes de pinos:

• Pino de origem IRP versus pino de coletor IRP

  Um pino de origem IRP emite IRPs; um pino de receção IRP recebe-os. Um cliente de modo de utilizador envia diretamente pedidos de Entrada/Saída para um pino de destino de IRP através do identificador de arquivo relevante. Os clientes usam KSPROPERTY_PIN_COMMUNICATION para verificar se os dados entram ou saem 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 do coletor de dados é um pino de entrada. A propriedade de ser uma fonte ou ponto de recepção de dados é independente de ser uma fonte ou ponto de recepção de IRP. Por exemplo, o cliente pode conectar uma fonte de dados, pino de coletor de IRP a um coletor de dados, pino de origem de IRP. Os clientes utilizam KSPROPERTY_PIN_DATAFLOW para verificar se os dados entram ou saem 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 de recursos fornecidos pelo pino de coletor, cabe ao pino de coletor notificar o pino de origem quando a conexão for encerrada.

Um cliente interage com um pino de streaming do kernel chamando a rotina DeviceIoControl (descrita na documentação do SDK do Microsoft Windows) com IRP_MJ_DEVICE_CONTROL. O chamador identifica a sua solicitação pelo código de controlo de E/S que 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 a 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 onde os dados lidos devem ser retornados.