IMediaControl::GetState

  • Article
 
Microsoft DirectShow 9.0

IMediaControl::GetState

The GetState method retrieves the state of the filter graph—paused, running, or stopped.

State transitions are not necessarily synchronous. Therefore, when you call this method, the filter graph might be in transition to a new state. In that case, the method blocks until the transition completes or until the specified time-out elapses.

Syntax

  HRESULT GetState(
  LONG msTimeout,
  OAFilterState *pfs
);

Parameters

msTimeout

[in] Duration of the time-out, in milliseconds, or INFINITE to specify an infinite time-out.

pfs

[out] Receives a member of the FILTER_STATE enumeration.

Return Values

Returns an HRESULT value. Possible values include the following.

Return code Description
S_OK Success.
VFW_S_STATE_INTERMEDIATE The filter graph is still in transition to the indicated state.
VFW_S_CANT_CUE The filter graph is paused, but cannot cue data.
E_FAIL Failure.

Remarks

Applications can use this method to determine whether playback has started after a call to IMediaControl::Run. Generally, applications should have their own mechanism for tracking which state they have put the filter graph into. Applications typically use the current state to determine which user interface controls are enabled or disabled. For example, once the graph goes into the running state, the application might disable a "Play" button and enable "Stop" and "Pause" buttons.

If the filter graph is in a transition to a new state, the returned state is the new state, not the previous state.

This method returns an error if there is a call on another thread to change the state while this method is blocked.

Avoid specifying a time-out of INFINITE, because threads cannot process messages while waiting in GetState. If you call GetState from the thread that processes Windows messages, specify small wait times on the call in order to remain responsive to user input. This is especially important when the source is streaming over a network or from the Internet because state transitions in these environments can take significantly more time to complete.

The pfs parameter is typed as an OAFilterState pointer but receives a member of the FILTER_STATE enumeration. You can cast the variable as follows:

FILTER_STATE fs;
hr = pControl->GetState(msTimeOut, (OAFilterState*)&fs);

For more information about filter graph states, see Filter States.

Requirements

Header: Declared in Control.h; include Dshow.h.

Library: Use Strmiids.lib.

See Also