CCmdQueue.New method

  • Article

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The New method initializes a command to be run and returns a new CDeferredCommand object.

Syntax

virtual HRESULT New(
   CDeferredCommand **ppCmd,
   LPUNKNOWN        pUnk,
   REFTIME          time,
   GUID             *iid,
   long             dispidMethod,
   short            wFlags,
   long             cArgs,
   VARIANT          *pDispParams,
   VARIANT          *pvarResult,
   short            *puArgErr,
   BOOL             bStream
);

Parameters

ppCmd

Address of a pointer to a CDeferredCommand object by which an application can cancel the command, set a new presentation time for it, or retrieve estimate information.

pUnk

Pointer to the object that will run the command.

time

Time at which to run the queued command or commands.

iid

Pointer to the globally unique identifier (GUID) of the interface to call.

dispidMethod

Method on the interface to be called.

wFlags

Flags describing the context of the call. This parameter supports the same flags as the IDispatch::Invoke method.

cArgs

Number of arguments passed.

pDispParams

Pointer to the list of variant types associated with the dispatch parameters.

pvarResult

Pointer to the list where results, if any, are to be returned.

puArgErr

Pointer to the index within the pDispParams parameter list where the last error occurred.

bStream

Value indicating whether the time parameter is a stream-time value (TRUE) or a presentation-time value (FALSE).

Return value

Returns S_OK if successful. Returns E_OUTOFMEMORY if ppCmd returns from creating the new CDeferredCommand object with a value of NULL. Otherwise, returns an HRESULT that indicates an error from attempting to create a new CDeferredCommand object. If there is an error, no object has been queued.

Remarks

The new CDeferredCommand object will be initialized with the parameters and will be added to the queue during construction. This method is similar to the IDispatch::Invoke method.

Values for the wFlags parameter include the following:

Value Description
DISPATCH_METHOD The member is being run as a method. If a property has the same name, both this and the DISPATCH_PROPERTYGET flag can be set.
DISPATCH_PROPERTYGET The member is being retrieved as a property or data member.
DISPATCH_PROPERTYPUT The member is being changed as a property or data member.
DISPATCH_PROPERTYPUTREF The member is being changed via a reference assignment, rather than a value assignment. This value is valid only when the property accepts a reference to an object.

Requirements

Requirement Value
Header
Winutil.h (include Streams.h)
Library
Strmbase.lib (retail builds);
Strmbasd.lib (debug builds)

See also

CCmdQueue Class