IMiniportWavePci：：NewStream 方法 (portcls.h)

项目
03/05/2024

方法 NewStream 创建与指定物理通道关联的逻辑流的新实例。

语法

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
);

参数

[out] Stream

新流的输出指针。此参数指向调用方分配的指针变量，该方法在其中写入指向流对象的 IMiniportWavePciStream 接口的指针。调用方为此参数指定有效的非 NULL 指针。

[in, optional] OuterUnknown

指向需要聚合流对象的对象的 IUnknown 接口的指针。此参数是可选的。如果不需要聚合，则调用方将此参数指定为 NULL。

[in] PoolType

指定应从中分配 DMA 通道对象的存储的内存池的类型。此参数将是 POOL_TYPE 枚举中定义的非分页池类型之一。

[in] PortStream

指向端口驱动程序的流对象的 IPortWavePciStream 接口的指针。

[in] Pin

指定标识要打开的引脚的引脚 ID。如果 WavePci 微型端口驱动程序的筛选器描述符指定筛选器上的总共 n 个引脚工厂，则参数 Pin 的有效值在 0 到 n-1 的范围内。

[in] Capture

指定是创建捕获流还是呈现流。对于捕获 (输入) 通道，此参数为 TRUE ，对于播放 (输出) 通道，此参数为 FALSE 。

[in] DataFormat

指向 KSDATAFORMAT 结构的指针，该结构指定流的数据格式。

[out] DmaChannel

DMA 通道的输出指针。此参数指向调用方分配的指针变量，该方法将指针写入到流的 IDmaChannel 对象。调用方为此参数指定有效的非 NULL 指针。

[out] ServiceGroup

服务组的输出指针。此参数指向调用方分配的指针变量，该方法在其中写入指向流的服务组对象的 IServiceGroup 接口的指针。这是正在为中断通知注册的服务组。调用方为此参数指定有效的非 NULL 指针。

返回值

NewStream 如果调用成功，则返回STATUS_SUCCESS。否则，该方法将返回相应的错误代码。

注解

方法 NewStream 将流的初始状态设置为KSSTATE_STOP，将其初始位置设置为零。 (请参阅 IMiniportWavePciStream：：SetState 和 IMiniportWavePciStream：：GetPosition.)

DataFormat 参数（指定流的数据格式）指向以下特定于音频的扩展版本的 KSDATAFORMAT 结构之一：

KSDATAFORMAT_WAVEFORMATEX

KSDATAFORMAT_DSOUND

如果微型端口驱动程序未提供服务组指针 (也就是说，如果NewStream调用通过 ServiceGroup 指针) 输出 NULL，端口驱动程序会设置自己的定期计时器来处理流位置和时钟事件。此计时器的时间段当前为 20 毫秒，但该时间段在将来的实现中可能会更改。

Stream、OuterUnknown、PortStream 和 ServiceGroup 参数遵循 COM 对象的引用计数约定。

请注意， NewStream 在处理通过 DmaChannel OUT 参数输出的指针时，不遵循通常的引用计数约定。当端口驱动程序使用完通过NewStream方法的其他 OUT 参数（Stream 和 ServiceGroup）接收的引用时，它会按预期释放它们。相比之下，端口驱动程序从不使用从NewStream调用接收的 DmaChannel 指针，也从不对 DmaChannel 对象调用 Release。

Microsoft Windows 驱动程序工具包 (WDK) 中的 ac97 示例音频驱动程序反映了此行为。此示例中方法的IMiniportWavePci::NewStream实现对 Stream 和 ServiceGroup 引用调用 AddRef，它输出的而不是 DmaChannel 引用。为了向后兼容，保留此行为。

请注意， NewStream 其他端口类型的方法 (WaveCyclic，特别是) 遵循其所有 OUT 参数的常用引用计数约定。