## 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.

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