Index Topic Contents | |||
Previous Topic: CAMMsgEvent Class Next Topic: CAMThread Class |
CAMSchedule Class
The CAMSchedule class relieves clocks from the burden of managing the advise requests. A clock can delegate such management to this class, provided that it calls this class's Advise method when the earliest event should be fired. The application can fetch the time of the earliest event by calling GetNextAdviseTime, or the application can track events by a combination of the times returned by Advise and the event times that the clock adds.
Member Functions
Name Description AddAdvisePacket Creates a new pending notification. Advise Requests the scheduler to dispatch all events up to and including the time specified. CAMSchedule Constructs a CAMSchedule object. GetAdviseCount Returns the number of outstanding events. GetEvent Returns the event handle to send if the advise time requires reevaluation. GetNextAdviseTime Returns the reference time at which the next advise should be set, or MAX_TIME if no events are scheduled. Unadvise Removes a previously established advise link. CAMSchedule Class
CAMSchedule::AddAdvisePacketCreates a new pending notification and adds it to the advise notification list.
DWORD AddAdvisePacket(
const REFERENCE_TIME & time1,
const REFERENCE_TIME & time2,
HANDLE hNotify,
BOOL bPeriodic
);Parameters
- time1
- Time that the advise should take place.
- time2
- Period between notifications. (Ignored if bPeriodic is FALSE.)
- hNotify
- Notification mechanism. Either a semaphore handle (if bPeriodic is TRUE) or an event handle.
- bPeriodic
- Flag that specifies whether the notification is sent repeatedly, or whether the notification is sent once. This can be one of the following values:
Value Meaning TRUE This is a periodic timer that will fire every time2 units until canceled. FALSE This is a one-shot timer. Return Values
Returns the advise token if successful, or zero if an error occurred.
CAMSchedule Class
CAMSchedule::AdviseRequests the scheduler to dispatch all events up to and including the time specified. This method is expected to be called by a controlling clock specifying the current time, just in time to dispatch the next advise request.
REFERENCE_TIME Advise(
const REFERENCE_TIME & rtTime
);Parameters
- rtTime
- Current reference time.
Return Values
Returns the reference time at which the next advise will expire, or MAX_TIME if there are no outstanding events.
Remarks
Clocks can call this method to advise the scheduler of the time. The scheduler will then signal all the events that have expired, and reschedule the periodic ones.
It is not intended that clocks should call this method all the time, rather that clocks will call Advise just one time. The time returned will be invalidated if you start adding extra advises.
CAMSchedule Class
CAMSchedule::CAMScheduleConstructs a CAMSchedule object.
CAMSchedule(
HANDLE hEvent
);Parameters
- hEvent
- Event that CAMSchedule should fire if the advise time needs reevaluating.
Return Values
No return value.
CAMSchedule Class
CAMSchedule::GetAdviseCountReturns the number of outstanding events.
DWORD GetAdviseCount( );
Return Values
Returns the number of outstanding events.
CAMSchedule Class
CAMSchedule::GetEventRetrieves the event handle to set if the advise time requires reevaluation.
HANDLE GetEvent( );
Return Values
Returns a HANDLE to the event to set when this object's advise time requires reevaluation.
CAMSchedule Class
CAMSchedule::GetNextAdviseTimeChecks the time of the next advise.
REFERENCE_TIME GetNextAdviseTime( );
Return Values
Returns the reference time at which the next advise should be set, or MAX_TIME if there are no events scheduled.
CAMSchedule Class
CAMSchedule::UnadviseRemoves a previously established advise link.
HRESULT Unadvise(
DWORD dwAdviseCookie
);Parameters
- dwAdviseToken
- Identifier (cookie) of the link that is being reset. This is the value returned by CAMSchedule::AddAdvisePacket.
Return Values
Returns S_OK if successful; otherwise, returns S_FALSE.
Remarks
This member function is modeled after the IReferenceClock::Unadvise method. Call Unadvise to remove the previously established clock advise links.
Unadvise should be called for unexpired single-shot advise requests. Calling Unadvise with the token of an already expired event causes no problems, so applications can choose to always call Unadvise on their single-shot events without fear of problems.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.