IQueueCommand Interface

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.

This method is implemented by the filter graph manager to allow queuing of deferred commands.

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.

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.

IQueueCommand::InvokeAtPresentationTime

IQueueCommand Interface

Queues a method or property change for execution at a specified presentation time.

Syntax

HRESULT InvokeAtPresentationTime(

  IDeferredCommand *pCmd,

  REFTIME time,

  GUID *iid,

  long dispidMember,

  short wFlags,

  long cArgs,

  VARIANT *pDispParams,

  VARIANT *pvarResult,

  short *puArgErr

  );

Parameters

pCmd
[out] Pointer to the place to return an interface on the deferred command if it is successfully created.
time
[in] Time at which to invoke the command.
iid
[in] Pointer to the interface to be called.
dispidMember
[in] Method or property to call on the interface.
wFlags
[in] Method or property flag.
cArgs
[in] Number of arguments in pDispParams.
pDispParams
[in] Pointer to parameters to this method.
pvarResult
[in, out] Pointer to the return value.
puArgErr
[out] Pointer to the index to the arguments in error.

Return Value

Returns an HRESULT value.

IQueueCommand::InvokeAtStreamTime

IQueueCommand Interface

Queues a method or property change for execution at a specified stream time (that is, presentation time relative to the current stream time offset).

Syntax

HRESULT InvokeAtStreamTime(

  IDeferredCommand **pCmd,

  REFTIME time,

  GUID *iid,

  long dispidMember,

  short wFlags,

  long cArgs,

  VARIANT *pDispParams,

  VARIANT *pvarResult,

  short *puArgErr

  );

Parameters

pCmd
[out] Address of a pointer to the place to return an interface on the deferred command if it is successfully created.
time
[in] Time at which to invoke the command.
iid
[in] Pointer to the interface to be called.
dispidMember
[in] Method or property to call on the interface.
wFlags
[in] Method or property flag.
cArgs
[in] Number of arguments in pDispParams.
pDispParams
[in] Pointer to parameters to this method.
pvarResult
[in, out] Pointer to the return value of the called method.
puArgErr
[out] Pointer to the index to the arguments in error.

Return Value

Returns an HRESULT value.

Remarks

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.