Microsoft DirectX 8.0

IMediaPosition Interface

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 methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IDispatch methodsDescription
GetTypeInfoCountRetrieves the number of type information interfaces the object provides.
GetTypeInfoRetrieves the type information for the object, which can then be used to get the type information for an interface.
GetIDsOfNamesMaps a set of names to a corresponding set of DISPIDs.
InvokeProvides access to properties and methods exposed by the object.
IMediaPosition methodsDescription
get_DurationRetrieves the duration of the stream.
put_CurrentPositionSets the current position, relative to the total duration of the stream.
get_CurrentPositionRetrieves the current position, relative to the total duration of the stream.
get_StopTimeRetrieves the time at which the playback will stop, relative to the duration of the stream.
put_StopTimeSets the time at which the playback will stop, relative to the duration of the stream.
get_PrerollTimeRetrieves the amount of data that will be queued before the start position.
put_PrerollTimeSets the amount of data that will be queued before the start position.
put_RateSets the playback rate.
get_RateRetrieves the playback rate.
CanSeekForwardDetermines whether the filter graph can seek forward in the stream.
CanSeekBackwardDetermines whether the filter graph can seek backward in the stream.

IMediaPosition::CanSeekBackward

IMediaPosition Interface

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_OKSuccess.
E_NOTIMPLNot implemented.
E_POINTERNULL pointer argument.

IMediaPosition::CanSeekForward

IMediaPosition Interface

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_OKSuccess.
E_NOTIMPLNot implemented.
E_POINTERNULL pointer argument.

IMediaPosition::get_CurrentPosition

IMediaPosition Interface

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_OKSuccess.
E_NOTIMPLNot implemented.
E_POINTERNULL 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.

IMediaPosition::get_Duration

IMediaPosition Interface

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_OKSuccess.
E_NOTIMPLNot implemented.
E_POINTERNULL pointer argument.

Remarks

This method retrieves the duration of the stream at normal playback speed. Changing the playback rate does not affect the duration.

IMediaPosition::get_PrerollTime

IMediaPosition Interface

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_OKSuccess.
E_NOTIMPLNot implemented.
E_POINTERNULL 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.

IMediaPosition::get_Rate

IMediaPosition Interface

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_OKSuccess.
E_NOTIMPLNot implemented.
E_POINTERNULL 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.

IMediaPosition::get_StopTime

IMediaPosition Interface

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_OKSuccess.
E_NOTIMPLNot implemented.
E_POINTERNULL pointer argument.

Remarks

The playback rate does not affect the value returned by this method.

IMediaPosition::put_CurrentPosition

IMediaPosition Interface

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_FALSEGraph was paused and is in transition back to a running state.
S_OKSuccess.
E_INVALIDARGInvalid argument.
E_NOTIMPLNot 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.

IMediaPosition::put_PrerollTime

IMediaPosition Interface

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_OKSuccess.
E_NOTIMPLNot implemented.

Remarks

The preroll is the time prior to the start position at which nonrandom access devices, such as tape players, should start rolling.

IMediaPosition::put_Rate

IMediaPosition Interface

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_OKSuccess.
E_INVALIDARGInvalid argument.
E_NOTIMPLNot 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.

IMediaPosition::put_StopTime

IMediaPosition Interface

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_OKSuccess.
E_INVALIDARGInvalid argument.
E_NOTIMPLNot 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).