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::Cancel

IDeferredCommand Interface

Cancels a previously queued IQueueCommand::InvokeAtStreamTime or IQueueCommand::InvokeAtPresentationTime request.

HRESULT Cancel( );

Return Values

Returns an HRESULT value.

---

IDeferredCommand::Confidence

IDeferredCommand Interface

Returns 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::GetHResult

IDeferredCommand Interface

Retrieves the return value from the invoked command.

HRESULT GetHResult(
  HRESULT* phrResult
  );

Parameters

phrResult

Retrieved HRESULT value.

---

IDeferredCommand::Postpone

IDeferredCommand Interface

Specifies 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.

Top of Page