Microsoft DirectX 8.0

CPosPassThru Class

CPosPassThru class hierarchy

Handles seek commands for filters with one input pin that do not perform seeking on their own.

Declaration: Ctlutil.h

This helper class implements the IMediaPosition and IMediaSeeking interfaces for filters that pass seek commands upstream. When the filter graph manager receives a seek command from an application, it delivers the command to the renderer filters in the graph. The command is then passed upstream through each filter's output pin, until it reaches a filter that can execute the command (if any). Typically, seeking is implemented on source filters or parser filters.

The CPosPassThru class holds a pointer to the filter's input pin. It passes seek commands to the connected output pin on the upstream filter, as shown in the following diagram.

CPosPassThru

Use the CPosPassThru class for transform filters, and the derived CRendererPosPassThru class for renderer filters.

To use this class in your filter, create an instance of the class and specify the filter's input pin in the CPosPassThru constructor method. Then delegate all IMediaPosition and IMediaSeeking calls to the CPosPassThru object.

The simplest way to delegate seeking commands is to expose the CPosPassThru object's IMediaPosition and IMediaSeeking interfaces. When your filter or pin is queried for one of these interfaces, return a pointer to the CPosPassThru implementation of the interface. The following code shows how do this. It is adapted from the CTransformOutputPin class. The CreatePosPassThru function is a helper function that creates the CPosPassThru object:

// The following member variables are assumed:
// CPosPassThru *m_pPos;
// IPin *m_pPin;

if (riid == IID_IMediaPosition || riid == IID_IMediaSeeking) 
{
    if (m_pPos == NULL) 
    {
        HRESULT hr;
        hr = CreatePosPassThru(GetOwner(), FALSE, m_pPin, &m_pPos);
        if (FAILED(hr))
            return hr;
    }
    return m_pPosition->QueryInterface(riid, ppv);
} 
else 
{
    // Return pointers to the other interfaces on this pin.
}

Except where noted, all IMediaPosition and IMediaSeeking methods in this class call the corresponding method on the connected pin and return the result.

Public Methods
CPosPassThruConstructor method.
ForceRefreshObsolete.
GetMediaTimeRetrieves the time stamps on the current sample. Virtual.
IMediaPosition Methods
get_DurationRetrieves the duration of the stream.
put_CurrentPositionSets 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.
get_RateRetrieves the playback rate.
put_RateSets the playback rate.
get_CurrentPositionRetrieves the current position, relative to the total duration of the stream.
CanSeekForwardDetermines whether the stream can be seeked backward.
CanSeekBackwardDetermines whether the stream can be seeked forward.
IMediaSeeking Methods
CheckCapabilitiesQueries whether a stream has specified seeking capabilities.
ConvertTimeFormatConverts from one time format to another.
GetAvailableRetrieves the range of times in which seeking is efficient.
GetCapabilitiesRetrieves all the seeking capabilities of the stream.
GetCurrentPositionRetrieves the current position, relative to the total duration of the stream.
GetDurationRetrieves the duration of the stream.
GetPositionsRetrieves the current position and the stop position, relative to the total duration of the stream.
GetPrerollRetrieves the amount of data that will be queued before the start position.
GetRateRetrieves the playback rate.
GetStopPositionRetrieves the time at which the playback will stop, relative to the duration of the stream.
GetTimeFormatRetrieves the current time format.
IsFormatSupportedDetermines whether a specified time format is supported.
IsUsingTimeFormatDetermines whether a specified time format is the format currently in use.
QueryPreferredFormatRetrieves the preferred time format for the stream.
SetPositionsSets the current position and the stop position.
SetRateSets the playback rate.
SetTimeFormatSets the time format.
Helper Functions
CreatePosPassThruCreates a CPosPassThru or CRendererPosPassThru object.

CPosPassThru::CanSeekBackward

CPosPassThru Class

Determines whether the stream can be seeked backward. Implements the IMediaPosition::CanSeekBackward method.

Syntax

HRESULT CanSeekBackward(
    LONG *pCanSeekBackward
);

Parameters

pCanSeekBackward
Pointer to a variable that receives the value OATRUE if the filter can seek backward, or OAFALSE otherwise.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::CanSeekForward

CPosPassThru Class

Determines whether the stream can be seeked forward. Implements the IMediaPosition::CanSeekForward method.

Syntax

HRESULT CanSeekForward(
    LONG *pCanSeekForward
);

Parameters

pCanSeekForward
Pointer to a variable that receives the value OATRUE if the filter can seek forward, or OAFALSE otherwise.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::CheckCapabilities

CPosPassThru Class

Queries whether a stream has specified seeking capabilities. Implements the IMediaSeeking::CheckCapabilities method.

Syntax

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

Parameters

pCapabilities
Pointer to a bitwise combination of one or more AM_SEEKING_SEEKING_CAPABILITIES attributes. When the method returns, the value indicates which of those attributes are available.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::ConvertTimeFormat

CPosPassThru Class

Converts from one time format to another. Implements the IMediaSeeking::ConvertTimeFormat method.

Syntax

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

Parameters

pTarget
Pointer to a variable that receives the converted time.
pTargetFormat
Pointer to the time format GUID of the target format. If NULL, the current format is used.
Source
Time value to be converted.
pSourceFormat
Pointer to the time format GUID of the format to convert. If NULL, the current format is used.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::CPosPassThru

CPosPassThru Class

Constructor method.

Syntax

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

Parameters

pName
Pointer to the name of the object, for debugging purposes. Allocate this parameter in static memory.
pUnk
Pointer to the owner of this object. If the object is aggregated, pass a pointer to the aggregating object's IUnknown interface. Otherwise, set this parameter to NULL.
phr
Pointer to an HRESULT value. Ignored.
pPin
Pointer to the IPin interface of the filter's input pin.

CPosPassThru::ForceRefresh

CPosPassThru Class

Obsolete.

Syntax

HRESULT ForceRefresh(void);

Return Value

Returns S_OK.

Remarks

Originally this class was designed to cache pointers to the connected pin's IMediaPosition and IMediaSeeking interfaces. The ForceRefresh method released those interfaces.

As currently implemented, this class does not cache those interfaces. For compatibility, the ForceRefresh method is still included, but it returns S_OK without doing anything.

CPosPassThru::GetAvailable

CPosPassThru Class

Retrieves the range of times in which seeking is efficient. Implements the IMediaSeeking::GetAvailable method.

Syntax

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

Parameters

pEarliest
Pointer to a variable that receives the earliest time for efficient seeking.
pLatest
Pointer to a variable that receives the latest time for efficient seeking.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::GetCapabilities

CPosPassThru Class

Retrieves all the seeking capabilities of the stream. Implements the IMediaSeeking::GetCapabilities method.

Syntax

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

Parameters

pCapabilities
Pointer to a variable that receives a bitwise combination of AM_SEEKING_SEEKING_CAPABILITIES flags.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::GetCurrentPosition

CPosPassThru Class

Retrieves the current position, relative to the total duration of the stream. Implements the IMediaSeeking::GetCurrentPosition method.

Syntax

HRESULT GetCurrentPosition(
    LONGLONG *pCurrent
);

Parameters

pCurrent
Pointer to a variable that receives the current position, in units of the current time format.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
E_NOTIMPLMethod is not supported.
E_POINTERNULL pointer argument.

Remarks

This method calls the CPosPassThru::GetMediaTime method to retrieve the most recent position. If GetMediaTime fails, the method calls IMediaSeeking::GetCurrentPosition on the connected pin.

The GetMediaTime method fails by default in the base class. If your filter caches the current position, override GetMediaTime to return the cached value.

CPosPassThru::get_CurrentPosition

CPosPassThru Class

Retrieves the current position, relative to the total duration of the stream. Implements the IMediaPosition::get_CurrentPosition method.

Syntax

HRESULT get_CurrentPosition(
    REFTIME *pllTime
);

Parameters

pllTime
Pointer to a variable that receives the current position, in seconds.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::GetDuration

CPosPassThru Class

Retrieves the duration of the stream. Implements the IMediaSeeking::GetDuration method.

Syntax

HRESULT GetDuration(
    LONGLONG *pDuration
);

Parameters

pDuration
Pointer to a variable that receives the duration, in units of the current time format.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::get_Duration

CPosPassThru Class

Retrieves the duration of the stream. Implements the IMediaPosition::get_Duration method.

Syntax

HRESULT get_Duration(
    REFTIME *plength
);

Parameters

plength
Pointer to a variable that receives the total stream length, in seconds.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::GetMediaTime

CPosPassThru Class

Retrieves the time stamps on the current sample.

Syntax

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

Parameters

pStartTime
Pointer to a variable that receives the start time, in units of the current time format.
pEndTime
Pointer to a variable that receives the end time, in units of the current time format.

Return Value

Returns E_FAIL.

Remarks

Override this method if your filter caches the time stamps on the samples it receives.

CPosPassThru::GetPositions

CPosPassThru Class

Retrieves the current position and the stop position, relative to the total duration of the stream. Implements the IMediaSeeking::GetPositions method.

Syntax

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

Parameters

pCurrent
Pointer to a variable that receives the current position, in units of the current time format.
pStop
Pointer to a variable that receives the stop position, in units of the current time format.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::GetPreroll

CPosPassThru Class

Retrieves the amount of data that will be queued before the start position. Implements the IMediaSeeking::GetPreroll method.

Syntax

HRESULT GetPreroll(
    LONGLONG *pllPreroll
);

Parameters

pllPreroll
Pointer to a variable that receives the preroll time, in units of the current time format.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::get_PrerollTime

CPosPassThru Class

Retrieves the amount of data that will be queued before the start position. Implements the IMediaPosition::get_PrerollTime method.

Syntax

HRESULT get_PrerollTime(
    REFTIME *pllTime
);

Parameters

pllTime
Pointer to a variable that receives the preroll time, in seconds.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::GetRate

CPosPassThru Class

Retrieves the playback rate. Implements the IMediaSeeking::GetRate method.

Syntax

HRESULT GetRate(
    double *pdRate
);

Parameters

pdRate
Pointer to a variable that receives the playback rate.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::get_Rate

CPosPassThru Class

Retrieves the playback rate. Implements the IMediaPosition::get_Rate method.

Syntax

HRESULT get_Rate(
    double *pdRate
);

Parameters

pdRate
Pointer to a variable that receives the playback rate.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::GetStopPosition

CPosPassThru Class

Retrieves the time at which the playback will stop, relative to the duration of the stream. Implements the IMediaSeeking::GetStopPosition method.

Syntax

HRESULT GetStopPosition(
    LONGLONG *pStop
);

Parameters

pStop
Pointer to a variable that receives the stop time, in units of the current time format.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::get_StopTime

CPosPassThru Class

Retrieves the time at which the playback will stop, relative to the duration of the stream. Implements the IMediaPosition::get_StopTime method.

Syntax

HRESULT get_StopTime(
    REFTIME *pllTime
);

Parameters

pllTime
Pointer to a variable that receives the stop time, in seconds.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::GetTimeFormat

CPosPassThru Class

Retrieves the current time format. Implements the IMediaSeeking::GetTimeFormat method.

Syntax

HRESULT GetTimeFormat(
    const GUID *pFormat
);

Parameters

pFormat
Pointer to a variable that receives a time format GUID.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::IsFormatSupported

CPosPassThru Class

Determines whether a specified time format is supported. Implements the IMediaSeeking::IsFormatSupported method.

Syntax

HRESULT IsFormatSupported(
    const GUID *pFormat
);

Parameters

pFormat
Pointer to a time format GUID.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::IsUsingTimeFormat

CPosPassThru Class

Determines whether a specified time format is the format currently in use. Implements the IMediaSeeking::IsUsingTimeFormat method.

Syntax

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

Parameters

pFormat
Pointer to a time format GUID.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::put_CurrentPosition

CPosPassThru Class

Sets the current position, relative to the total duration of the stream. Implements the IMediaPosition::put_CurrentPosition method.

Syntax

HRESULT put_CurrentPosition(
    REFTIME llTime
);

Parameters

llTime
New position, in seconds.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::put_PrerollTime

CPosPassThru Class

Sets the amount of data that will be queued before the start position. Implements the IMediaPosition::put_PrerollTime method.

Syntax

HRESULT put_PrerollTime(
    REFTIME llTime
);

Parameters

llTime
Preroll time, in seconds.

Return Value

Returns the HRESULT value from the connected pin.

Remarks

Although this member function passes the call upstream, the IMediaPosition::put_PrerollTime method is not implemented on any DirectShow source filters.

CPosPassThru::put_Rate

CPosPassThru Class

Sets the playback rate. Implements the IMediaPosition::put_Rate method.

Syntax

HRESULT put_Rate(
    double dRate
);

Parameters

dRate
Playback rate. Must not be zero.

Return Value

Returns E_INVALIDARG if dRate is zero. Otherwise, returns the HRESULT value from the connected pin.

Remarks

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

CPosPassThru::put_StopTime

CPosPassThru Class

Sets the time at which the playback will stop, relative to the duration of the stream. Implements the IMediaPosition::put_StopTime method.

Syntax

HRESULT put_StopTime(
    REFTIME llTime
);

Parameters

llTime
Stop time as a double value, in seconds.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::QueryPreferredFormat

CPosPassThru Class

Retrieves the preferred time format for the stream. Implements the IMediaSeeking::QueryPreferredFormat method.

Syntax

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

Parameters

pFormat
Pointer to a variable that receives a time format GUID.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::SetPositions

CPosPassThru Class

Sets the current position and the stop position. Implements the IMediaSeeking::SetPositions method.

Syntax

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

Parameters

pCurrent
Pointer to a variable that specifies the current position, in units of the current time format.
dwCurrentFlags
Bitwise combination of flags. See IMediaSeeking::SetPositions for more information.
pStop
Pointer to a variable that specifies the stop time, in units of the current time format.
dwStopFlags
Bitwise combination of flags. See IMediaSeeking::SetPositions for more information.

Return Value

Returns the HRESULT value from the connected pin.

CPosPassThru::SetRate

CPosPassThru Class

Sets the playback rate. Implements the IMediaSeeking::SetRate method.

Syntax

HRESULT SetRate(
    double dRate
);

Parameters

dRate
Playback rate. Must not be zero.

Return Value

Returns E_INVALIDARG if dRate is zero. Otherwise, returns the HRESULT value from the connected pin.

CPosPassThru::SetTimeFormat

CPosPassThru Class

Sets the time format. Implements the IMediaSeeking::SetTimeFormat method.

Syntax

HRESULT SetTimeFormat(
    const GUID *pFormat
);

Parameters

pFormat
Pointer to a time format GUID.

Return Value

Returns the HRESULT value from the connected pin.

CreatePosPassThru Function

CPosPassThru Class

Creates a CPosPassThru or CRendererPosPassThru object.

Syntax

STDAPI CreatePosPassThru(
    LPUNKNOWN pAgg,
    BOOL bRenderer,
    IPin *pPin,
    IUnknown **ppPassThru
);

Parameters

pAgg
Pointer to the owner of this object. If the object is aggregated, pass a pointer to the aggregating object's IUnknown interface. Otherwise, set this parameter to NULL.
bRenderer
Boolean value that specifies whether the filter is a renderer. Use the value TRUE if the filter is a renderer, or FALSE otherwise.
pPin
Pointer to the IPin interface on the filter's input pin.
ppPassThru
Address of a variable that receives a pointer to the object's IUnknown interface.

Return Value

Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.

Remarks

If the value of bSupportRendering is TRUE, this method creates an instance of the CRendererPosPassThru class. Otherwise, it creates an instance of the CPosPassThru class. For more information, see CSeekingPassThru.