CCmdQueue Class

The CCmdQueue class is a base class that provides a queue of CDeferredCommand objects and member functions to add, remove, check status, and invoke the queued commands. A CCmdQueue object is a part of an object that implements IQueueCommand methods. The filter graph manager implements IQueueCommand methods so that applications can queue commands to the filter graph. Filters that implement the IQueueCommand interface directly use this class. If you want to use CDeferredCommand objects, your queue must be derived from this class.

There are two modes of synchronization: coarse and accurate. In coarse mode, the application waits until a specified time arrives and then executes the command. In accurate mode, the application waits until processing begins on the sample that appears at the time, and then executes the command. The filter determines which one it will implement. The filter graph manager always implements coarse mode for commands that are queued at the filter graph manager.

If you want coarse synchronization, you probably want to wait until there is a command due, and then execute it. You can do this by calling CCmdQueue::GetDueCommand. If you have several things to wait for, get the event handle from CCmdQueue::GetDueHandle and then call CCmdQueue::GetDueCommand when this is signaled. stream time will advance only between calls to the CCmdQueue::Run and CCmdQueue::EndRun member functions. There is no guarantee that if the handle is set, there will be a command ready. Each time the event is signaled, call the GetDueCommand member function (probably with a time-out of zero); this can return E_ABORT if no command is ready.

If you want accurate synchronization, call the CCmdQueue::GetCommandDueFor member function and pass the samples you are about to process as a parameter. This returns the following:

A stream-time command due at or before that stream time.
A presentation-time command due at or before the presentation of the stream time. Do this only between the CCmdQueue::Run and CCmdQueue::EndRun member functions, because outside of this, the mapping from stream time to presentation time is not known.
Any presentation-time command due now.

If you want accurate synchronization for samples that might be processed during paused mode, you must use stream-time commands.

In all cases, commands remain queued until called or canceled. The setting and resetting of the event handle is managed entirely by this queue object.

Protected Data Members

m_bRunning Flag for running state; set TRUE when running.

m_dwAdvise Advise identifier from the reference clock (zero if no outstanding advise).

m_evDue Sets the time when any commands are due.

m_listPresentation Stores commands queued in presentation time.

m_listStream Stores commands queued in stream time.

m_Lock Protects access to lists.

m_pClock Current reference clock.

m_StreamTimeOffset Contains the stream time offset when m_bRunning is true.

m_tCurrentAdvise Advise time is for this presentation time.

Member Functions

CCmdQueue Constructs a CCmdQueue object.

CheckTime Determines if a given time is due.

GetDueHandle Retrieves the event handle that will be signaled.

Overridable Member Functions

EndRun Switches to stopped or paused mode.

GetCommandDueFor Retrieves a deferred command that is scheduled at a specified time.

GetDueCommand Retrieves a pointer to the next command that is due.

Insert Adds the CDeferredCommand object to the queue.

New Initializes a command to be run and returns a new CDeferredCommand object.

Remove Removes the CDeferredCommand object from the queue.

Run Switches to running mode.

SetSyncSource Sets the clock used for timing.

SetTimeAdvise Sets up a timer event with the reference clock.

CCmdQueue::CCmdQueue

CCmdQueue Class

Constructs a CCmdQueue object.

Syntax

CCmdQueue(void);

Return Value

No return value.

CCmdQueue::CheckTime

CCmdQueue Class

Determines if a specified time is due.

Syntax

BOOL CheckTime(
    CRefTime time,
    BOOL bStream
    );

Parameters

time
Time to check.
bStream
TRUE if the time parameter is a stream-time value; FALSE if time is a presentation-time value.

Return Value

Returns TRUE if the specified time has not yet passed.

CCmdQueue::EndRun

CCmdQueue Class

Switches to the stopped or paused mode.

Syntax

virtual HRESULT EndRun(void);

Return Value

Returns an HRESULT value that depends on the implementation. The HRESULT indicates the error and can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
S_OK or NOERROR Success.

Remarks

Time mapping between stream time and presentation time is not known after this member function has been called. Call the CCmdQueue::Run member function to carry out this mapping.

CCmdQueue::GetCommandDueFor

CCmdQueue Class

Retrieves a deferred command that is scheduled at a specified time.

Syntax

virtual HRESULT GetCommandDueFor(
    REFERENCE_TIME tStream,
    CDeferredCommand **ppCmd
    );

Parameters

tStream
Time for which the command is scheduled.
ppCmd
Address of a pointer to the deferred command to be carried out at the time specified in the tStream parameter.

Return Value

Returns VFW_E_NOT_FOUND if no commands are due; otherwise, returns S_OK.

Remarks

This member function takes a stream time and returns the deferred command scheduled at that time. The actual stream-time offset is calculated when the command queue is run. Commands remain queued until run or canceled. This member function will not block.

CCmdQueue::GetDueCommand

CCmdQueue Class

Retrieves a pointer to the next command that is due.

Syntax

virtual HRESULT GetDueCommand(
    CDeferredCommand **ppCmd,
    long msTimeout
    );

Parameters

ppCmd
Address of a pointer to the deferred command.
msTimeout
Amount of time to wait before carrying out the time-out.

Return Value

Returns E_ABORT if a time-out occurs. Returns S_OK if successful; otherwise, returns an error. Returns an object that has been incremented using IUnknown::AddRef.

Remarks

This member function blocks until a pending command is due. The member function blocks for the amount of time, in milliseconds, specified in the msTimeout parameter. Stream-time commands become due only between the CCmdQueue::Run and CCmdQueue::EndRun member functions. The command remains queued until run or canceled.

CCmdQueue::GetDueHandle

CCmdQueue Class

Retrieves the event handle to be signaled.

Syntax

HANDLE GetDueHandle(void);

Return Value

Returns the event handle.

Remarks

Return the event handle whenever there are deferred commands that are due for execution (when CCmdQueue::GetDueCommand will not block).

CCmdQueue::Insert

CCmdQueue Class

Adds the CDeferredCommand object to the queue.

Syntax

virtual HRESULT Insert(
    CDeferredCommand *pCmd
    );

Parameters

pCmd
Pointer to the CDeferredCommand object to add to the queue.

Return Value

Returns S_OK in the default implementation.

CCmdQueue::New

CCmdQueue Class

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 OLE 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 OLE IDispatch::Invoke method.
Values for the wFlags parameter include the following:

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.

CCmdQueue::Remove

CCmdQueue Class

Removes the CDeferredCommand object from the queue.

Syntax

virtual HRESULT Remove(
    CDeferredCommand *pCmd
    );

Parameters

pCmd
Pointer to the CDeferredCommand object to remove from the queue.

Return Value

Returns VFW_E_NOT_FOUND if the object is not found in the queue. Otherwise, returns S_OK.

CCmdQueue::Run

CCmdQueue Class

Switches to running mode so that commands that are deferred by the stream time can be run.

Syntax

virtual HRESULT Run(
    REFERENCE_TIME tStreamTimeOffset
    );

Parameters

tStreamTimeOffset
Offset time.

Return Value

Returns S_OK in the default implementation.

Remarks

During running mode, stream-time-to-presentation-time mapping is known.

CCmdQueue::SetSyncSource

CCmdQueue Class

Sets the clock used for timing.

Syntax

virtual HRESULT SetSyncSource(
    IReferenceClock *pIrc
    );

Parameters

pIrc
Pointer to the IReferenceClock interface.

Return Value

Returns S_OK in the default implementation.

CCmdQueue::SetTimeAdvise

CCmdQueue Class

Sets up a timer event with the reference clock.

Syntax

void SetTimeAdvise(void);

Return Value

No return value.

Remarks

This member function calls the IReferenceClock::AdviseTime method to set up a notification for the earliest time required in the queue. Presentation-time commands that are deferred are always checked. If the filter graph is in running mode, deferred commands using stream time are also checked.

m_bRunning	Flag for running state; set TRUE when running.
m_dwAdvise	Advise identifier from the reference clock (zero if no outstanding advise).
m_evDue	Sets the time when any commands are due.
m_listPresentation	Stores commands queued in presentation time.
m_listStream	Stores commands queued in stream time.
m_Lock	Protects access to lists.
m_pClock	Current reference clock.
m_StreamTimeOffset	Contains the stream time offset when m_bRunning is true.
m_tCurrentAdvise	Advise time is for this presentation time.

CCmdQueue	Constructs a CCmdQueue object.
CheckTime	Determines if a given time is due.
GetDueHandle	Retrieves the event handle that will be signaled.

EndRun	Switches to stopped or paused mode.
GetCommandDueFor	Retrieves a deferred command that is scheduled at a specified time.
GetDueCommand	Retrieves a pointer to the next command that is due.
Insert	Adds the CDeferredCommand object to the queue.
New	Initializes a command to be run and returns a new CDeferredCommand object.
Remove	Removes the CDeferredCommand object from the queue.
Run	Switches to running mode.
SetSyncSource	Sets the clock used for timing.
SetTimeAdvise	Sets up a timer event with the reference clock.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
S_OK or NOERROR	Success.

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.