Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
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_INTERMEDIATEif 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::Pausemethod 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_Runningmember of the FILTER_STATEenumeration).

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 GetStatefrom 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 GetStatewith an INFINITE time-out, and then IMediaControl::Stop).

Although pfsis declared as a pointer to an OAFilterState value in IMediaControl::GetState, DirectShow implements it as a pointer to a FILTER_STATEvalue in CBaseFilter::GetStateand its derivatives. Because both OAFilterState and FILTER_STATEresolve to LONGvalues, 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

See Also