CPosPassThru Class

CPosPassThru class hierarchy

The CPosPassThru class is a utility class that handles the IMediaPosition and IMediaSeeking interfaces for single-input pin renderers and transform filters.

IMediaPosition is the interface originally used for seeking in time-based media streams. IMediaSeeking is an interface intended to replace IMediaPosition in filter graphs that require seeking to units other than time, such as samples or fields, or that require more precise time-based seeking.

Renderers will use this class to implement IMediaPosition and IMediaSeeking from the filter; transform filters will use it to implement these two interfaces from the output pin. In both cases, the methods will be implemented by calls to the IMediaPosition or IMediaSeeking interface provided by the output pin of the connected upstream filter, effectively passing the position information through to the next filter.

Create a class derived from CPosPassThru, giving it the IPin pointer to your input pin, and delegate all IMediaPosition and IMediaSeeking methods to it. The class will find the output pin connected to the input pin, query this output pin for the IMediaPosition or IMediaSeeking interface, and respond appropriately.

Protected Data Members

m_Pin Pointer to the input pin of the filter.

Member Functions

CPosPassThru Constructs a CPosPassThru object.
ForceRefresh Releases any cached interfaces held on the upstream pin.

Overridable Member Functions

GetMediaTime Retrieves the starting and ending media times.

Implemented IMediaPosition Methods

CanSeekBackward Determines if the current position can be moved backward in the media stream.
CanSeekForward Determines if the current position can be moved forward in the media stream.
get_CurrentPosition Retrieves the current position in terms of the total length of the media stream.
get_Duration Retrieves the total duration of the media stream.
get_PrerollTime Retrieves the time before the start position that the filter graph will start any nonrandom access device rolling.
get_Rate Retrieves the playback rate, relative to normal playback of the media.
get_StopTime Retrieves the position within the media at which playback should stop.
put_CurrentPosition Sets the position within the media at which playback should start.
put_PrerollTime Sets the time before the start position that the filter graph will start any nonrandom access device rolling.
put_Rate Sets the playback rate, relative to normal playback of the media.
put_StopTime Sets the position within the media at which playback should stop.

Implemented IMediaSeeking Methods

CheckCapabilities Determines which capabilities exist on a media stream by applying seeking capability flags and checking the returned value.
ConvertTimeFormat Converts a time from one time format to another.
GetAvailable Retrieves the range of times in which seeking is efficient.
GetCapabilities Retrieves the seeking capabilities of the media stream.
GetCurrentPosition Retrieves the current position within the media stream.
GetDuration Retrieves the length of time that the media stream will play.
GetPositions Retrieves the current start and stop position settings.
GetPreroll Retrieves the preroll settings.
GetRate Retrieves the current rate.
GetStopPosition Retrieves the position at which the media stream stops.
GetTimeFormat Retrieves the current media time format.
IsFormatSupported Determines if a specified time format is supported.
IsUsingTimeFormat Determines if the time format being used in the call is the same as the one the interface currently uses.
QueryPreferredFormat Retrieves the preferred time format the interface will use.
SetPositions Sets current and stop positions and applies flags to both.
SetRate Sets a new playback rate.
SetTimeFormat Sets the time format, which determines the format of units used during seeking.

Implemented INonDelegatingUnknown Methods

NonDelegatingQueryInterface Retrieves a specified reference-counted interface.

CPosPassThru::CanSeekBackward

CPosPassThru Class

Determines if the current position can be moved backward in the media stream.

Syntax

HRESULT CanSeekBackward(
    LONG *pCanSeekBackward
);

Parameters

pCanSeekBackward
Pointer to a value indicating whether the current position can be moved backward in the media stream. Set to OATRUE if able to seek backward; otherwise set to OAFALSE.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::CanSeekBackward on the connected pin.

CPosPassThru::CanSeekForward

CPosPassThru Class

Determines if the current position can be moved forward in the media stream.

Syntax

HRESULT CanSeekForward(
    LONG *pCanSeekForward
);

Parameters

pCanSeekForward
Pointer to a value indicating whether the current position can be moved forward in the media stream. Set to OATRUE if able to seek forward; otherwise set to OAFALSE.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::CanSeekForward on the connected pin.

Remarks

This member function calls IMediaPosition::CanSeekForward on the upstream output pin connected to the peer input pin and returns the result.

CPosPassThru::CheckCapabilities

CPosPassThru Class

Determines which capabilities exist on a media stream by applying seeking capability flags and checking the returned value.

Syntax

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

Parameters

pCapabilities
Pointer to an AM_SEEKING_SEEKING_CAPABILITIES enumerator containing the seeking capabilities flags to apply. These flags 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 Value

Returns S_OK if all capabilities in pCapabilities are present, S_FALSE if some are present, or E_FAIL if none are present.

Remarks

This member function implements IMediaSeeking::CheckCapabilities, by calling the IMediaSeeking::CheckCapabilities method on the upstream output pin connected to the peer input pin. The pin that performs the seek operation will return whether the flags presented in the pCapabilities parameter are present. This returned value will then, in turn, propagate to calls made from CPosPassThru::CheckCapabilities member functions in intervening filters.

CPosPassThru::ConvertTimeFormat

CPosPassThru Class

Converts a time from one format to another.

Syntax

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

Parameters

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

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::ConvertTimeFormat on the connected pin.

Remarks

This member function implements the IMediaSeeking::ConvertTimeFormat method by calling this same method on the upstream filter's output pin.

CPosPassThru::CPosPassThru

CPosPassThru Class

Constructs a CPosPassThru object.

Syntax

CPosPassThru(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
    IPin *pPin
);

Parameters

pName
Pointer to the name of the object used in the CPosPassThru constructor for debugging purposes.
pUnk
Pointer to the owner of this object.
phr
Pointer to an HRESULT value for resulting information.
pPin
Pointer to the input pin for the filter.

Return Value

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.

CPosPassThru::ForceRefresh

CPosPassThru Class

Releases any cached interfaces on the upstream pin.

Syntax

HRESULT ForceRefresh(void);

Return Value

Returns S_OK.

Remarks

For efficiency, the CPosPassThru class can cache the IMediaPosition interface of the connected upstream output pin. This method releases any cached interface pointers and forces them to be obtained again via QueryInterface if needed.

Presently, this class does not cache the upstream IMediaPosition so this member function is not necessary. It is left in for future flexibility.

CPosPassThru::GetAvailable

CPosPassThru Class

Retrieves the range of times in which seeking is efficient.

Syntax

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

Parameters

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

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::GetAvailable on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetAvailable method by calling this same method on the upstream filter's output pin.

CPosPassThru::GetCapabilities

CPosPassThru Class

Retrieves the seeking capabilities of the media stream.

Syntax

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

Parameters

pCapabilities
Pointer to seeking capability flags, 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 Value

Returns the HRESULT value returned from calling IMediaSeeking::GetCapabilities on the connected pin.

Remarks

This member function implements IMediaSeeking::GetCapabilities by calling the IMediaSeeking::GetCapabilities method on the upstream output pin connected to the peer input pin. The pin that performs the seek operation will return the capabilities present in the pCapabilities parameter. These returned capabilities will then, in turn, propagate to calls made from CPosPassThru::GetCapabilities member functions in intervening filters.

CPosPassThru::GetCurrentPosition

CPosPassThru Class

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

Syntax

HRESULT GetCurrentPosition(
    LONGLONG *pCurrent
);

Parameters

pCurrent
Pointer to the current position in current time format units.

Return Value

Returns NOERROR if successful. Otherwise, returns the HRESULT value returned from calling IMediaSeeking::GetCurrentPosition on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetCurrentPosition interface. It calls the CPosPassThru::GetMediaTime virtual member function, which you should override and implement in your derived class to return the current position. If this fails (which it does by default), the IMediaSeeking::GetCurrentPosition on the upstream filter's output pin is called.

CPosPassThru::get_CurrentPosition

CPosPassThru Class

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

Syntax

HRESULT get_CurrentPosition(
    REFTIME *pllTime
);

Parameters

pllTime
Pointer to the returned start time as a double value, in seconds.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::get_CurrentPosition on the connected pin.

Remarks

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

CPosPassThru::GetDuration

CPosPassThru Class

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

Syntax

HRESULT GetDuration(
    LONGLONG *pDuration
);

Parameters

pDuration
Pointer to the returned length of the media stream.

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::GetDuration on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetDuration method by calling this same method on the upstream filter's output pin.

CPosPassThru::get_Duration

CPosPassThru Class

Retrieves the total duration of the media stream.

Syntax

HRESULT get_Duration(
    REFTIME *plength
);

Parameters

plength
Pointer to the returned length of the media stream.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::get_Duration on the connected pin.

Remarks

The duration assumes normal playback speed, and it is therefore unaffected by the rate.

CPosPassThru::GetMediaTime

CPosPassThru Class

Retrieves the starting and ending media times.

Syntax

virtual HRESULT GetMediaTime(
    LONGLONG *pStartTime,
    LONGLONG *pEndTime
);

Parameters

pStartTime
Pointer to the returned starting media time.
pEndTime
Pointer to the returned ending media time.

Return Value

Returns an HRESULT value (E_FAIL by default).

Remarks

Override this virtual member function to return the current sample's media time. This represents the current position in terms of media time (for example, frame 20 of a total 130 frames).

CPosPassThru::GetPositions

CPosPassThru Class

Returns the current and stop position settings.

Syntax

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

Parameters

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

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::GetPositions on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetPositions method by calling this same method on the upstream filter's output pin. It allows the retrieval of several values with only one call.

CPosPassThru::GetPreroll

CPosPassThru Class

Retrieves the preroll settings.

Syntax

HRESULT GetPreroll(
    LONGLONG *pllPreroll
);

Parameters

pllPreroll
Pointer to the returned preroll time.

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::GetPreroll on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetPreroll method by calling this same method on the upstream filter's output pin.

CPosPassThru::get_PrerollTime

CPosPassThru Class

Retrieves the time prior to the start position that devices should start rolling.

Syntax

HRESULT get_PrerollTime(
    REFTIME *pllTime
);

Parameters

pllTime
Pointer to the returned preroll time as a double value, in seconds.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::get_PrerollTime on the connected pin.

Remarks

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

CPosPassThru::GetRate

CPosPassThru Class

Retrieves the current rate.

Syntax

HRESULT GetRate(
    double *pdRate
);

Parameters

pdRate
Pointer to the current rate, where 1 is the normal rate.

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::GetRate on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetRate method by calling this same method on the upstream filter's output pin.

CPosPassThru::get_Rate

CPosPassThru Class

Retrieves the rate of playback relative to normal playback speed.

Syntax

HRESULT get_Rate(
    double *pdRate
);

Parameters

pdRate
Pointer to the returned rate.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::get_Rate on the connected pin.

Remarks

A rate of 1.0 indicates normal playback speed. A rate of 0.5 indicates half speed. A rate of –1.0 indicates normal speed in reverse.

CPosPassThru::GetStopPosition

CPosPassThru Class

Retrieves the position at which the media stream stops.

Syntax

HRESULT GetStopPosition(
    LONGLONG *pStop
);

Parameters

pStop
Pointer to the returned stop time.

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::GetStopPosition on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetStopPosition method by calling this same method on the upstream filter's output pin. 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.

CPosPassThru::get_StopTime

CPosPassThru Class

Retrieves the time at which the media stream stops.

Syntax

HRESULT get_StopTime(
    REFTIME *pllTime
);

Parameters

pllTime
Returned stop time as a double value, in seconds.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::get_StopTime on the connected pin.

Remarks

The stop time is a position 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.

CPosPassThru::GetTimeFormat

CPosPassThru Class

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

Syntax

HRESULT GetTimeFormat(
    const GUID *pFormat
);

Parameters

pFormat
Pointer to the media time format currently supported by this interface.

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::GetTimeFormat on the connected pin.

Remarks

This member function implements the IMediaSeeking::GetTimeFormat method by calling this same method on the upstream filter's output pin.

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

CPosPassThru::IsFormatSupported

CPosPassThru Class

Determines if a specified time format is supported.

Syntax

HRESULT IsFormatSupported(
    const GUID *pFormat
);

Parameters

pFormat
Pointer to the time format to compare.

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::IsFormatSupported on the connected pin.

Remarks

This member function implements the IMediaSeeking::IsFormatSupported method. For a list of valid time formats, see that method.

CPosPassThru::IsUsingTimeFormat

CPosPassThru Class

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
Pointer to the time format to check.

Return Value

Returns S_OK if pFormat is the current time format; otherwise returns S_FALSE.

Remarks

This member function implements the IMediaSeeking::IsUsingTimeFormat method by calling this same method on the upstream filter's output pin. This can be used in place of IMediaSeeking::GetTimeFormat to save copying the GUID.

CPosPassThru::NonDelegatingQueryInterface

CPosPassThru Class

Retrieves a specified reference-counted interface.

Syntax

HRESULT NonDelegatingQueryInterface(
    REFIID riid,
    void **ppv
);

Parameters

riid
Reference identifier.
ppv
Address of a pointer to the interface.

Return Value

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This function returns pointers to the IMediaPosition, IMediaSeeking, and IUnknown interfaces by default. Override this function to publish any additional interfaces implemented by the derived class.

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method.

CPosPassThru::put_CurrentPosition

CPosPassThru Class

Sets the time that the media stream begins.

Syntax

HRESULT put_CurrentPosition(
    REFTIME llTime
);

Parameters

llTime
Start time expressed as a double value, in seconds.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::put_CurrentPosition on the connected pin.

Remarks

The start time is a position between zero and the duration of the media at which playback should begin when the next run command is issued. Do not call this method when the filter graph is running, only when it is paused or stopped.

Setting the start position when paused causes playback to resume from the new start position when the run command is issued.

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

CPosPassThru::put_PrerollTime

CPosPassThru Class

Sets the time prior to the start position that devices should start rolling.

Syntax

HRESULT put_PrerollTime(
    REFTIME llTime
);

Parameters

llTime
Preroll time to be set.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::put_PrerollTime.

Remarks

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

Note that while this member function passes the call upstream, the IMediaPosition::put_PrerollTime method is not implemented on any Microsoft source filter.

CPosPassThru::put_Rate

CPosPassThru Class

Sets the rate of playback relative to normal speed.

Syntax

HRESULT put_Rate(
    double dRate
);

Parameters

dRate
Rate to set.

Return Value

Returns E_INVALIDARG if dRate is zero. Otherwise, returns the HRESULT value returned from calling IMediaPosition::put_Rate on the connected pin.

Remarks

This property enables an application to speed up or slow down playback relative to the normal default playback speed. A rate of 1.0 indicates 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 frames.

Negative rates indicate reverse play. Not all media will support reverse play.

CPosPassThru::put_StopTime

CPosPassThru Class

Sets the time at which the media stream will stop.

Syntax

HRESULT put_StopTime(
    REFTIME llTime
);

Parameters

llTime
Stop time as a double value, in seconds.

Return Value

Returns the HRESULT value returned from calling IMediaPosition::put_StopTime on the connected pin.

Remarks

The stop time is a position 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.

CPosPassThru::QueryPreferredFormat

CPosPassThru Class

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

Syntax

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

Parameters

pFormat
Pointer to the time format preferred by the interface.

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::QueryPreferredFormat on the connected pin.

Remarks

This member function implements the IMediaSeeking::QueryPreferredFormat method by calling this same method on the upstream filter's output pin.

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

CPosPassThru::SetPositions

CPosPassThru Class

Sets current and stop positions and applies flags to both.

Syntax

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

Parameters

pCurrent
Pointer to the start position if stopped, or position to continue from if paused.
dwCurrentFlags
When seeking, one of these flags must be set to indicate the type of seek. See the IMediaSeeking::SetPositions method for a description of these flags.
pStop
Pointer to the position in the stream at which to quit.
dwStopFlags
Stop position seeking options to be applied. These are the same as listed for dwCurrentFlags.

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::SetPositions on the connected pin.

Remarks

This member function implements the IMediaSeeking::SetPositions method by calling this same method on the upstream filter's output pin. It allows the retrieval of several values with only one call.

CPosPassThru::SetRate

CPosPassThru Class

Sets a new playback rate.

Syntax

HRESULT SetRate(
    double dRate
);

Parameters

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

Return Value

Returns E_INVALIDARG if dRate is zero. Otherwise, returns the HRESULT value returned from calling IMediaSeeking::SetRate on the connected pin.

Remarks

This member function implements the IMediaSeeking::SetRate method by calling this same method on the upstream filter's output pin. It is an error to set the rate to zero.

CPosPassThru::SetTimeFormat

CPosPassThru Class

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

Syntax

HRESULT SetTimeFormat(
    const GUID *pFormat
);

Parameters

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

Return Value

Returns the HRESULT value returned from calling IMediaSeeking::SetTimeFormat on the connected pin.

Remarks

This member function implements the IMediaSeeking::SetTimeFormat method by calling this same method on the upstream filter's output pin. For a list of time formats, see the IMediaSeeking::IsFormatSupported method.

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