CSourceSeeking Class

CSourceSeeking is an abstract class that assists source filters with the implementation of IMediaSeeking interface methods. This class enables a source filter to handle calls that change the start and stop positions in the media stream and the playback rate.

Derive from this class and set the positions. This class supports IMediaSeeking, and calls the pure virtual member functions CSourceSeeking::ChangeStart, CSourceSeeking::ChangeStop, and CSourceSeeking::ChangeRate when CSourceSeeking::SetPositions or CSourceSeeking::SetRate is called, to enable a source filter to handle these commands and start sending new data.

Override the CSourceSeeking::ChangeStart, CSourceSeeking::ChangeStop, and CSourceSeeking::ChangeRate member functions to do something when the properties change.

Protected Data Members

Name	Description
m_dRateSeeking	Playback rate. Set to 1 by default.
m_dwSeekingCaps	Seeking capabilities returned in the GetCapabilities function. Can be one or more of the following values: AM_SEEKING_CanSeekForwards, AM_SEEKING_CanSeekBackwards, AM_SEEKING_CanSeekAbsolute, AM_SEEKING_CanGetStopPos, AM_SEEKING_CanGetDuration. Set to all of these by default.
m_pLock	Pointer to a CCritSec object for locking.
m_rtDuration	Duration of the stream. Set to m_rtStop by default.
m_rtStart	Start time. Set to zero by default.
m_rtStop	Stop time. Set to the largest positive 64-bit integer possible (9223372036854775807) by default.

Member Functions

Name	Description
CSourceSeeking	Constructs a CSourceSeeking object.

Overridable Member Functions

Name	Description
ChangeRate	Override this pure virtual to handle notification of a change of sample rate.
ChangeStart	Override this pure virtual to handle notification of a change of start time.
ChangeStop	Override this pure virtual to handle notification of a change in stop time.

Implemented IMediaSeeking Methods

Name	Description
CheckCapabilities	Checks that all requested capabilities are in m_dwSeekingCaps.
ConvertTimeFormat	Checks that the time format is TIME_FORMAT_MEDIA_TIME. This is the only format currently available.
GetAvailable	Retrieves the range of seeking times. Earliest is zero and latest is the media stream's duration.
GetCapabilities	Retrieves the current seeking capabilities in m_dwSeekingCaps.
GetCurrentPosition	Not currently implemented.
GetDuration	Retrieves the length of time the media stream will play.
GetPositions	Retrieves the current start and stop position settings.
GetPreroll	Sets the preroll time to zero.
GetRate	Retrieves the current playback rate.
GetStopPosition	Retrieves the position within the media stream at which playback should stop.
GetTimeFormat	Sets the time format to TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.
IsFormatSupported	Determines if the requested format is TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.
IsUsingTimeFormat	Determines if the requested format is TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.
QueryPreferredFormat	Sets the preferred time format to TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.
SetPositions	Sets current and stop positions, first checking that the seeking options are valid.
SetRate	Sets the playback rate.
SetTimeFormat	Checks that the time format is TIME_FORMAT_MEDIA_TIME. This is the only format currently supported.

Implemented INonDelegatingUnknown Methods

Name	Description
NonDelegatingQueryInterface	Retrieves an interface and increments the reference count on the interface.

---

CSourceSeeking::ChangeRate

CSourceSeeking Class

Override this member function to handle notification of a change of sample rate.

virtual HRESULT ChangeRate( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

This member function is called when a change to the rate has been made by a call to the CSourceSeeking::SetRate function. Override this and change the rate of data sent. Typically, you do this by calling CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then send samples marked with new time stamps, for example, with an implementation NewSegment method.

---

CSourceSeeking::ChangeStart

CSourceSeeking Class

Override this member function to handle notification of a change of start time.

virtual HRESULT ChangeStart( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

This member function is called when a new start position has been requested by a call to CSourceSeeking::SetPositions. Override this and change the data sent. Typically, you do this by calling CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then send samples marked with new start time, for example, with an implementation NewSegment method.

---

CSourceSeeking::ChangeStop

CSourceSeeking Class

Override this member function to handle notification of a change in stop time.

virtual HRESULT ChangeStop( ) PURE;

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

This member function is called when a change to the stop position has been made by a call to CSourceSeeking::SetPositions. Override this and ensure that the correct stop time is being observed. Typically, you do this by calling CBaseInputPin::BeginFlush and CBaseInputPin::EndFlush, and then send samples marked with new stop time, for example, with an implementation NewSegment method.

---

CSourceSeeking::CheckCapabilities

CSourceSeeking Class

Checks that all the requested capabilities are among the flags in m_dwSeekingCaps.

HRESULT CheckCapabilities(
  DWORD * pCapabilities
  );

Parameters

pCapabilities

Pointer to an AM_SEEKING_CAPABILITIES enumerator containing the desired seeking capabilities flags in m_dwSeekingCaps. This value can be any combination of the following flags:

AM_SEEKING_CanGetCurrentPos

AM_SEEKING_CanGetDuration

AM_SEEKING_CanGetStopPos

AM_SEEKING_CanPlayBackwards

AM_SEEKING_CanSeekAbsolute

AM_SEEKING_CanSeekBackwards

AM_SEEKING_CanSeekForwards

Return Values

Returns E_POINTER if pCapabilities is not a valid pointer, S_OK if all the requested capabilities in pCapabilities are supported, or S_FALSE if they are not.

---

CSourceSeeking::ConvertTimeFormat

CSourceSeeking Class

Checks that the time format is TIME_FORMAT_MEDIA_TIME. This is the only format currently available.

HRESULT ConvertTimeFormat(
  LONGLONG * pTarget,
  const GUID * pTargetFormat,
  LONGLONG Source,
  const GUID * pSourceFormat
  );

Parameters

pTarget

Time set to Source time if the format is TIME_FORMAT_MEDIA_TIME or NULL.

pTargetFormat

GUID of the TIME_FORMAT_MEDIA_TIME format, or NULL.

Source

Time in original format.

pSourceFormat

GUID of the TIME_FORMAT_MEDIA_TIME format, or NULL.

Return Values

Returns E_POINTER if pTarget is not a valid pointer, or E_INVALIDARG if pTargetFormat and pSourceFormat are not equal to TIME_FORMAT_MEDIA_TIME or NULL; otherwise, returns S_OK.

---

CSourceSeeking::CSourceSeeking

CSourceSeeking Class

Constructs a CSourceSeeking object.

CSourceSeeking(
  const TCHAR * pName,
  LPUNKNOWN pUnk,
  HRESULT * phr,
  CCritSec * pLock
  );

Parameters

pName

Name of the object used in the CSourceSeeking constructor for debugging purposes.

pUnk

Pointer to the owner of this object.

phr

Pointer to an HRESULT value for information about the results of creating this object.

pLock

Pointer to a CCritSec object used for synchronization within a process.

Return Values

No return value.

Remarks

Allocate the pName parameter in static memory. This name appears on the debugging terminal upon creation and deletion of the object.

---

CSourceSeeking::GetAvailable

CSourceSeeking Class

Returns the range of seeking times.

HRESULT GetAvailable(
  LONGLONG * pEarliest,
  LONGLONG * pLatest
  );

Parameters

pEarliest

Earliest time that can be seeked to. Set to zero.

pLatest

Latest time that can be seeked to. Set to m_rtDuration.

Return Values

Returns S_OK.

---

CSourceSeeking::GetCapabilities

CSourceSeeking Class

Retrieves the seeking capabilities of the media stream.

HRESULT GetCapabilities(
  DWORD * pCapabilities
  );

Parameters

pCapabilities

Set to the seeking capability flags in m_dwSeekingCaps, which can be any combination of the following:

AM_SEEKING_CanGetCurrentPos

AM_SEEKING_CanGetDuration

AM_SEEKING_CanGetStopPos

AM_SEEKING_CanPlayBackwards

AM_SEEKING_CanSeekAbsolute

AM_SEEKING_CanSeekBackwards

AM_SEEKING_CanSeekForwards

Return Values

Returns E_POINTER if pCapabilities is invalid; otherwise, returns S_OK.

---

CSourceSeeking::GetCurrentPosition

CSourceSeeking Class

Not currently implemented.

HRESULT GetCurrentPosition(
  LONGLONG* pCurrent
  );

Parameters

pCurrent

Current position in current time format units.

Return Values

Returns E_NOTIMPL.

Remarks

This function is typically supported only in renderers and not in source filters.

---

CSourceSeeking::GetDuration

CSourceSeeking Class

Retrieves the length of time that the media stream will play.

HRESULT GetDuration(
  LONGLONG* pDuration
  );

Parameters

pDuration

Duration of the media stream set to the value in m_rtDuration.

Return Values

Returns E_POINTER if pDuration is invalid; otherwise, returns S_OK.

Remarks

The duration in m_rtDuration is set to the stop time in m_rtStop. Set the stop time with the CSourceSeeking::SetPositions function.

---

CSourceSeeking::GetPositions

CSourceSeeking Class

Retrieves the current and stop position settings.

HRESULT GetPositions(
  LONGLONG * pCurrent,
  LONGLONG * pStop
  );

Parameters

pCurrent

Current start time set to the value in m_rtStart.

pStop

Current stop time set to the value in m_rtStop.

Return Values

Returns S_OK.

Remarks

The start and stop times are set in the CSourceSeeking::SetPositions function.

---

CSourceSeeking::GetPreroll

CSourceSeeking Class

Sets the preroll time to zero.

HRESULT GetPreroll(
  LONGLONG * pPreroll
  );

Parameters

pPreroll

Returned preroll time of zero.

Return Values

Returns E_POINTER if pPreroll is invalid; otherwise, returns S_OK.

---

CSourceSeeking::GetRate

CSourceSeeking Class

Retrieves the current playback rate.

HRESULT GetRate(
  double * pdRate
  );

Parameters

pdRate

Returned playback rate set to the value in m_dRateSeeking, where 1 is the normal rate.

Return Values

Returns E_POINTER if pdRate is invalid; otherwise, returns S_OK.

Remarks

Set the rate in the CSourceSeeking::SetRate function.

---

CSourceSeeking::GetStopPosition

CSourceSeeking Class

Retrieves the position within the media stream at which playback should stop.

HRESULT GetStopPosition(
  LONGLONG* pStop
  );

Parameters

pStop

Returned stop time set to the value in m_rtStop.

Return Values

Returns E_POINTER if pStop is invalid; otherwise, returns S_OK.

Remarks

Set the stop time in the CSourceSeeking::SetPositions function.

---

CSourceSeeking::GetTimeFormat

CSourceSeeking Class

Sets the time format to TIME_FORMAT_MEDIA_TIME, which determines the format of units used during seeking.

HRESULT GetTimeFormat(
  const GUID * pFormat
  );

Parameters

pFormat

Media time format set to TIME_FORMAT_MEDIA_TIME.

Return Values

Returns E_POINTER if pFormat is invalid; otherwise, returns S_OK.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported.

---

CSourceSeeking::IsFormatSupported

CSourceSeeking Class

Determines if the requested format is TIME_FORMAT_MEDIA_TIME.

HRESULT IsFormatSupported(
  const GUID * pFormat
  );

Parameters

pFormat

Time format to compare to TIME_FORMAT_MEDIA_TIME.

Return Values

Returns E_POINTER if pFormat is invalid, S_OK if the format in pFormat is TIME_FORMAT_MEDIA_TIME, or S_FALSE if the format in pFormat is not TIME_FORMAT_MEDIA_TIME.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported. As implemented, this function is the same as CSourceSeeking::IsUsingTimeFormat.

---

CSourceSeeking::IsUsingTimeFormat

CSourceSeeking Class

Determines if the requested format is TIME_FORMAT_MEDIA_TIME.

HRESULT IsUsingTimeFormat(
  const GUID * pFormat
  );

Parameters

pFormat

Time format to compare to TIME_FORMAT_MEDIA_TIME.

Return Values

Returns E_POINTER if pFormat is invalid, S_OK if the format in pFormat is TIME_FORMAT_MEDIA_TIME, or S_FALSE if the format in pFormat is not TIME_FORMAT_MEDIA_TIME.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported. As implemented, this method is the same as CSourceSeeking::IsFormatSupported.

---

CSourceSeeking::NonDelegatingQueryInterface

CSourceSeeking Class

Retrieves an interface and increments the reference count on the interface.

HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void **ppv
  );

Parameters

riid

Reference identifier.

ppv

Pointer to the interface.

Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

Returns pointers to the IMediaSeeking and IUnknown interfaces by default. Override this method to publish any additional interfaces implemented by the derived class.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.

---

CSourceSeeking::QueryPreferredFormat

CSourceSeeking Class

Sets the preferred time format to TIME_FORMAT_MEDIA_TIME.

HRESULT QueryPreferredFormat(
  GUID *pFormat
  );

Parameters

pFormat

Time format set to TIME_FORMAT_MEDIA_TIME.

Return Values

Returns E_POINTER if pFormat is invalid; otherwise, returns S_OK.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported.

---

CSourceSeeking::SetPositions

CSourceSeeking Class

Sets current and stop positions, first checking that the seeking options are valid.

HRESULT SetPositions(
  LONGLONG * pCurrent,
  DWORD CurrentFlags,
  LONGLONG * pStop,
  DWORD StopFlags
  );

Parameters

pCurrent

Start position if stopped, or position to continue from if paused.

CurrentFlags

Flags that indicate the type of seek. Valid values are AM_SEEKING_AbsolutePositioning and AM_SEEKING_RelativePositioning. See the IMediaSeeking::SetPositions method for a description of these flags.

pStop

Position in the stream at which to quit playback.

StopFlags

Flags that indicate stop position seeking options. Valid values are AM_SEEKING_AbsolutePositioning, AM_SEEKING_RelativePositioning, and AM_SEEKING_IncrementalPositioning. See the IMediaSeeking::SetPositions method for a description of these flags.

Return Values

Returns E_INVALIDARG if CurrentFlags and StopFlags are not one of the values listed, or E_POINTER if pCurrent or pStop is invalid; otherwise, returns the HRESULT returned by calls to the CSourceSeeking::ChangeStart and CSourceSeeking::ChangeStop functions.

Remarks

You must implement ChangeStart and ChangeStop to use this method.

See Also

CSourceSeeking::GetPositions, CSourceSeeking::GetStopPosition, CSourceSeeking::GetDuration

---

CSourceSeeking::SetRate

CSourceSeeking Class

Sets a new playback rate.

HRESULT SetRate(
  double dRate
  );

Parameters

dRate

New rate, where 1.0 is the normal normal playback speed. Specifying 2.0 causes playback at twice the normal rate: a video created for 10 frames per second (fps) will be played back at 20 fps, if resources permit. Audio streams played back at above-normal speed increase the pitch rather than drop samples. A rate of 0.5 specifies half speed.

Return Values

Returns the HRESULT value returned by the call to the CSourceSeeking::ChangeRate function.

Remarks

You must implement ChangeRate to use this method. The m_dRateSeeking data member is set to the new rate. Setting the rate to zero causes an error.

See Also

CSourceSeeking::GetRate

---

CSourceSeeking::SetTimeFormat

CSourceSeeking Class

Checks that the requested format is TIME_FORMAT_MEDIA_TIME.

HRESULT SetTimeFormat(
  const GUID * pFormat
  );

Parameters

pFormat

Time format to compare to TIME_FORMAT_MEDIA_TIME.

Return Values

Returns E_POINTER if pFormat is invalid, S_OK if the format in pFormat is TIME_FORMAT_MEDIA_TIME, or E_INVALIDARG if the format in pFormat is not TIME_FORMAT_MEDIA_TIME.

Remarks

TIME_FORMAT_MEDIA_TIME is the only time format currently supported.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page