estrutura PCPIN_DESCRIPTOR (portcls.h)

Artigo
02/07/2025

A estrutura PCPIN_DESCRIPTOR descreve uma fábrica de pinos.

Sintaxe

typedef struct {
  ULONG                    MaxGlobalInstanceCount;
  ULONG                    MaxFilterInstanceCount;
  ULONG                    MinFilterInstanceCount;
  const PCAUTOMATION_TABLE *AutomationTable;
  KSPIN_DESCRIPTOR         KsPinDescriptor;
} PCPIN_DESCRIPTOR, *PPCPIN_DESCRIPTOR;

Membros

MaxGlobalInstanceCount

Especifica o número máximo global de vezes que esse tipo de pino pode ser instanciado. O máximo global conta o número de instâncias de pino que o driver do adaptador pode dar suporte em todas as instâncias do filtro. A contagem pode ser definida como zero para indicar que o pino não pode ser instanciado. Um valor ULONG(-1) indica que o pino pode ser instanciado várias vezes. Qualquer outro valor indica um número específico de vezes que o pino pode ser instanciado.

MaxFilterInstanceCount

Especifica o número máximo de vezes que o pino pode ser instanciado em uma única instância do filtro. A contagem pode ser definida como zero para indicar que o pino não pode ser instanciado. Um valor ULONG(-1) indica que o pino pode ser instanciado várias vezes. Qualquer outro valor indica um número específico de vezes que o pino pode ser instanciado.

MinFilterInstanceCount

Especifica o número mínimo de vezes que o pino precisa ser instanciado em uma instância do filtro. Esse membro é um limite inferior definido no número de instâncias de um pino que deve existir para que um filtro possa funcionar.

AutomationTable

Ponteiro para a tabela de automação. Esse membro é um ponteiro para uma estrutura do tipo PCAUTOMATION_TABLE. O ponteiro pode ser NULL para indicar que nenhuma automação tem suporte. A tabela de automação especifica os manipuladores para as propriedades e eventos que pertencem à instância de pin.

KsPinDescriptor

Descreve a fábrica de pinos. Esse membro é uma estrutura do tipo KSPIN_DESCRIPTOR. Uma fábrica de pinos pode ter zero interfaces e zero meios. A lista de interfaces é ignorada em todos os casos. A lista de médio padrão usará como padrão uma lista que contém apenas E/S do dispositivo (KSMEDIUM_STANDARD_DEVIO).

Observações

Essa estrutura é usada para descrever cada uma das fábricas de pinos que um driver de miniporto implementa. A estrutura de PCFILTER_DESCRIPTOR do driver contém um ponteiro para uma matriz de estruturas de PCPIN_DESCRIPTOR. O número de elementos na matriz é igual ao número de fábricas de pinos no filtro.

Os membros MaxGlobalInstanceCount, MaxFilterInstanceCounte MinFilterInstanceCount são contagens máximas e mínimas que descrevem as restrições de recursos do pin e os requisitos funcionais. Uma matriz de PCPIN_DESCRIPTOR inicializada automaticamente pode apresentar apenas uma estimativa estática dos recursos de pino disponíveis. O método IPinCount::P inCount fornece um meio para o driver revisar sua lista de recursos de pino disponíveis dinamicamente à medida que os pinos são alocados e liberados.

O valor MaxGlobalInstanceCount é semelhante ao significado de:

O parâmetro de chamada GlobalPossible do método PinCount.
O valor da propriedade KSPROPERTY_PIN_GLOBALCINSTANCES (membro PossibleCount da estrutura KSPIN_CINSTANCES).

O valor MaxFilterInstanceCount é semelhante ao significado de:

O parâmetro de chamada filterPossible do método PinCount.
O valor da propriedade KSPROPERTY_PIN_CINSTANCES (membro PossibleCount da estrutura KSPIN_CINSTANCES).

O valor MinFilterInstanceCount é semelhante ao significado de:

O parâmetro de chamada FilterNecessarydo método PinCount.
O valor da propriedade KSPROPERTY_PIN_NECESSARYINSTANCES.

Ao descrever um pino de ponte (consulte gráficos de filtro de áudio), defina MaxGlobalInstanceCount, MaxFilterInstanceCounte MinFilterInstanceCount como zero e defina AutomationTable para NULL.

Para obter um exemplo de código simples que mostra como a estrutura de PCPIN_DESCRIPTOR é usada, consulte Expondo a topologia de filtro.

Para obter mais informações, consulte Pin Factories.