Inside Macintosh: QuickTime Components /

Chapter 11 - Clock Components / Clock Components Reference

Clock Component Functions / Using the Callback Functions

ClockCallMeWhen

Your clock component's ClockCallMeWhen function schedules a callback event for invocation. The Movie Toolbox calls this function when an application schedules a callback event using the CallMeWhen function of the Movie Toolbox (described in the chapter "Movie Toolbox" in Inside Macintosh: QuickTime).

The Movie Toolbox passes the parameter data from its CallMeWhen function to
your component in the param1, param2, and param3 parameters to this function. Your clock component interprets these parameters based on the value of the callBackType parameter to the ClockNewCallBack function (see page 11-9).

pascal ComponentResult ClockCallMeWhen (ComponentInstance aClock,
                                          QTCallBack cb, 
                                          long param1, 
                                          long param2, 
                                          long param3);

aClock

Specifies the clock for the operation. Applications obtain this identifier from the Component Manager's OpenComponent function.

cb

Specifies the callback event for the operation. The Movie Toolbox obtains this value from your component's ClockNewCallBack function.

param1

Contains data supplied to the Movie Toolbox in the param1 parameter to the CallMeWhen function. Your component interprets this parameter based on the value of the callBackType parameter to the ClockNewCallBack function.

If callBackType is set to callBackAtTime, param1 contains QuickTime callback flags indicating when to invoke the callback function. The following values are defined:

triggerTimeFwd

Indicates that the callback function should be called at the time specified by param2 only when time is moving forward (positive rate). The value of this flag is 0x0001.

triggerTimeBwd

Indicates that the callback function should be called at the time specified by param2 only when time is moving backward (negative rate). The value of this flag is 0x0002.

triggerTimeEither

Indicates that the callback function should be called at the time specified by param2 without regard to direction. The value of this flag is 0x0003.

If callBackType is set to callBackAtRate, param1 contains flags indicating when to invoke the callback function.

The following values are defined:

triggerRateChange

Indicates that the callback function should be called whenever the rate changes. The value of this flag is 0.

triggerRateLT

Indicates that the callback function should be called when the rate changes to a value less than that specified by param2. The value of this flag is 0x0004.

triggerRateGT

Indicates that the callback function should be called when the rate changes to a value greater than that specified by param2. The value of this flag is 0x0008.

triggerRateEqual

Indicates that the callback function should be called when the rate changes to a value equal to that specified by param2. The value of this flag is 0x0010.

triggerRateLTE

Indicates that the callback function should be called when the rate changes to a value that is less than or equal to that specified by param2. The value of this flag is 0x0014.

triggerRateGTE

Indicates that the callback function should be called when the rate changes to a value that is less than or equal to that specified by param2. The value of this flag is 0x0018.

triggerRateNotEqual

Indicates that the callback function should be called when the rate changes to a value that is not equal to that specified by param2. The value of this flag is 0x001C.

param2

Contains data supplied to the Movie Toolbox in the param2 parameter to the CallMeWhen function (see page 11-10). Your component interprets this parameter based on the value of the callBackType parameter to the ClockNewCallBack function, described on page 11-9.

If callBackType is set to callBackAtTime, param2 contains the time value at which your component should invoke the callback function for this event. The param1 parameter contains flags affecting when you should call the function.

If callBackType is set to callBackAtRate, param2 contains the rate value at which your component should invoke the callback function for this event. The param1 parameter contains flags affecting when you should call the function.

param3

Contains data supplied to the Movie Toolbox in the param3 parameter to the CallMeWhen function. If qtType is set to callBackAtTime, param3 contains the time scale in which to interpret the time value that is stored in param2.

DESCRIPTION

The Movie Toolbox maintains control information about the callback event. Your clock component only needs to maintain the invocation schedule. For example, the Movie Toolbox saves the address of the callback event, its reference constant, and the value of the A5 register. In addition, the Movie Toolbox prevents applications from scheduling a single callback event more than once.

If your clock component successfully schedules the callback event, you should call the AddCallBackToTimeBase function (described on page 11-16) to add it to the list of callback events for the corresponding time base. If your component cannot schedule
the callback event, it should return an appropriate error.