See Also
 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
Although IMediaPositionallows applications a simple seeking interface on a filter graph, it has a number of limitations.
The IMediaPositioninterface allows seeking only by using REFTIME time-based units; however, many filter graphs would prefer to seek on units of samples, video frames, or fields in a compressed stream.
Also, the IMediaPositioninterface uses separate methods to set and retrieve position properties, which can cause unnecessary filter flushing.
The IMediaSeekinginterface improves on the IMediaPositioninterface by allowing arbitrary formats for seekable units, such as frames, bytes, and 100-nanosecond units of time.
It also offers the ability to start and stop times using a single method call, which is absent in IMediaPosition.
When seeking to time units, IMediaSeekingexpresses 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 IMediaPositionsupports Automation.
IMediaPositionis maintained as an interface for this reason only.
Applications not using Automation to seek the media stream should use the IMediaSeekinginterface instead.
The IMediaSeekinginterface 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 DirectShow plug-in distributor method for this method takes care of this automatically, effectively eliminating this restriction).
Only one time format is available at a 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 other filters to that 2-second position so the graph as a whole remains synchronized.
Time formats are globally unique identifiers (GUIDs), which are defined as follows.
| GUID | Defined 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 |
When to Implement
The filter graph manager exposes the IMediaSeekinginterface 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 one or more filters support 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 IMediaSeekingif 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 CPosPassThrubase 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.
When to Use
Applications can use this interface to set or retrieve properties such as
- The duration of the stream
- The current position
- The stop time
- 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 IMediaSeekingmethods on the connected upstream pin when passing media times upstream from the renderer.
Methods in Vtable Order
The following table shows the methods that appear in the Vtable beneath the standard COM methods inherited from IUnknown.
| Method | Description |
|---|---|
|
Returns the seeking capabilities of the media stream. |
|
|
Determines which capabilities exist on a media stream by applying seeking capability flags and checking the returned value. |
|
|
Determines if a specified time format is supported. |
|
|
Retrieves the preferred time format to be used by the interface. |
|
|
Retrieves the current time format. |
|
|
Determines if the time format being used in the call is the same as the one currently in use by the interface. |
|
|
Sets the time format, which determines the format of units used during seeking. |
|
|
Retrieves the length of time that the media stream will play. |
|
|
Retrieves the position within the media stream at which playback should stop. |
|
|
Retrieves the current position within the media stream. |
|
|
Converts a time from one time format to another. |
|
|
Sets current and stop positions and applies flags to both. |
|
|
Returns the current and stop position settings. |
|
|
Returns the range of times in which seeking is efficient. |
|
|
Sets a new playback rate. |
|
|
Returns the current rate. |
|
|
Retrieves the preroll settings. |
Requirements
| Windows Embedded CE | Windows CE 2.12 and later |
| Windows Mobile | Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later |
| Note | Microsoft DirectShow applications and DirectShow filters have
different include file and Library requirements
For more information, see Setting Up the Build Environment
|