The IQueueCommand interface provides a way to defer commands and property changes. The deferred command mechanism allows filters themselves to handle deferred commands. When 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.
Both presentation time and stream time commands will run once, and then be removed from the queue. 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 IUnknown::Release on the IDeferredCommand interface is not sufficient to cancel the command, because the queue also holds a reference count.
Rather than add optional stream time and presentation time constraints to every method and property on every control interface, the application uses IDispatch to provide a single interface where these time parameters can be specified. IQueueCommand provides InvokeAtStreamTime and InvokeAtPresentationTime methods that are similar in style to the IDispatch::Invoke method.
Filters can implement IQueueCommand themselves. In this case, they parse the command and queue it for action when the relevant samples arrive or when the reference clock reaches the correct point, as appropriate. For filters that do not support this, the filter graph manager will run the command when the reference clock reaches the specified time, regardless of the samples being processed at the filter.
When to Implement
This method is implemented by the filter graph manager to allow queuing of deferred commands.
When to Use
Applications can use this interface, along with the IDeferredCommand interface, to queue commands for deferred processing.
Methods in Vtable Order
| IUnknown methods | Description |
| QueryInterface | Returns pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| IQueueCommand methods | Description |
| InvokeAtStreamTime | Queues a method or property change for execution at a specified stream time (that is, presentation time relative to the current stream time offset). |
| InvokeAtPresentationTime | Queues a method or property change for execution at a specified presentation time. |
Queues a method or property change for execution at a specified presentation time.
HRESULT InvokeAtPresentationTime(
IDeferredCommand * pCmd,
REFTIME time,
GUID* iid,
long dispidMember,
short wFlags,
long cArgs,
VARIANT *pDispParams,
VARIANT *pvarResult,
short *puArgErr
);
Returns an HRESULT value.
Queues a method or property change for execution at a specified stream time (that is, presentation time relative to the current stream time offset).
HRESULT InvokeAtStreamTime(
IDeferredCommand ** pCmd,
REFTIME time,
GUID *iid,
long dispidMember,
short wFlags,
long cArgs,
VARIANT *pDispParams,
VARIANT *pvarResult,
short *puArgErr
);
Returns an HRESULT value.
Run this command to affect the presentation that occurs after the specified stream time. The interface IID is an interface that can be obtained by calling IUnknown::QueryInterface on this same IQueueCommand interface.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.