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] Pointer to a variable that receives a member of the FILTER_STATE enumeration.

Return Values

Returns an HRESULT value. Possible values include the following.

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.

For more information about filter graph states, see Data Flow in the Filter Graph.

See Also

• Error and Success Codes
• IMediaControl Interface