IMediaControl::GetState

  • Article

This method retrieves the state of the filter graph.

HRESULT GetState(
  LONG msTimeout,
  OAFilterState* pfs
);

Parameters

  • msTimeout
    [in] Duration of the time-out, in milliseconds.
  • pfs
    [out] Holds the returned state of the filter graph.

Return Values

Returns VFW_S_STATE_INTERMEDIATE if the state transition is not complete, or S_OK if it completed successfully. It can also return VFW_S_CANT_CUE if the state is paused, but the source filter does not push data during the paused state (only pushes during the run state). An example of this is a live video capture filter.

Remarks

Not all state transitions are synchronous. For example, even though the IMediaControl::Pause method returns immediately, the filter graph typically does not complete the transition into paused mode until data is ready at the renderer. This method will not return S_OK until the state transition has been completed.

If you specify a nonzero time-out, the method waits up to that number of milliseconds for the filter graph to leave the intermediate state. If the time-out expires before the state transition is complete, the return code will be VFW_S_STATE_INTERMEDIATE, and the returned state will be the state into which the graph is transitioning (either the State_Stopped, State_Paused, or State_Running member of the FILTER_STATE structure).

This method will return 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. Threads cannot process messages while waiting in GetState. If you call GetState from the thread that processes Windows® messages, specify only small wait times on the call in order to remain responsive to user input. This is most important when streaming data from a source such as the Internet, because state transitions can take significantly more time to complete.

If you want to pause a filter graph completely before stopping it, call IMediaControl::Pause, and then IMediaControl::StopWhenReady (instead of calling GetState with an INFINITE time-out, and then IMediaControl::Stop).

Although pfs is declared as a pointer to an OAFilterState value in IMediaControl::GetState, DirectShow implements it as a pointer to a FILTER_STATE value in CBaseFilter::GetState and its derivatives. Because both OAFilterState and FILTER_STATE resolve to LONG values, this does not cause an error.

Requirements

DirectShow applications and DirectShow filters have different include file and link library requirements. See Setting Up the Build Environment for more information.

OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later.

See Also

IMediaControl Interface

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.