IMediaSeeking Interface

The IMediaSeeking interface improves on the IMediaPosition interface by allowing arbitrary formats for seekable units, such as frames, bytes, and 100-nanosecond units of time. It also offers the ability to set start and stop times using a single method call, which is absent in IMediaPosition. When seeking to time units, IMediaSeeking expresses time as a 64-bit integer (LONGLONG), providing greater accuracy than IMediaPosition, which expresses time in decimal seconds stored as a double. However, because of this difference in time unit data types, only IMediaPosition supports Automation. IMediaPosition is maintained as an interface for this reason only. Applications not using Automation to seek the media stream should use the IMediaSeeking interface instead.

The IMediaSeeking interface is set by using a defined time format, such as TIME_FORMAT_MEDIA_TIME or TIME_FORMAT_SAMPLE, which then defines how parameters in other methods are interpreted. The format can be changed only when the filter graph is stopped. The default Microsoft® DirectShow® plug-in distributor method for this method takes care of this automatically, effectively eliminating this restriction. Only one time format is available at any given time.

When a filter is seeked in media time, it must return a time at which the media seek positioned it. For example, if a source filter is seeked to frame 30, it might return 2 seconds if the video is 15 frames per second. With that position time (of 2 seconds), the filter graph manager can then seek all the other filters to that 2-second position so that the graph as a whole remains synchronized.

Time formats are globally unique identifiers (GUID), which are defined as follows:
GUIDDefined as
0L-0-0-0-0-0-0-0-0-0-0 TIME_FORMAT_NONE
7b785570-8c82-11cf-bc0c-00aa00ac74f6 TIME_FORMAT_FRAME
7b785571-8c82-11cf-bc0c-00aa00ac74f6 TIME_FORMAT_BYTE
7b785572-8c82-11cf-bc0c-00aa00ac74f6 TIME_FORMAT_SAMPLE
7b785573-8c82-11cf-bc0c-00aa00ac74f6 TIME_FORMAT_FIELD
7b785574-8c82-11cf-bc0c-00aa00ac74f6 TIME_FORMAT_MEDIA_TIME

The filter graph manager exposes the IMediaSeeking interface from the plug-in distributor (PID) that handles this interface. If none of the filters within the graph support this interface, the PID will return E_NOINTERFACE; if at least one filter supports the interface, but all such filters return E_NOTIMPL, the PID will return E_NOTIMPL. Otherwise, the filter graph manager will return either a success or the first failure it encounters.

A success normally means that a seekable file source filter was found. Filters, such as a file source filter, will expose IMediaSeeking if they can seek their data or if their output pin represents a seekable stream. The renderer filter also should expose this interface. Output pins of transform filters expose this interface to pass the positioning information upstream, from the renderer through each intermediate filter to the seekable filter.

Use the CPosPassThru base class to implement this interface on output pins of transform filters used to pass media positioning information upstream. This is enabled by default in the pin base classes. Renderers can use the same class, although in most cases they should use CRendererPosPassThru, which is derived from CPosPassThru, to implement this interface.

Applications can use this interface to set or retrieve properties such as the duration of the stream, the current position, the stop time, and the media time format being used. Most commonly, an application will use the methods on this interface to play a media stream for some duration starting at some set position in the stream (for example, 10 seconds from the start).

A transform filter will call the IMediaSeeking methods on the connected upstream pin when passing media times upstream from the renderer.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IMediaSeeking methodsDescription
GetCapabilities Retrieves all the seeking capabilities of the media stream.
CheckCapabilities Determines whether a media stream has a specific seeking capability.
IsFormatSupported Determines if a specified time format is supported.
QueryPreferredFormat Retrieves the preferred time format to be used by the interface.
GetTimeFormat Retrieves the current time format.
IsUsingTimeFormat Determines if the time format being used in the call is the same as the one currently in use by the interface.
SetTimeFormat Sets the time format, which determines the format of units used during seeking.
GetDuration Retrieves the length of time that the media stream will play.
GetStopPosition Retrieves the position within the media stream at which playback should stop.
GetCurrentPosition Retrieves the current position within the media stream.
ConvertTimeFormat Converts a time from one time format to another.
SetPositions Sets current and stop positions and applies flags to both.
GetPositions Retrieves the current and stop position settings.
GetAvailable Retrieves the range of times in which seeking is efficient.
SetRate Sets a new playback rate.
GetRate Retrieves the current rate.
GetPreroll Retrieves the preroll settings.

IMediaSeeking::CheckCapabilities

IMediaSeeking Interface

Determines whether a media stream has a specific seeking capability.

Syntax

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

Parameters

pCapabilities
[in, out] Pointer to a DWORD whose bits you set by performing a bitwise-inclusive-OR operation on the AM_SEEKING_SEEKING_CAPABILITIES attribute(s) you are interested in. The results can be determined either through the HRESULT return value or by examining pCapabilities after the method returns.

Return Value

Returns one of the following values.
E_FAILNo capabilities in pCapabilities are present.
S_FALSESome capabilities in pCapabilities are present.
S_OKAll capabilities in pCapabilities are present.

Remarks

If you are only interested in a few specific capabilities, calling this method is more efficient than calling GetCapabilities, which checks all the stream's seeking capabilities.

Indicate which capabilities you want to know about by using a bitwise-inclusive-OR operation on any combination of the AM_SEEKING_SEEKING_CAPABILITIES values.

The following code example shows how to find out whether the stream supports forward seeking, backward seeking, and absolute seeking.

HRESULT hr;
IMediaSeeking* pMediaSeeking;
hr = pFilterGraphMgr->QueryInterface(IID_IMediaSeeking, (void**)&pMediaSeeking);

// Set all bits to zero.
DWORD caps = 0;

// Indicate which ones you want to know about.
caps |= AM_SEEKING_CanSeekAbsolute | 
    AM_SEEKING_CanSeekForwards |
    AM_SEEKING_CanSeekBackwards;

// Call CheckCapabilities.
hr = pMediaSeeking->CheckCapabilities(&caps);

if(SUCCEEDED(hr)) // the stream has all three capabilities
{
	// You can seek forward, backward, or to an absolute position.
	.
	.
	.
}
else if(FAILED(hr) // the stream has none
                   //   of the capabilities we asked about.
{
	// go to plan B	
	.
	.
	.
}
else if(hr == S_FALSE) // the stream has at least one but not 
                       //   all the capabilities we asked about
{
	// To find out which of the specified capabilities
	//   it does not have, check to see which bits were set to zero.
	if (caps & AM_SEEKING_CanSeekAbsolute)
		// then the stream can seek to an absolute position
	if caps & AM_SEEKING_CanSeekAbsolute)
		// then the stream can seek forward
	if (caps & AM_SEEKING_CanSeekBackwards)
		// then the stream can seek backward
}

IMediaSeeking::ConvertTimeFormat

IMediaSeeking Interface

Converts a time from one format to another.

Syntax

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

Parameters

pTarget
[out] Pointer to the time in converted format.
pTargetFormat
[in] Pointer to the GUID of the format to convert to, or the currently selected format if NULL.
Source
[in] Time in original format.
pSourceFormat
[in] Pointer to the GUID of the format to be converted from, or the currently selected format if NULL.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns NOERROR for success and E_NOTIMPL if the method is not implemented.

Remarks

Time formats can be converted between any two of the following:

IMediaSeeking::GetAvailable

IMediaSeeking Interface

Retrieves the range of times in which seeking is efficient.

Syntax

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

Parameters

pEarliest
[out] Pointer to the earliest time that can be efficiently seeked to.
pLatest
[out] Pointer to the latest time that can be efficiently seeked to.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success and E_NOTIMPL if the method is not implemented.

Remarks

This method is intended primarily for seeking in media streams that might have excessive latency, such as when playing back media "live" from an Internet server. The returned values indicate cached data that has already arrived, which can be easily seeked. It is assumed that seeking to values beyond these returned parameters will cause a delay while waiting for the data to arrive.

IMediaSeeking::GetCapabilities

IMediaSeeking Interface

Retrieves all the seeking capabilities of the media stream.

Syntax

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

Parameters

pCapabilities
[out] Pointer to a DWORD whose bits will be set to any combination of the AM_SEEKING_SEEKING_CAPABILITIES flags.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK.

Remarks

Unlike CheckCapabilities, which retrieves information only on seeking capabilities you specify, this method returns information on all the seeking capabilities of the stream. Examine pCapabilities by performing a separate bitwise-AND operation on each AM_SEEKING_SEEKING_CAPABILITIES value you are interested in.

DWORD caps = 0;
pMediaSeeking->GetCapabilities(&caps);

if (caps & AM_SEEKING_CanGetCurrentPos)
	// then the stream can seek to the current position
if(caps & AM_SEEKING_CanPlayBackwards)
	// The stream can also play backward.

IMediaSeeking::GetCurrentPosition

IMediaSeeking Interface

Retrieves the current position in terms of the total length of the media stream.

Syntax

HRESULT GetCurrentPosition(
    LONGLONG *pCurrent
);

Parameters

pCurrent
[out] Pointer to the current position in current time format units.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns E_POINTER if the pointer argument is NULL, or another COM return code otherwise.

Remarks

The current position is the position that playback has reached. It is a value between zero and the duration. If the filter graph is paused, this is the position at which it will restart.

Because IMediaSeeking uses media times for its time parameters, the current position value is independent of any rate or start position that might have been set.

When the filter graph is stopped or paused, this method returns the position at which playback will recommence. When the filter graph is running, the filter graph manager returns the position according to the data arriving at the renderer. If an individual filter implements this method, it should return the media time of the sample it is currently processing when paused or running.

After stopping or pausing, a run command causes playback to begin at the current position. This will be where playback stopped or paused, unless there has been an IMediaSeeking::SetPositions call in the meantime to reset the start position.

IMediaSeeking::GetDuration

IMediaSeeking Interface

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

Syntax

HRESULT GetDuration(
    LONGLONG *pDuration
);

Parameters

pDuration
[out] Pointer to the returned length of the media stream.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns E_POINTER if the pointer argument is NULL, or another COM return code otherwise.

Remarks

The duration assumes normal playback speed, and it is therefore unaffected by the rate. Although IMediaSeeking allows filters to be seeked in media time, it still requires that the media samples it sends downstream are time stamped appropriately.

IMediaSeeking::GetPositions

IMediaSeeking Interface

Returns the current and stop position settings.

Syntax

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

Parameters

pCurrent
[out] Pointer to the start time in the current time format.
pStop
[out] Pointer to the stop time in the current time format.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method is provided for efficiency so that just one call will retrieve both the current and stop position.

IMediaSeeking::GetPreroll

IMediaSeeking Interface

Retrieves the preroll settings.

Syntax

HRESULT GetPreroll(
    LONGLONG *pllPreroll
);

Parameters

pllPreroll
[out] Pointer to the returned preroll time.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success and E_NOTIMPL if the method is not implemented.

Remarks

This method retrieves the time prior to the start position that the filter graph begins any nonrandom access device rolling.

IMediaSeeking::GetRate

IMediaSeeking Interface

Retrieves the current rate.

Syntax

HRESULT GetRate(
    double *dRate
);

Parameters

dRate
[out] Pointer to the current rate, where 1 is the normal rate.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IMediaSeeking::GetStopPosition

IMediaSeeking Interface

Retrieves the time at which the media stream stops.

Syntax

HRESULT GetStopPosition(
    LONGLONG *pStop
);

Parameters

pStop
[out] Pointer to the returned stop time.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns E_POINTER if the pointer argument is NULL, S_OK for success, or E_NOTIMPL if the method is not implemented.

Remarks

The stop position is a time between zero and the duration of the media at which playback should stop.

The stop position is applied before the rate and therefore is the position at typical playback speed.

IMediaSeeking::GetTimeFormat

IMediaSeeking Interface

Retrieves the current time format, which determines the format of units used during seeking.

Syntax

HRESULT GetTimeFormat(
    GUID *pFormat
);

Parameters

pFormat
[out] Pointer to the time format currently supported by this interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success, or E_NOTIMPL if the method is not implemented.

Remarks

For a list of time formats, see the IsFormatSupported method. Only one time format can be set on the filter graph at any one time.

IMediaSeeking::IsFormatSupported

IMediaSeeking Interface

Determines if a specified time format is supported.

Syntax

HRESULT IsFormatSupported(
    const GUID *pFormat
);

Parameters

pFormat
[in] Pointer to the time format to compare.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK if the time format is supported; otherwise returns S_FALSE.

Remarks

Time formats are defined as follows:
TIME_FORMAT_NONE Seeking is not supported.
TIME_FORMAT_FRAME Seeks to specific video frames.
TIME_FORMAT_SAMPLE Seeks to samples in the stream.
TIME_FORMAT_FIELD Seeks to interlaced video fields.
TIME_FORMAT_BYTE Seeks to a byte in the stream.
TIME_FORMAT_MEDIA_TIME Seeks to time stamps on the media samples.

Third-party vendors are encouraged to add their own time formats to this list.

IMediaSeeking::IsUsingTimeFormat

IMediaSeeking Interface

Determines if the time format being used in the call is the same as the one currently in use by the interface.

Syntax

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

Parameters

pFormat
[in] Pointer to the time format to check.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK if pFormat is the current time format; otherwise returns S_FALSE.

Remarks

This can be used in place of IMediaSeeking::GetTimeFormat to compare time formats, because it is faster and does not require copying the GUID.

IMediaSeeking::QueryPreferredFormat

IMediaSeeking Interface

Retrieves the preferred time format to be used by the interface.

Syntax

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

Parameters

pFormat
[out] Pointer to the time format preferred by the interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns NOERROR.

Remarks

For a list of available time formats, see IsFormatSupported. If the time format returned is not satisfactory, use the IsFormatSupported method to query for supported time formats that you can use.

IMediaSeeking::SetPositions

IMediaSeeking Interface

Sets current and stop positions and applies flags to both.

Syntax

HRESULT SetPositions(
    LONGLONG *pCurrent,
    DWORD dwCurrentFlags,
    LONGLONG *pStop,
    DWORD dwStopFlags
);

Parameters

pCurrent
[in,out] Pointer to the start position if stopped, or position from which to continue if paused.
dwCurrentFlags
[in] When seeking, one of these flags must be set to indicate the type of seek. The flags passed to this method should include one positioning value and (optionally) any of the nonpositioning values.
AM_SEEKING_NoPositioningNo change in positioning.
AM_SEEKING_AbsolutePositioningPosition supplied is absolute.
AM_SEEKING_RelativePositioning Position supplied is relative to the current position.
AM_SEEKING_IncrementalPositioning Stop position relative to current; useful for seeking when paused (only valid in conjunction with stop times).
AM_SEEKING_PositioningBitsMask Mask flag; determine if seeking is required by performing a bitwise-AND of the four flags listed above and this mask. If the resulting value is nonzero, some form of seeking is required. Check the value of the last two bits to determine which of the above flags are set.
AM_SEEKING_SeekToKeyFrame Seek to the nearest key frame (not as accurate but quicker).
AM_SEEKING_ReturnTime Return the media time equivalents for pCurrent and pStop (overwriting these values with the returned values).
AM_SEEKING_Segment At the end of the segment call EC_ENDOFSEGMENT instead of EndOfStream.
AM_SEEKING_NoFlush Do not flush.
pStop
[in,out] Pointer to the position in the stream at which to quit.
dwStopFlags
[in] Stop position seeking options to be applied. These are the same as listed for dwCurrentFlags.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns E_POINTER if the pointer argument is NULL, NOERROR for success, E_INVALIDARG if a parameter is out of range, or another COM return code otherwise.

Example

The following code fragment checks for the type of seeking required.

switch ( dwFlags & AM_SEEKING_PositioningBitsMask )
{
    case AM_SEEKING_IncrementalPositioning:
        // Check this is on a stop time
        // Get Current, add this delta, apply result as new stop time
        break;
    case AM_SEEKING_RelativePositioning:
        // ...
        break;
    case AM_SEEKING_AbsolutePositioning:
        // ...
        break;
    case AM_SEEKING_NoPositioning:
        // Nothing to do.
        break;
}

IMediaSeeking::SetRate

IMediaSeeking Interface

Sets a new playback rate.

Syntax

HRESULT SetRate(
    double dRate
);

Parameters

dRate
[in] New rate, where 1 is the normal rate, 2 is twice as fast, and so on.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success, E_INVALIDARG if the parameter is invalid, or E_NOTIMPL if the method is not implemented.

IMediaSeeking::SetTimeFormat

IMediaSeeking Interface

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

Syntax

HRESULT SetTimeFormat(
    const GUID *pFormat
);

Parameters

pFormat
[in] Pointer to the time format to be supported by this interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The default DirectShow implementation returns S_OK for success, E_FAIL for failure, or E_NOTIMPL if the method is not implemented.

Remarks

For a list of time formats, see the IsFormatSupported method.

The filter graph must be stopped before calling this method or a VFW_E_WRONG_STATE error will be returned.


Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.