IDeferredCommand Interface
The deferred command mechanism enables 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.
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.
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 Retrieves 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 Retrieves 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
Cancels a previously queued IQueueCommand::InvokeAtStreamTime or IQueueCommand::InvokeAtPresentationTime request.
Syntax
HRESULT Cancel(void);
Return Value
Returns an HRESULT value.
IDeferredCommand::Confidence
Retrieves a confidence value on a scale of 0 to 100 that describes the probability that the deferred command will be run on time.
Syntax
HRESULT Confidence(
LONG *pConfidence
);
Parameters
- pConfidence
- Pointer to the confidence level.
Return Value
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
Retrieves the return value from the invoked command.
Syntax
HRESULT GetHResult(
HRESULT *phrResult
);
Parameters
- phrResult
- Pointer to the retrieved HRESULT value.
Return Value
Returns S_OK if successful. Also, if successful, the phrResult parameter is set to the result of the deferred command.
IDeferredCommand::Postpone
Specifies a new presentation time for a previously queued command.
Syntax
HRESULT Postpone(
REFTIME newtime
);
Parameters
- newtime
- New presentation time.
Return Value
Returns S_OK if the new presentation time was successfully inserted. If the time specified in newtime has already passed, returns VFW_E_TIME_ALREADY_PASSED.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.