 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. |
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_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_Runningmembers of the FILTER_STATEstructure).
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. Since both OAFilterState and FILTER_STATEresolve to LONGvalues, this does not cause an error.