IMiniportWaveCyclicStream::GetPosition method (portcls.h)

Article
10/21/2021

The GetPosition method gets the current position of the stream.

Syntax

NTSTATUS GetPosition(
  [out] PULONG Position
);

Parameters

[out] Position

Output pointer for the position value. This parameter points to a caller-allocated variable into which the method writes the current byte position of the stream.

Return value

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

Remarks

GetPosition reports the stream's current play or record position. The position is expressed as a byte offset from the beginning of the DMA buffer and represents the miniport driver's best estimate of the byte position of the data currently in the DAC or ADC.

The position is zero immediately following initialization of the stream. A transition to the KSSTATE_STOP state (see KSSTATE) resets the position to zero. When the stream is halted by a transition from KSSTATE_RUN to KSSTATE_PAUSE or KSSTATE_ACQUIRE, the position freezes. It unfreezes when the stream transitions from KSSTATE_PAUSE or KSSTATE_ACQUIRE back to KSSTATE_RUN.

GetPosition specifies the position as an offset into the cyclic buffer. When the position reaches the end of the cyclic buffer, it wraps around to the beginning of the buffer. Hence, the position never exceeds the buffer size.

Note that the offset value retrieved by a GetPosition call is one of the following:

For a render stream, the GetPosition method retrieves the play position, which is the byte offset of the sample that is currently being played through the DAC and transmitted through the speaker jack.
For a capture stream, the GetPosition method retrieves the record position, which is the byte offset of the latest sample to be received through the microphone jack and captured by the ADC.

It is not the offset of the sample that the DMA engine in the audio device is currently reading from or writing to the audio buffer.

Some audio hardware contains a position register to keep track of the byte offset of the sample currently in each DAC or ADC, in which case the GetPosition method simply retrieves the contents of the position register for the appropriate stream. Other audio hardware can only supply the driver with DMA pointers into the audio buffers, in which case the GetPosition method must provide a best estimate of the byte offset in the DAC or ADC based on the current DMA position and the buffering delays internal to the device.

Audio hardware that internally buffers a portion of a playback or capture stream might make a precise position reading more difficult to obtain. In this case, the driver should estimate the current position as accurately as possible. For example, if an audio device prefetches the playback stream into an internal buffer, the driver might need to take both the buffer size and timing information into account in order to properly estimate the play position.

The WaveCyclic port driver implements a property handler for KSPROPERTY_AUDIO_POSITION. This property handler calls the GetPosition method to obtain the current play or record position from the miniport driver. For more information, see Audio Position Property.

Requirements

Requirement	Value
Target Platform	Universal
Header	portcls.h (include Portcls.h)
IRQL	<=DISPATCH_LEVEL