Index
|
|
|
|
|
| |||
| |||
IDeferredCommand Interface
The deferred command mechanism allows filters themselves to handle deferred commands. Where they do not, the filter graph manager queues the command until the requested time and then calls the method on the filter (this would result in coarse rather than accurate synchronization). Note that a filter that does handle deferred commands must make them apply to data appearing at that time. Thus a contrast filter asked to change the contrast at time x must ensure that it applies the change when processing data time-stamped to be rendered at time x; these samples will be processed by the filter somewhat before time x.
The IQueueCommand interface provides two methods, InvokeAtStreamTime, which queues commands at stream time, and InvokeAtPresentationTime, which queues commands at presentation time. Both return an IDeferredCommand interface to the queued command, by which the application can cancel the command, set a new presentation time for it, or get back an estimate of the likelihood of the filter graph manager being able to run the command on time (implementation of this last method is likely to be highly simplistic in the first release of Microsoft® DirectShow™).
Both the queue and the application will hold a reference count on the object (represented to the application by the IDeferredCommand interface), and the object will not be destroyed until both are released. Similarly, calling Release on the IDeferredCommand interface is not sufficient to cancel the command because the queue also holds a reference count.
When to Implement
This method is implemented by the filter graph manager to allow deferred processing of commands. It is implemented through a plug-in distributor to pass deferred commands from the application to the filters (through the plug-in distributor for the command that has been queued). You can implement it within your filter if your filter supports queued commands; in this case, applications will need to obtain an IQueueCommand interface directly from your filter. You can use the CDeferredCommand class to help implement this interface.
When to Use
Applications can use this interface to cancel, postpone, get return values from, or determine a confidence level for commands that have been queued for deferred execution by using the IQueueCommand interface.
Methods in Vtable Order
IUnknown methods Description QueryInterface Returns pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count.
IDeferredCommand methods Description Cancel Cancels a previously queued IQueueCommand::InvokeAtStreamTime or IQueueCommand::InvokeAtPresentationTime request. Confidence Returns a confidence value that describes the probability of the deferred command being run on time. Postpone Specifies a new invocation time for a previously queued command. GetHResult Retrieves the return value from the invoked command. IDeferredCommand Interface
IDeferredCommand::CancelCancels a previously queued IQueueCommand::InvokeAtStreamTime or IQueueCommand::InvokeAtPresentationTime request.
HRESULT Cancel( );
Return Values
Returns an HRESULT value.
IDeferredCommand Interface
IDeferredCommand::ConfidenceReturns a confidence value on a scale of 0 to 100 that describes the probability that the deferred command will be run on time.
HRESULT Confidence(
LONG *pConfidence
);Parameters
- pConfidence
- Confidence level.
Return Values
Returns an HRESULT value.
Remarks
Higher confidence values indicate a greater probability of timely execution. For example, a command queued at a presentation time that has already passed will return a value of 0. A value of 100 would indicate, with absolute certainty, that the command can be run on time. Commands that are not directly supported by the filter but are queued by the filter graph manager will return a lower confidence value than commands queued directly by the filters that run them. Commands that are queued with times too close to other commands are likely to return lower confidence values. The initial implementation of this method relies mostly on the reporting of the individual filter commands rather than an attempt to estimate resource availability on a filter graph-wide basis.
IDeferredCommand Interface
IDeferredCommand::GetHResultRetrieves the return value from the invoked command.
HRESULT GetHResult(
HRESULT* phrResult
);Parameters
- phrResult
- Retrieved HRESULT value.
IDeferredCommand Interface
IDeferredCommand::PostponeSpecifies a new presentation time for a previously queued command.
HRESULT Postpone(
REFTIME newtime
);Parameters
- newtime
- New presentation time.
Return Values
Return value is S_OK if completed. Also, if completed, the phrResult parameter is set to the result of the deferred command.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.