Microsoft DirectX 8.0 |
Contains methods for seeking to a position within a stream.
The IMediaSeeking interface improves on this interface. Applications written in C/C++ should use IMediaSeeking instead of IMediaPosition. However, IMediaSeeking is not compatible with Automation, so applications written in Microsoft® Visual Basic® must use IMediaPosition instead.
This interface is exposed by the filter graph manager as well as by individual filters. Applications should obtain an IMediaPosition interface pointer from the filter graph manager, not from a filter. The filter graph manager distributes method calls to all of the renderer filters. The renderer filters propagate the calls upstream to the source filters. This sequence of events ensures that all streams remain synchronized.
If one of the distributed calls returns an error, the filter graph manager returns the first error value it received. Some of the distributed calls may have succeeded in this case. However, the filter graph does not return E_NOTIMPL unless all the distributed calls return E_NOTIMPL. If at least one filter in the graph implements the method, the filter graph manager does not return E_NOTIMPL.
Filter developers: Do not implement this method. Implement IMediaSeeking instead. If your filter supports IMediaSeeking, the filter graph manager automatically handles calls to IMediaPosition.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IDispatch methods Description GetTypeInfoCount Retrieves the number of type information interfaces the object provides. GetTypeInfo Retrieves the type information for the object, which can then be used to get the type information for an interface. GetIDsOfNames Maps a set of names to a corresponding set of DISPIDs. Invoke Provides access to properties and methods exposed by the object. IMediaPosition methods Description get_Duration Retrieves the duration of the stream. put_CurrentPosition Sets the current position, relative to the total duration of the stream. get_CurrentPosition Retrieves the current position, relative to the total duration of the stream. get_StopTime Retrieves the time at which the playback will stop, relative to the duration of the stream. put_StopTime Sets the time at which the playback will stop, relative to the duration of the stream. get_PrerollTime Retrieves the amount of data that will be queued before the start position. put_PrerollTime Sets the amount of data that will be queued before the start position. put_Rate Sets the playback rate. get_Rate Retrieves the playback rate. CanSeekForward Determines whether the filter graph can seek forward in the stream. CanSeekBackward Determines whether the filter graph can seek backward in the stream.
Determines whether the filter graph can seek backward in the stream.
Syntax
HRESULT CanSeekBackward( LONG *pCanSeekBackward );
Parameters
- pCanSeekBackward
- [out] Pointer to a variable that receives the value OATRUE if the graph can seek backward, or OAFALSE otherwise.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_NOTIMPL Not implemented. E_POINTER NULL pointer argument.
Determines whether the filter graph can seek forward in the stream.
Syntax
HRESULT CanSeekForward( LONG *pCanSeekForward );
Parameters
- pCanSeekForward
- [out] Pointer to a variable that receives the value OATRUE if the graph can seek forward, or OAFALSE otherwise.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_NOTIMPL Not implemented. E_POINTER NULL pointer argument.
Retrieves the current position, relative to the total duration of the stream.
Syntax
HRESULT get_CurrentPosition( REFTIME *pllTime );
Parameters
- pllTime
- [out] Pointer to a variable that receives the current position, in seconds.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_NOTIMPL Not implemented. E_POINTER NULL pointer argument.
Remarks
This method returns the current position that playback has reached. The value ignores the playback rate and start time. For example, if you set the rate to 2.0 and the start time to five seconds, running the graph for four seconds yields a current position of 9.0 seconds (5 + 4 × 2.0).
If the graph is paused or stopped, the current position is the point at which playback will resume.
Retrieves the duration of the stream.
Syntax
HRESULT get_Duration( REFTIME *plength );
Parameters
- plength
- [out] Pointer to a variable that receives the total stream length, in seconds.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_NOTIMPL Not implemented. E_POINTER NULL pointer argument.
Remarks
This method retrieves the duration of the stream at normal playback speed. Changing the playback rate does not affect the duration.
Retrieves the amount of data that will be queued before the start position.
Syntax
HRESULT get_PrerollTime( REFTIME *pllTime );
Parameters
- pllTime
- [out] Pointer to a variable that receives the preroll time, in seconds.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_NOTIMPL Not implemented. E_POINTER NULL pointer argument.
Remarks
The preroll is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.
If no filter in the graph implements this method, the filter graph manager sets the value of *pllTime to zero and returns S_OK.
Retrieves the playback rate.
Syntax
HRESULT get_Rate( double *pdRate );
Parameters
- pdRate
- [out] Pointer to a variable that receives the playback rate.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_NOTIMPL Not implemented. E_POINTER NULL pointer argument.
Remarks
The playback rate is expressed as a ratio of the normal speed. Thus, 1.0 is normal playback speed, 0.5 is half speed, and 2.0 is twice speed.
Retrieves the time at which the playback will stop, relative to the duration of the stream.
Syntax
HRESULT get_StopTime( REFTIME *pllTime );
Parameters
- pllTime
- [out] Pointer to a variable that receives the stop time, in seconds.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_NOTIMPL Not implemented. E_POINTER NULL pointer argument.
Remarks
The playback rate does not affect the value returned by this method.
Sets the current position, relative to the total duration of the stream.
Syntax
HRESULT put_CurrentPosition( REFTIME llTime );
Parameters
- llTime
- [in] New position, in seconds.
Return Values
Returns an HRESULT value. Possible values include the following:
S_FALSE Graph was paused and is in transition back to a running state. S_OK Success. E_INVALIDARG Invalid argument. E_NOTIMPL Not implemented.
Remarks
The position specified by the llTime parameter is relative to the total duration, ignoring playback rate. For example, if a source file is 10 seconds long, setting the position to 5.0 causes the graph to seek to the middle of the file, regardless of playback rate.
If the filter graph is running, the filter graph manager pauses the graph, issues the seek command, and then runs the graph again. If the method returns while the graph is still transitioning to a running state, the return value is S_FALSE.
If a filter is paused when it receives a seek command, it must flush existing data before it introduces the data from the new position. See IPin::BeginFlush and IPin::EndFlush.
Sets the amount of data that will be queued before the start position.
Syntax
HRESULT put_PrerollTime( REFTIME llTime );
Parameters
- llTime
- [in] Preroll time, in seconds.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_NOTIMPL Not implemented.
Remarks
The preroll is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.
Sets the playback rate.
Syntax
HRESULT put_Rate( double dRate );
Parameters
- dRate
- [in] Playback rate. Must not be zero.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_INVALIDARG Invalid argument. E_NOTIMPL Not implemented.
Remarks
The playback rate is expressed as a ratio of the normal speed. Thus, 1.0 is normal playback speed, 0.5 is half speed, and 2.0 is twice speed. For audio streams, changing the rate also changes the pitch.
For more information, see the remarks in IMediaSeeking::SetRate.
Sets the time at which the playback will stop, relative to the duration of the stream.
Syntax
HRESULT put_StopTime( REFTIME llTime );
Parameters
- llTime
- [in] Stop time, in seconds.
Return Values
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_INVALIDARG Invalid argument. E_NOTIMPL Not implemented.
Remarks
The stop time ignores the start time and the playback rate. For example, if the start time is 2 seconds, the stop time is 12 seconds, and the playback rate is 2.0, playback will stop after 5 seconds (real time).