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

Artículo
08/07/2023

El NewStream método crea una nueva instancia de una secuencia lógica asociada a un canal físico especificado.

Sintaxis

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

Puntero de salida para la nueva secuencia. Este parámetro apunta a una variable de puntero asignada por el autor de la llamada en la que el método escribe un puntero a la interfaz IMiniportWavePciStream del objeto de secuencia. El autor de la llamada especifica un puntero válido que no es NULL para este parámetro.

[in, optional] OuterUnknown

Puntero a la interfaz IUnknown de un objeto que necesita agregar el objeto de secuencia. Este parámetro es opcional. Si no se requiere la agregación, el autor de la llamada especifica este parámetro como NULL.

[in] PoolType

Especifica el tipo de grupo de memoria desde el que se debe asignar el almacenamiento para el objeto de canal DMA. Este parámetro será uno de los tipos de grupo no paginados definidos en la enumeración POOL_TYPE .

[in] PortStream

Puntero a la interfaz IPortWavePciStream del objeto de secuencia del controlador de puerto.

[in] Pin

Especifica un identificador de patilla que identifica el pin que se va a abrir. Si el descriptor de filtro del controlador de miniport de WavePci especifica un total de n generadores de patillas en el filtro, los valores válidos para el pin del parámetro están en el intervalo de 0 a n-1.

[in] Capture

Especifica si se va a crear una secuencia de captura o una secuencia de representación. Este parámetro es TRUE para un canal de captura (entrada) y FALSE para un canal de reproducción (salida).

[in] DataFormat

Puntero a una estructura KSDATAFORMAT que especifica el formato de datos de la secuencia.

[out] DmaChannel

Puntero de salida para el canal DMA. Este parámetro apunta a una variable de puntero asignada por el autor de la llamada en la que el método escribe un puntero al objeto IDmaChannel de la secuencia. El autor de la llamada especifica un puntero válido que no es NULL para este parámetro.

[out] ServiceGroup

Puntero de salida para el grupo de servicios. Este parámetro apunta a una variable de puntero asignada por el autor de la llamada en la que el método escribe un puntero en la interfaz IServiceGroup del objeto de grupo de servicios de la secuencia. Este es el grupo de servicios que se está registrando para la notificación de interrupción. El autor de la llamada especifica un puntero válido que no es NULL para este parámetro.

Valor devuelto

NewStream devuelve STATUS_SUCCESS si la llamada se realizó correctamente. De lo contrario, el método devuelve un código de error adecuado.

Comentarios

El NewStream método establece el estado inicial de la secuencia en KSSTATE_STOP y su posición inicial en cero. (Consulte IMiniportWavePciStream::SetState e IMiniportWavePciStream::GetPosition).

El parámetro DataFormat , que especifica el formato de datos de la secuencia, apunta a una de las siguientes versiones extendidas específicas de audio de la estructura KSDATAFORMAT :

KSDATAFORMAT_WAVEFORMATEX

KSDATAFORMAT_DSOUND

Si el controlador de miniporte no proporciona un puntero de grupo de servicio (es decir, si la NewStream llamada genera NULL a través del puntero ServiceGroup ), el controlador de puerto configura su propio temporizador periódico en su lugar para procesar eventos de posición y reloj de flujo. El período de este temporizador es actualmente de 20 milisegundos, pero el período podría cambiar en implementaciones futuras.

Los parámetros Stream, OuterUnknown, PortStream y ServiceGroup siguen las convenciones de recuento de referencias para objetos COM.

Tenga en cuenta que NewStream no sigue las convenciones habituales de recuento de referencias en su control del puntero que genera a través del parámetro OUT de DmaChannel . Cuando el controlador de puerto termina de usar las referencias que recibe a través de los NewStream demás parámetros OUT del método, Stream y ServiceGroup, los libera, según lo previsto. En cambio, el controlador de puerto nunca usa el puntero DmaChannel que recibe de la NewStream llamada y nunca llama a Release en el objeto DmaChannel .

El controlador de audio de ejemplo ac97 del Kit de controladores de Microsoft Windows (WDK) refleja este comportamiento. La implementación de este ejemplo del IMiniportWavePci::NewStream método llama a AddRef en las referencias de Stream y ServiceGroup que genera, pero no la referencia de DmaChannel. Este comportamiento se conserva por motivos de compatibilidad con versiones anteriores.

Tenga en cuenta que los NewStream métodos para los otros tipos de puerto (WaveCíclico, en particular) siguen las convenciones habituales de recuento de referencias para todos sus parámetros OUT.