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::AddAdvisePacket

CAMSchedule Class

Creates 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::Advise

CAMSchedule Class

Requests 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::CAMSchedule

CAMSchedule Class

Constructs 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::GetAdviseCount

CAMSchedule Class

Returns the number of outstanding events.

DWORD GetAdviseCount( );

Return Values

Returns the number of outstanding events.

---

CAMSchedule::GetEvent

CAMSchedule Class

Retrieves 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::GetNextAdviseTime

CAMSchedule Class

Checks 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::Unadvise

CAMSchedule Class

Removes 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.

Top of Page