Método IMiniportWavePci::NewStream (portcls.h)

Artigo
02/26/2024

O NewStream método cria uma nova instância de um fluxo lógico associado a um canal físico especificado.

Sintaxe

NTSTATUS NewStream(
  [out]          PMINIPORTWAVEPCISTREAM *Stream,
  [in, optional] PUNKNOWN               OuterUnknown,
  [in]           POOL_TYPE              PoolType,
  [in]           PPORTWAVEPCISTREAM     PortStream,
  [in]           ULONG                  Pin,
  [in]           BOOLEAN                Capture,
  [in]           PKSDATAFORMAT          DataFormat,
  [out]          PDMACHANNEL            *DmaChannel,
  [out]          PSERVICEGROUP          *ServiceGroup
);

Parâmetros

[out] Stream

Ponteiro de saída para o novo fluxo. Esse parâmetro aponta para uma variável de ponteiro alocada pelo chamador na qual o método grava um ponteiro na interface IMiniportWavePciStream do objeto de fluxo. O chamador especifica um ponteiro válido e não NULL para esse parâmetro.

[in, optional] OuterUnknown

Ponteiro para a interface IUnknown de um objeto que precisa agregar o objeto stream. Esse parâmetro é opcional. Se a agregação não for necessária, o chamador especificará esse parâmetro como NULL.

[in] PoolType

Especifica o tipo de pool de memória do qual o armazenamento do objeto de canal DMA deve ser alocado. Esse parâmetro será um dos tipos de pool nãopagados definidos na enumeração POOL_TYPE .

[in] PortStream

Ponteiro para a interface IPortWavePciStream do objeto de fluxo do driver de porta.

[in] Pin

Especifica uma ID de pin que identifica o pino a ser aberto. Se o descritor de filtro do driver de miniporto WavePci especificar um total de n fábricas de pinos no filtro, os valores válidos para o parâmetro Pin estarão no intervalo de 0 a n-1.

[in] Capture

Especifica se é necessário criar um fluxo de captura ou um fluxo de renderização. Esse parâmetro é TRUE para um canal de captura (entrada) e FALSE para um canal de reprodução (saída).

[in] DataFormat

Ponteiro para uma estrutura KSDATAFORMAT que especifica o formato de dados do fluxo.

[out] DmaChannel

Ponteiro de saída para o canal DMA. Esse parâmetro aponta para uma variável de ponteiro alocada pelo chamador na qual o método grava um ponteiro no objeto IDmaChannel do fluxo. O chamador especifica um ponteiro válido e não NULL para esse parâmetro.

[out] ServiceGroup

Ponteiro de saída para o grupo de serviços. Esse parâmetro aponta para uma variável de ponteiro alocada pelo chamador na qual o método grava um ponteiro para a interface IServiceGroup do objeto do grupo de serviços do fluxo. Esse é o grupo de serviços que está sendo registrado para notificação de interrupção. O chamador especifica um ponteiro válido e não NULL para esse parâmetro.

Retornar valor

NewStream retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Caso contrário, o método retorna um código de erro apropriado.

Comentários

O NewStream método define o estado inicial do fluxo como KSSTATE_STOP e sua posição inicial como zero. (Consulte IMiniportWavePciStream::SetState e IMiniportWavePciStream::GetPosition.)

O parâmetro DataFormat , que especifica o formato de dados do fluxo, aponta para uma das seguintes versões estendidas específicas de áudio da estrutura KSDATAFORMAT :

KSDATAFORMAT_WAVEFORMATEX

KSDATAFORMAT_DSOUND

Se o driver de miniporto não fornecer um ponteiro do grupo de serviços (ou seja, se a NewStream chamada gerar NULL por meio do ponteiro ServiceGroup ), o driver de porta configurará seu próprio temporizador periódico em vez de processar eventos de relógio e posição do fluxo. O período para esse temporizador atualmente é de 20 milissegundos, mas o período pode mudar em implementações futuras.

Os parâmetros Stream, OuterUnknown, PortStream e ServiceGroup seguem as convenções de contagem de referência para objetos COM.

Observe que NewStream não segue as convenções usuais de contagem de referência em sua manipulação do ponteiro que ele gera por meio do parâmetro DmaChannel OUT. Quando o driver de porta termina de usar as referências que recebe por meio dos NewStream outros parâmetros OUT do método, Stream e ServiceGroup, ele os libera, conforme o esperado. Por outro lado, o driver de porta nunca usa o ponteiro DmaChannel que recebe da NewStream chamada e nunca chama Release no objeto DmaChannel .

O driver de áudio de exemplo ac97 no WDK (Microsoft Windows Driver Kit) reflete esse comportamento. A implementação deste exemplo do IMiniportWavePci::NewStream método chama AddRef nas referências Stream e ServiceGroup que ele gera, mas não a referência DmaChannel. Esse comportamento é preservado para fins de compatibilidade com versões anteriores.

Observe que os NewStream métodos para os outros tipos de porta (WaveCyclic, em particular) seguem as convenções habituais de contagem de referência para todos os parâmetros OUT.