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 CCmdQueue::GetDueCommand member function (probably with a time-out of zero); this may return E_ABORT.
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:
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
| Name | Description |
| m_Lock | Protects access to lists. |
| m_listPresentation | Stores commands queued in presentation time. |
| m_listStream | Stores commands queued in stream time. |
| m_evDue | Sets the time when any commands are due. |
| m_dwAdvise | Advise identifier from the reference clock (zero if no outstanding advise). |
| m_tCurrentAdvise | Advise time is for this presentation time. |
| m_pClock | Current reference clock. |
| m_bRunning | Flag for running state; set TRUE when running. |
| m_StreamTimeOffset | Contains the stream time offset when m_bRunning is true. |
Member Functions
| Name | Description |
| CCmdQueue | Constructs a CCmdQueue object. |
| CheckTime | Determines if a given time is due. |
| GetDueHandle | Returns the event handle that will be signaled. |
Overridable Member Functions
| Name | Description |
| EndRun | Switches to stopped or paused mode. |
| GetCommandDueFor | Returns a pointer to a command that will be due for a given time. |
| GetDueCommand | Returns 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 | Creates an advise for the earliest time required. |
Constructs a CCmdQueue object.
CCmdQueue( );
No return value.
Determines if a specified time is due.
BOOL CheckTime(
CRefTime time,
BOOL bStream
);
Returns TRUE if the specified time has not yet passed.
Switches to the stopped or paused mode.
virtual HRESULT EndRun( );
Returns an HRESULT value.
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.
Returns a deferred command that is scheduled at a specified time.
virtual HRESULT GetCommandDueFor(
REFERENCE_TIME tStream,
CDeferredCommand **ppCmd
);
Returns an HRESULT value. Returns VFW_E_NOT_FOUND if no commands are due.
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.
Returns a pointer to the next command that is due.
virtual HRESULT GetDueCommand(
CDeferredCommand ** ppCmd,
long msTimeout
);
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.
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.
Returns the event handle to be signaled.
HANDLE GetDueHandle( );
Returns an HRESULT value.
Return the event handle whenever there are deferred commands that are due for execution (when CCmdQueue::GetDueCommand will not block).
The CDeferredCommand object calls this member function to add itself to the queue.
virtual HRESULT Insert(
CDeferredCommand* pCmd
);
Returns an HRESULT value.
Initializes a command to be run and returns a new CDeferredCommand object.
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
);
Returns S_OK if successful; otherwise, returns an error value and no object has been queued.
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:
| 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 may 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. |
The CDeferredCommand object calls this member function to remove itself from the queue.
virtual HRESULT Remove(
CDeferredCommand* pCmd
);
Returns an HRESULT value.
Switches to running mode so that commands that are deferred by the stream time can be run.
virtual HRESULT Run(
REFERENCE_TIME tStreamTimeOffset
);
Returns an HRESULT value.
During running mode, stream-time-to-presentation-time mapping is known.
Sets the clock used for timing.
virtual HRESULT SetSyncSource(
IReferenceClock* pIrc
);
Returns an HRESULT value.
Sets up a timer event with the reference clock.
void SetTimeAdvise(void);
No return value.
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.