IMediaControl::GetState
A version of this page is also available for
4/8/2010
This method retrieves the state of the filter graph.
Syntax
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 Value
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 enumeration).
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
| Windows Embedded CE | Windows CE 2.12 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
| Note | Microsoft DirectShow applications and DirectShow filters have different include file and Library requirements For more information, see Setting Up the Build Environment, Version 2.12 requires DXPAK 1.0 or later |