IMiniportWavePci::NewStream method (portcls.h)

Article
10/21/2021

The NewStream method creates a new instance of a logical stream associated with a specified physical channel.

Syntax

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

Parameters

[out] Stream

Output pointer for the new stream. This parameter points to a caller-allocated pointer variable into which the method writes a pointer to the stream object's IMiniportWavePciStream interface. The caller specifies a valid, non-NULL pointer for this parameter.

[in, optional] OuterUnknown

Pointer to the IUnknown interface of an object that needs to aggregate the stream object. This parameter is optional. If aggregation is not required, the caller specifies this parameter as NULL.

[in] PoolType

Specifies the type of memory pool from which the storage for the DMA-channel object should be allocated. This parameter will be one of the nonpaged pool types defined in the POOL_TYPE enumeration.

[in] PortStream

Pointer to the IPortWavePciStream interface of the port driver's stream object.

[in] Pin

Specifies a pin ID identifying the pin that is to be opened. If the WavePci miniport driver's filter descriptor specifies a total of n pin factories on the filter, then valid values for parameter Pin are in the range 0 to n-1.

[in] Capture

Specifies whether to create a capture stream or a render stream. This parameter is TRUE for an capture (input) channel, and FALSE for an playback (output) channel.

[in] DataFormat

Pointer to a KSDATAFORMAT structure that specifies the stream's data format.

[out] DmaChannel

Output pointer for the DMA channel. This parameter points to a caller-allocated pointer variable into which the method writes a pointer to the stream's IDmaChannel object. The caller specifies a valid, non-NULL pointer for this parameter.

[out] ServiceGroup

Output pointer for the service group. This parameter points to a caller-allocated pointer variable into which the method writes a pointer to the IServiceGroup interface of the stream's service group object. This is the service group that is being registered for interrupt notification. The caller specifies a valid, non-NULL pointer for this parameter.

Return value

NewStream returns STATUS_SUCCESS if the call was successful. Otherwise, the method returns an appropriate error code.

Remarks

The NewStream method sets the initial state of the stream to KSSTATE_STOP and its initial position to zero. (See IMiniportWavePciStream::SetState and IMiniportWavePciStream::GetPosition.)

The DataFormat parameter, which specifies the data format of the stream, points to one of the following audio-specific, extended versions of the KSDATAFORMAT structure:

KSDATAFORMAT_WAVEFORMATEX

KSDATAFORMAT_DSOUND

If the miniport driver does not provide a service group pointer (that is, if the NewStream call outputs NULL through the ServiceGroup pointer), the port driver sets up its own periodic timer instead for processing stream position and clock events. The period for this timer is currently 20 milliseconds, but the period might change in future implementations.

The Stream, OuterUnknown, PortStream, and ServiceGroup parameters follow the reference-counting conventions for COM objects.

Note that NewStream does not follow the usual reference-counting conventions in its handling of the pointer that it outputs through the DmaChannel OUT parameter. When the port driver finishes using the references that it receives through the NewStream method's other OUT parameters, Stream and ServiceGroup, it releases them, as expected. In contrast, the port driver never uses the DmaChannel pointer that it receives from the NewStream call and it never calls Release on the DmaChannel object.

The ac97 sample audio driver in the Microsoft Windows Driver Kit (WDK) reflects this behavior. This sample's implementation of the IMiniportWavePci::NewStream method calls AddRef on the Stream and ServiceGroup references that it outputs but not the DmaChannel reference. This behavior is preserved for the sake of backward compatibility.

Note that the NewStream methods for the other port types (WaveCyclic, in particular) follow the usual reference-counting conventions for all their OUT parameters.

Requirements

Requirement	Value
Target Platform	Universal
Header	portcls.h (include Portcls.h)
IRQL	PASSIVE_LEVEL