IMediaControl::GetState method (control.h)

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(
  [in]  LONG          msTimeout,
  [out] OAFilterState *pfs
);

Parameters

[in] msTimeout

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

[out] pfs

Receives a member of the FILTER_STATE enumeration.

Return value

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 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

   
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header control.h (include Dshow.h)
Library Strmiids.lib

See also

Error and Success Codes

IMediaControl Interface