CSourceSeeking Class

CSourceSeeking class hierarchy

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

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

CSourceSeeking Constructs a CSourceSeeking object.

Overridable Member Functions

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

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

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.

Syntax

virtual HRESULT ChangeRate(void) PURE;

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
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.

Syntax

virtual HRESULT ChangeStart(void) PURE;

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
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.

Syntax

virtual HRESULT ChangeStop(void) PURE;

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
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.

Syntax

HRESULT CheckCapabilities(

  DWORD *pCapabilities

  );

Parameters

pCapabilities
Pointer to a DWORD 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 Value

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.

Syntax

HRESULT ConvertTimeFormat(

  LONGLONG *pTarget,

  const GUID *pTargetFormat,

  LONGLONG Source,

  const GUID *pSourceFormat

  );

Parameters

pTarget
Pointer to the time set to Source time if the format is TIME_FORMAT_MEDIA_TIME or NULL.
pTargetFormat
Pointer to the GUID of the TIME_FORMAT_MEDIA_TIME format, or NULL.
Source
Time in original format.
pSourceFormat
Pointer to the GUID of the TIME_FORMAT_MEDIA_TIME format, or NULL.

Return Value

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.

Syntax

CSourceSeeking(

  const TCHAR *pName,

  LPUNKNOWN pUnk,

  HRESULT *phr,

  CCritSec *pLock

  );

Parameters

pName
Pointer to the 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 Value

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.

Syntax

HRESULT GetAvailable(

  LONGLONG *pEarliest,

  LONGLONG *pLatest

  );

Parameters

pEarliest
Pointer to the earliest time that can be seeked to. Set to zero.
pLatest
Pointer to the latest time that can be seeked to. Set to m_rtDuration.

Return Value

Returns S_OK.

CSourceSeeking::GetCapabilities

CSourceSeeking Class

Retrieves the seeking capabilities of the media stream.

Syntax

HRESULT GetCapabilities(

  DWORD *pCapabilities

  );

Parameters

pCapabilities
Pointer 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 Value

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

CSourceSeeking::GetCurrentPosition

CSourceSeeking Class

This method is not currently implemented and returns E_NOTIMPL.

Syntax

HRESULT GetCurrentPosition(
  LONGLONG *pCurrent
);

Parameters

pCurrent
Pointer to the current position in current time format units.

Return Value

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.

Syntax

HRESULT GetDuration(

  LONGLONG *pDuration

  );

Parameters

pDuration
Pointer to the duration of the media stream set to the value in m_rtDuration.

Return Value

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.

Syntax

HRESULT GetPositions(

  LONGLONG *pCurrent,

  LONGLONG *pStop

  );

Parameters

pCurrent
Pointer to the current start time set to the value in m_rtStart.
pStop
Pointer to the current stop time set to the value in m_rtStop.

Return Value

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.

Syntax

HRESULT GetPreroll(

  LONGLONG *pPreroll

  );

Parameters

pPreroll
Pointer to the returned preroll time of zero.

Return Value

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

CSourceSeeking::GetRate

CSourceSeeking Class

Retrieves the current playback rate.

Syntax

HRESULT GetRate(

  double *pdRate

  );

Parameters

pdRate
Pointer to the returned playback rate set to the value in m_dRateSeeking, where 1 is the normal rate.

Return Value

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.

Syntax

HRESULT GetStopPosition(

  LONGLONG *pStop

  );

Parameters

pStop
Pointer to the returned stop time set to the value in m_rtStop.

Return Value

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.

Syntax

HRESULT GetTimeFormat(

  const GUID *pFormat

  );

Parameters

pFormat
Pointer to the media time format set to TIME_FORMAT_MEDIA_TIME.

Return Value

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.

Syntax

HRESULT IsFormatSupported(

  const GUID *pFormat

  );

Parameters

pFormat
Pointer to the time format to compare to TIME_FORMAT_MEDIA_TIME.

Return Value

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.

Syntax

HRESULT IsUsingTimeFormat(

  const GUID *pFormat

  );

Parameters

pFormat
Pointer to the time format to compare to TIME_FORMAT_MEDIA_TIME.

Return Value

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.

Syntax

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

Parameters

riid
Reference identifier.
ppv
Address of a pointer to the interface.

Return Value

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.

Syntax

HRESULT QueryPreferredFormat(
  GUID *pFormat
  );

Parameters

pFormat
Pointer to the time format set to TIME_FORMAT_MEDIA_TIME.

Return Value

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.

Syntax

HRESULT SetPositions(

  LONGLONG *pCurrent,

  DWORD CurrentFlags,

  LONGLONG *pStop,

  DWORD StopFlags

  );

Parameters

pCurrent
Pointer to the 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
Pointer to the 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 Value

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.

CSourceSeeking::SetRate

CSourceSeeking Class

Sets a new playback rate.

Syntax

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 Value

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.

CSourceSeeking::SetTimeFormat

CSourceSeeking Class

Checks that the requested format is TIME_FORMAT_MEDIA_TIME.

Syntax

HRESULT SetTimeFormat(

  const GUID *pFormat

  );

Parameters

pFormat
Pointer to the time format to compare to TIME_FORMAT_MEDIA_TIME.

Return Value

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.

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.

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.

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.

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