IWMSyncReader::GetNextSample method (wmsdkidl.h)

  • Article

[The feature associated with this page, Windows Media Format 11 SDK, is a legacy feature. It has been superseded by Source Reader and Sink Writer. Source Reader and Sink Writer have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use Source Reader and Sink Writer instead of Windows Media Format 11 SDK, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The GetNextSample method retrieves the next sample from the file.

Syntax

HRESULT GetNextSample(
  [in]  WORD       wStreamNum,
  [out] INSSBuffer **ppSample,
  [out] QWORD      *pcnsSampleTime,
  [out] QWORD      *pcnsDuration,
  [out] DWORD      *pdwFlags,
  [out] DWORD      *pdwOutputNum,
  [out] WORD       *pwStreamNum
);

Parameters

[in] wStreamNum

WORD containing the stream number for which you would like a sample. If you pass zero, the next sample in the file is returned, regardless of stream number.

[out] ppSample

Pointer to a buffer that receives the sample. Set to NULL to retrieve the sample time without getting the sample. If set to NULL, pcnsDuration and pdwFlags must both be set to NULL as well.

[out] pcnsSampleTime

Pointer to a QWORD variable that receives the sample time in 100-nanosecond units.

[out] pcnsDuration

Pointer to QWORD variable that receives the duration of the sample in 100-nanosecond units.

[out] pdwFlags

Pointer to a DWORD containing one or more of the following flags.

Flag Description
No flag set None of the conditions for the other flags applies. For example, a delta frame in most cases would not have any flags set for it.
WM_SF_CLEANPOINT Indicates that the sample does not require any other samples to be decompressed. All audio samples and all video samples that are key frames are cleanpoints.
WM_SF_DISCONTINUITY The data stream has a gap in it, which could be due to a seek, a network loss, or other reason. This can be useful extra information for an application such as a codec or renderer. The flag is set on the first piece of data following the gap.
WM_SF_DATALOSS Some data has been lost between the previous sample and the sample with this flag set.

[out] pdwOutputNum

Pointer to a DWORD that receives the output number.

[out] pwStreamNum

Pointer to a WORD that receives the stream number.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return code Description
S_OK
 The method succeeded.
NS_E_NO_MORE_SAMPLES
 All the samples in the file have been read.
E_UNEXPECTED
 A problem occurred with a call within the method.
E_INVALIDARG
 wStreamNum specifies a stream number that is not valid.

OR

pcnsSampleTime is NULL

OR

ppSample, pcnsDuration, or pdwFlags is NULL, but one or both of the others are not.

OR

wStreamNum is 0 and both pdwOutputNum and pwStreamNum are NULL.
NS_E_INVALID_REQUEST
 No file is open and ready for reading by the synchronous reader.

OR

wStreamNum specifies a stream number that is turned off (not selected for reading).

Remarks

Both compressed and uncompressed samples are delivered by this method, depending upon whether you have called SetReadStreamSamples for the streams in the file. This is the only method to retrieve samples using the synchronous reader.

To begin receiving samples from anywhere in the file other than the beginning, you must first specify a range for playback. To specify a playback range based on presentation times, use the SetRange method. To set a range using frame numbers, use the SetRangeByFrame method. When you have received all of the samples in the file, or in the range if you specified one, the next call made to GetNextSample returns NS_E_NO_MORE_SAMPLES.

The timeline is presentation time if no output setting is specified. To get early delivery for a stream, use SetOutputSetting.

You can call GetNextSample in one of three ways:

  • If you pass a non-zero value as wStreamNum, you will get the next sample for the specified stream number. In this case, you can pass NULL for both pdwOutputNum and pwStreamNum.
  • If you pass zero as wStreamNum, and are using output numbers, you can pass NULL for pwStreamNum. In this case you must pass a valid address for pdwOutputNum.
  • If you pass zero as wStreamNum, and are not using output numbers, you can pass NULL for pdwOutputNum. In this case you must pass a valid address for pwStreamNum.
You can also use GetNextSample to retrieve precise times for video frames when reading compressed data. For more information, see To Retrieve Accurate Presentation Times for Compressed Samples by Frame.
Note  To ensure that you get correct sample durations from this method, you must configure the output for the stream. Call the SetOutputSetting method to set the g_wszVideoSampleDurations setting to TRUE. Subsequent calls to GetNextSample will return correct sample durations.
 

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only],Windows Media Format 9 Series SDK, or later versions of the SDK
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header wmsdkidl.h (include Wmsdk.h)
Library Wmvcore.lib; WMStubDRM.lib (if you use DRM)

See also

INSSBuffer Interface

IWMSyncReader Interface