IMiniportDMus::NewStream method

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

Syntax


NTSTATUS NewStream(
  [out]           PMXF *ppMXF,
  [in, optional]  PUNKNOWN pOuterUnknown,
  [in]            POOL_TYPE PoolType,
  [in]            ULONG uPinId,
  [in]            DMUS_STREAM_TYPE StreamType,
  [in]            PKSDATAFORMAT pDataFormat ,
  [out]           PSERVICEGROUP *ppServiceGroup ,
  [in]            PAllocatorMXF pAllocatorMXF,
  [in]            PMASTERCLOCK pMasterClock,
  [out]           PULONGLONG puuSchedulePreFetch
);

Parameters

ppMXF [out]

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 IMXF interface.

pOuterUnknown [in, optional]

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.

PoolType [in]

Specifies the type of memory pool from which the storage for the DMA-channel object should be allocated. This parameter is set to one of the POOL_TYPE enumeration values.

uPinId [in]

Specifies the pin ID. This parameter identifies the pin that is to be opened. If the DMus miniport driver's IMiniport::GetDescription method outputs a filter descriptor that specifies a total of n pin factories on the filter, then valid pin IDs are in the range 0 to n-1.

StreamType [in]

Specifies the type of data stream to create. This parameter is set to one of the following DMUS_STREAM_TYPE enumeration values:

DMUS_STREAM_MIDI_RENDER

Specifies a MIDI output (playback) stream.

DMUS_STREAM_MIDI_CAPTURE

Specifies a MIDI input stream.

DMUS_STREAM_WAVE_SINK

Specifies a wave output stream.

For more information, see the following Remarks section.

pDataFormat [in]

Pointer to a kernel streaming KSDATAFORMAT structure specifying the data format to use for this instance

ppServiceGroup [out]

Output pointer for 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.

pAllocatorMXF [in]

Pointer to an IAllocatorMXF object. This is the port driver's memory allocator, which is needed to recycle DMUS_KERNEL_EVENT structures.

pMasterClock [in]

Pointer to an IMasterClock object. This master clock passes a wrapper for the KS clock to the miniport driver. The master-clock pointer is required to sync to reference time.

puuSchedulePreFetch [out]

Output pointer for the schedule-prefetch time. This parameter is a pointer to a caller-allocated ULONGLONG variable into which the method writes a time value that specifies how far ahead to query for events. The time is specified in 100-nanosecond units. The port driver is responsible for sequencing any events that exceed the amount of time that the miniport driver specifies here.

Return value

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

Remarks

Note that the port driver creates the IAllocatorMXF object that the NewStream method inputs through the pAllocatorMXF parameter, but the miniport driver creates the IMXF object that the method outputs through the ppMXF parameter. For more information about IMXF and IAllocatorMXF, see MIDI Transport.

The meaning of the IMiniportDMus::NewStream method's StreamType parameter is similar to that of the IMiniportMidi::NewStream method's Capture parameter:

  • When creating a stream on a MIDI pin, the IMiniportMidi::NewStream method's Capture parameter indicates whether the pin is to serve as the sink for a MIDI render stream (Capture = FALSE) or as the source of a MIDI capture stream (Capture = TRUE).

  • Similarly, when creating a stream on a MIDI or DirectMusic pin, the IMiniportDMus::NewStream method's StreamType parameter can indicate whether the pin is to serve as the sink for a MIDI render stream (StreamType = DMUS_STREAM_MIDI_RENDER) or as the source of a MIDI capture stream (StreamType = DMUS_STREAM_MIDI_CAPTURE).

However, a pin on a DirectMusic filter can support a third option that is not available with a MIDI filter. A pin can serve as the source of a wave output stream (StreamType = DMUS_STREAM_WAVE_SINK). The DMus port driver implements the wave sink for this stream. After creating the wave output stream, the DMus port driver queries the stream object (which the port driver obtains through the IMiniportDMus::NewStream method's ppMXF output parameter) for its ISynthSinkDMus interface. The port driver's wave sink calls the Render method on this interface to pull wave data from the software synthesizer. For more information, see A Wave Sink for Kernel-Mode Software Synthesizers.

The ppMXF, pOuterUnknown, ppServiceGroup, pAllocatorMXF, and pMasterClock parameters follow the reference-counting conventions for COM objects.

Requirements

Header

Dmusicks.h (include Dmusicks.h)

IRQL

PASSIVE_LEVEL

See also

IMXF
POOL_TYPE
IMiniport::GetDescription
KSDATAFORMAT
IServiceGroup
IAllocatorMXF
DMUS_KERNEL_EVENT
IMasterClock
IMiniportMidi::NewStream
ISynthSinkDMus

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.