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

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.

Syntax

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:

TRUE This is a periodic timer that will fire every time2 units until canceled.
FALSE This is a one-shot timer.

Return Value

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.

Syntax

REFERENCE_TIME Advise(
  const REFERENCE_TIME & rtTime
  );

Parameters

rtTime
Current reference time.

Return Value

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.

Syntax

CAMSchedule(
  HANDLE hEvent
  );

Parameters

hEvent
Event that CAMSchedule should fire if the advise time needs reevaluating.

Return Value

No return value.

CAMSchedule::GetAdviseCount

CAMSchedule Class

Retrieves the number of outstanding events.

Syntax

DWORD GetAdviseCount(void);

Return Value

Returns the number of outstanding events.

CAMSchedule::GetEvent

CAMSchedule Class

Retrieves the event handle to set if the advise time requires reevaluation.

Syntax

HANDLE GetEvent(void);

Return Value

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.

Syntax

REFERENCE_TIME GetNextAdviseTime(void);

Return Value

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.

Syntax

HRESULT Unadvise(
  DWORD dwAdviseCookie
  );

Parameters

dwAdviseToken
Identifier (cookie) of the link that is being reset. This is the value returned by CAMSchedule::AddAdvisePacket.

Return Value

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.

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.

TRUE	This is a periodic timer that will fire every time2 units until canceled.
FALSE	This is a one-shot timer.